Backstage Orphan Clean Up定位并批量删除 Catalog 孤儿实体的实战指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 的 Software Catalog 在处理失败或引用丢失时会把实体标记为孤儿orphan这些残留实体会长期占据目录并干扰搜索与权限判定。本文围绕仓库中contrib/scripts/orphan-clean-up/目录贡献的孤儿清理脚本展开完整讲解 PowerShell 与 Bash 两套脚本的使用方法、所依赖的 Catalog REST API以及孤儿注解在后端源码中是如何产生的帮助你在生产环境安全地批量清掉这些无效实体。什么是孤儿实体backstage.io/orphan注解的由来在理解清理脚本之前先要弄清孤儿实体这个概念在 Backstage 中的准确定义。从源码结构看孤儿的判定发生在后端缝合stitching阶段。performStitching.ts 中的关键逻辑是当某个实体的入边引用计数为 0 时即没有任何其他实体通过owns、partOf、dependsOn等关系指向它它就是一条孤儿记录随后被强制写入注解const isOrphan Number(incomingReferenceCount) 0; // ... if (isOrphan) { logger.debug(${entityRef} is an orphan); entity.metadata.annotations { ...entity.metadata.annotations, [backstage.io/orphan]: true, }; }也就是说只要实体满足入边引用计数为零这一条件backstage.io/orphan: true注解就会被附加到该实体上并在 Catalog API 中随实体一起暴露。清理脚本正是基于这一注解来筛选目标的——这也是理解整套脚本工作机制的起点。同时后端还内置了一套数据库层面的孤儿回收工具 deleteOrphanedEntities.ts它会在refresh_state表中查找没有入边引用的实体行并级联删除最多迭代 100 轮以保证收敛源码注释原文Limit iterations for sanity。贡献脚本与这套内部机制解决的是同一个问题但面向的是运维场景当数据库层面的清理未能覆盖所有情况或者你希望先看一眼再删时直接调用公开 REST API 的脚本更透明、更可控。前提与风险警告务必先读README 中有两条明确的约束使用脚本前必须确认API 端点未配置认证。脚本通过匿名 HTTP 请求调用/api/catalog/entities相关端点因此它假设你的 Backstage 实例的 Catalog API 没有开启认证。如果你的部署启用了 JWT 校验需要自行在curl/Invoke-RestMethod请求中追加Authorization头。误删风险。README 中的原文警告当某个 location 自身出现故障例如返回 404时由它提供的实体会暂时变为孤儿并被标记此时若运行清理脚本可能把本应存活的实体误删直到处理循环重新拉取并重建该实体。因此建议在执行删除前先核对脚本打印出的实体列表确认没有误伤。PowerShell 版OrphanCleanUp.ps1运行要求脚本基于 PowerShell 编写必须在 PowerShell 会话中执行。README 也指出如果你无法使用 PowerShell脚本的逻辑足够简单可以直接照搬到 Bash、Python 等任意其他语言实现。使用步骤下载 OrphanCleanUp.ps1启动一个 PowerShell 会话cd到脚本所在目录执行以下命令把示例 URL 替换为你的 Backstage 实例地址.\OrphanCleanUp.ps1 https://backstage.my-company.com脚本会先输出找到的孤儿实体总数然后逐个打印正在删除的实体名称与类型kind。脚本源码解析整个脚本只有 22 行核心逻辑如下完整内容见 OrphanCleanUp.ps1param( [string]$backstageUrl http://localhost:7007 # 缺省指向本地开发后端 ) $orphanApiUrl $backstageUrl/api/catalog/entities?filtermetadata.annotations.backstage.io/orphantrue $orphanDeleteApiUrl $backstageUrl/api/catalog/entities/by-uid $orphans Invoke-RestMethod -Method Get -Uri $orphanApiUrl Write-Host Found $($orphans.length) orphaned entities foreach($orphan in $orphans){ Write-Host Deleting orphan $($orphan.metadata.name) of kind $($orphan.kind) Invoke-RestMethod -Method Delete -Uri $orphanDeleteApiUrl/$($orphan.metadata.uid) }三个要点参数缺省值$backstageUrl的默认值是http://localhost:7007即 Backstage 本地开发后端的标准端口方便开发期直接试跑查询接口GET /api/catalog/entities?filtermetadata.annotations.backstage.io/orphantrue利用 Catalog 查询 API 的filter参数按注解精确筛选孤儿删除接口DELETE /api/catalog/entities/by-uid/{uid}按实体的唯一标识 UID 逐个删除。Bash 版orphan_cleanup.sh运行要求Bash 脚本orphan_cleanup.sh依赖两个外部工具curl发起 HTTP 请求jq解析与遍历 JSON 响应。脚本开头使用set -euo pipefail任一命令失败都会立即终止避免在异常状态下继续批量删除。使用步骤下载 orphan_cleanup.sh启动一个 Bash 会话cd到脚本所在目录执行以下命令并替换为你的实例地址./orphan_cleanup.sh https://backstage.my-company.com脚本输出找到的孤儿实体数量然后逐条打印被删除实体的完整 JSON、名称与类型。脚本源码解析BACKSTAGE_URL${1:-http://localhost:7007} ORPHAN_API_URL$BACKSTAGE_URL/api/catalog/entities?filtermetadata.annotations.backstage.io/orphantrue ORPHAN_DELETE_API_URL$BACKSTAGE_URL/api/catalog/entities/by-uid ORPHANS$(curl -s $ORPHAN_API_URL) echo Found $(echo $ORPHANS | jq length ) orphaned entities jq -c .[] $ORPHANS | while read ORPHAN; do echo Deleting orphan entity: $(echo $ORPHAN | jq -r .metadata.name) of kind: $(echo $ORPHAN | jq -r .kind) curl -X DELETE $ORPHAN_DELETE_API_URL/$(echo $ORPHAN | jq -r .metadata.uid) done与 PowerShell 版相比Bash 版在删除前额外echo了实体的完整 JSONecho $ORPHAN | jq .相当于删除前的留痕便于事后审计。两版脚本的第一参数缺省值同为http://localhost:7007行为完全对齐。脚本依赖的两个 Catalog REST 端点两个脚本本质上只用了 Catalog API 的两个端点二者都在 Catalog 后端 OpenAPI 定义 中有完整契约端点方法operationId说明/api/catalog/entities?filter...GETGetEntitiesByQuery按filter表达式查询实体脚本用metadata.annotations.backstage.io/orphantrue精确命中孤儿/api/catalog/entities/by-uid/{uid}DELETEDeleteEntityByUid按 UID 删除单个实体成功返回204 No Content值得注意的是 OpenAPI 中这两个操作均声明了security为无凭据或 JWT即security: [ {}, JWT: []。在默认未启用认证部署下脚本可直接匿名调用一旦启用 JWT则需要为curl补上-H Authorization: Bearer token、为Invoke-RestMethod补上对应的-Headers参数否则会收到 401。另外OpenAPI 文档中对filter参数本身给出了官方示例其中就包含按孤儿注解过滤的用法kindcomponent,metadata.annotations.backstage.io/orphantrue说明这一筛选路径是被官方 API 文档认可的常规手段而非脚本的野路子。与后端内置清理机制的分工仓库中孤儿相关的代码共有两层理解它们的分工能帮你判断该用哪种手段数据库层自动回收deleteOrphanedEntities.ts 在数据库事务中直接删除refresh_state表里没有入边引用的行并把曾经引用它的实体标记为待重新缝合markForStitching。这是后端在正常数据流中自动执行的内部机制运维人员无需也无法直接调用。API 层手动清理本文脚本面向运维人员的显式操作先查询再逐个删除全程可观察、可中断、可审计适合在 location 故障恢复后清理历史残留或在迁移、下线业务线后做一次性清库。可以推断脚本存在的意义在于提供一个API 视角的兜底手段它不触碰数据库完全走公开 REST 接口因此对数据库实现PostgreSQL/SQLite无侵入也不会绕过权限与审计边界。落地检查清单综合 README 的警告与源码事实执行清理前建议按以下清单确认确认目标实例--help式的快速验证可以先手动curl $BACKSTAGE_URL/api/catalog/entities?filtermetadata.annotations.backstage.io/orphantrue检查返回的 JSON 数组内容是否全部是预期删除对象确认 location 健康先排查 Catalog 处理队列中是否有长时间失败的 location返回 404 的 location 会让其实体被误标为孤儿确认认证模式匿名 API 还是 JWT按需为脚本请求追加认证头小步执行脚本没有内置仅列出、不删除的 dry-run 模式若想在删除前只预览名单可以先单独执行查询请求并保存输出再决定是否运行删除留痕Bash 版会逐条打印实体 JSON建议将标准输出重定向到日志文件作为删除操作的审计记录。小结Backstage 的孤儿清理脚本PowerShell 版 / Bash 版虽然只有 20 来行却精确踩中了 Catalog 的两个核心机制stitching 阶段写入的backstage.io/orphan注解以及by-uid删除端点。它把发现孤儿 → 逐个删除这条运维链路压缩成了单命令操作同时保持了足够的透明度总数统计、逐条日志。对于任何需要定期治理 Catalog 数据质量的团队把它纳入运维手册、并配合 location 健康检查一起使用就是最稳妥的做法。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考