Backstage 软件目录同步

服务元数据为什么需要一条同步链路

当平台团队超过十几个时，"服务到底在哪、谁在维护、依赖了哪些上游"这类问题就会从"翻文档"退化成"靠记忆"。Backstage 的 Software Catalog 是解决这类问题的常见选择，但它只提供存储与展示，真正让目录保持新鲜的是同步链路：你要么手工在界面里点 Add Component，要么在 CI 里写脚本拼命令。前者无法规模化，后者每个人写出来的 catalog-info.yaml 格式都不统一。

这个技能要解决的就是这一步：把 catalog-info.yaml 的生成和 Catalog REST API 的调用封装成一条可重复的同步流程，让服务元数据能从代码仓库流向 Backstage，并保持组件、API、系统三层实体关系的正确。

它具体做什么

• 生成实体描述：基于服务代码仓库或配置，产出符合 Backstage 目录规范的 catalog-info.yaml，包含实体类型（Component、API、System）与元数据字段。
• 调用 Catalog API：通过 Backstage Catalog REST API 提交实体，完成注册或更新，而不是人工在 UI 里逐个录入。
• 维护实体关系：在 YAML 中声明 owner、type、dependsOn 等字段，使目录中能呈现团队间组件、API 和系统之间的依赖关系图。

使用上的边界

• 技能只负责写入与更新目录数据，不包含 Backstage 前端组件的部署，也不处理实体删除后的级联清理。
• Catalog API 的地址、访问令牌、命名空间策略需要在运行环境中自行配置，技能本身不内置鉴权信息。
• 如果仓库结构与 Backstage 的命名规范差异较大，catalog-info.yaml 仍需要人工校正后才能提交。
• 同步频率取决于调用方的调度方式，技能不提供常驻定时同步能力。