Backstage 软件目录组件更新指南：通过编辑 catalog-info.yaml 完成组件信息变更

本指南介绍如何在 Backstage 软件目录（Software Catalog）中更新一个已有组件。Backstage 中的组件实体由软件模板创建，模板会在 GitHub 或 GitLab 仓库中生成一份名为 catalog-info.yaml 的实体定义文件，因此更新组件的本质就是编辑其对应的 catalog-info.yaml 实体定义文件。读完本文，你将掌握在 Backstage UI 中完成组件信息编辑、提交、走 PR 评审并最终同步回软件目录的完整流程，并理解该文件背后的实体描述符格式与目录处理机制。

更新机制概览：为什么“更新组件”等于“编辑 YAML”

在 Backstage 的软件目录中，组件（Component）的创建通常经由软件模板（Software Template）完成。模板会生成一个 catalog-info.yaml 文件并发布到 GitHub 或 GitLab 仓库，该文件定义了实体的全部关键信息，例如组件名称、类型、生命周期阶段和负责人等。

因此，更新一个组件时，你并不需要操作任何独立的“组件配置界面”，而是修改仓库中该组件对应的 catalog-info.yaml 实体定义文件。软件目录的后台会持续监听这些文件的变化：当你在分支上提交修改并通过 PR 合并到组件关联的分支后，目录会自动重新摄取（ingest）并处理该实体，最终在 Backstage UI 中呈现更新后的信息。

动手前请确保你已经：

• 完成了独立应用的安装，参见独立安装指南；
• 拥有一个已通过模板创建并注册进目录的组件（参见创建组件和注册组件）；
• 具备该组件仓库的修改权限（能够提交并合并变更）。

使用 Backstage UI 更新组件

以下步骤以 tutorial 实体为例，展示完整的更新流程。

第 1 步：选择组件的“编辑”图标

在目录中打开目标组件，点击与组件关联的 Edit（编辑） 图标：

随后，与该组件关联的 catalog-info.yaml 文件会被显示出来，你可以在界面中直接查看并编辑其内容：

第 2 步：修改 YAML 文件内容

在打开的 YAML 编辑器中做出你想要的修改。例如，将组件的 metadata.name 从 tutorial 修改为 mytutorial：

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: 'mytutorial'
spec:
  type: service
  owner: user:guest
  lifecycle: experimental

需要注意的是，metadata.name 是实体的唯一标识，它同时被人类识别与机器引用（如 URL、其他实体的引用）所使用，因此修改名称会产生全局影响。除了名称，你还可以在此处调整 description、labels、annotations、tags、links 以及 spec 下的各类字段。

第 3 步：提交更改并走 PR 评审流程

完成修改后，选择 Commit changes（提交更改） 将变更提交到合适的分支，然后走你团队常规的 PR（Pull Request）评审流程。这一步与日常的代码评审一致，任何评审意见都应在合并前解决。

第 4 步：合并后查看目录中的更新结果

一旦更新后的 catalog-info.yaml 被合并到组件关联的分支，软件目录会自动同步，你将在软件目录中看到更新后的组件信息：

认识 catalog-info.yaml：组件实体描述文件

要想高效地编辑 catalog-info.yaml，理解其实体描述符格式（Descriptor Format）很有必要。完整的格式说明见目录实体描述符格式，这里摘取与组件更新最相关的核心内容。

一份典型的 Component 描述文件结构如下：

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: artist-web
  description: The place to be, for great artists
  labels:
    example.com/custom: custom_label_value
  annotations:
    example.com/service-discovery: artistweb
    circleci.com/project-slug: github/example-org/artist-website
  tags:
    - java
  links:
    - url: https://admin.example-org.com
      title: Admin Dashboard
      icon: dashboard
      type: admin-dashboard
spec:
  type: website
  lifecycle: production
  owner: artist-relations-team
  system: public-websites

信封字段（Envelope）

根部的 apiVersion、kind、metadata、spec 构成实体的“信封”，定义了所有类型实体共有的整体结构：

• apiVersion（必填）：实体规范格式的版本，Backstage 实体以 backstage.io/ 前缀区分于其他同构对象（如 Kubernetes 清单），当前目录实体普遍使用 backstage.io/v1alpha1；
• kind（必填）：实体的高层类型，本指南场景下为 Component。Backstage 的核心类型由 ADR005 核心实体 定义，组织也可以自由添加自有类型；
• metadata（必填）：实体本身的元数据（名称、描述、标签、注解等），不属于实体规范本身；
• spec（因类型而异）：描述实体的实际规范数据，其结构取决于 apiVersion 与 kind 的组合。

metadata 常用字段

字段	必填	说明
name	是	实体名称，须在同一命名空间下按 kind 唯一（不区分大小写），长度为 1～63，由 [a-z0-9A-Z] 组成、可用 [-_.] 分隔
namespace	否	实体所属命名空间，默认 default；跨命名空间引用时使用 <namespace>/<name> 语法
title	否	展示名称，UI 中优先显示它而非 name，格式限制更宽松但务必保持简短
description	否	人类可读的描述，保持简短信息性
labels	否	键值对形式的分类信息，键的 backstage.io/ 前缀为 Backstage 保留
annotations	否	任意非标识性元数据，常用于引用外部系统（监控、日志、PagerDuty 等）
tags	否	单值字符串列表（如 java、go），由 [a-z0-9:+#] 组成、用 - 分隔
links	否	外部超链接列表，每个链接包含 url（必填）、title、icon、type 字段

Component 特有的 spec 字段

字段	必填	说明
spec.type	是	组件类型，如 service、website、library；目录接受任意值，但建议组织建立规范分类体系
spec.lifecycle	是	生命周期状态，常见取值 experimental、production、deprecated
spec.owner	是	组件负责人的实体引用，默认为 Group 类型，如 artist-relations-team
spec.system	否	组件所属系统的实体引用，生成 partOf/hasPart 关系
spec.subcomponentOf	否	组件所属父组件的实体引用
spec.providesApis	否	组件提供的 API 实体引用数组，生成 providesApi/apiProvidedBy 关系
spec.consumesApis	否	组件消费的 API 实体引用数组，生成 consumesApi/apiConsumedBy 关系
spec.dependsOn	否	组件依赖的组件/资源引用数组，生成 dependsOn/dependencyOf 关系
spec.dependencyOf	否	依赖该组件的组件/资源引用数组

完整的关系类型语义可参见已知关系列表。

更新后的生效链路：从仓库合并到目录刷新

你可能好奇：为什么合并 catalog-info.yaml 后目录会自动更新？这背后的机制记录在实体的生命周期文档中。软件目录后端由三条流水线驱动：

1. 摄取（Ingestion）：实体提供者（Entity Provider）从外部权威源（如你注册的 YAML 文件 URL）拉取原始实体数据并写入数据库。通过 Create 按钮或 app-config 注册的 YAML 文件 URL 都由实体提供者管理；
2. 处理（Processing）：处理器（Processor）循环校验、分析并加工原始实体数据，可能产出子实体、错误以及到其他实体的关系。当你在 UI 中把 name 从 tutorial 改成 mytutorial 并合并后，处理循环会重新读取文件并更新数据库中的实体；若 YAML 语法错误，错误会以状态条目（如 backstage.io/catalog-processing）的形式附加到实体上；
3. 缝合（Stitching）：汇总处理阶段产出的实体体、错误与全部关系（包括其他处理步骤指向本实体的关系），组装成最终对外可见的实体，并同步刷新目录过滤所用的索引表。

从源码结构看，目录的读取、处理与过滤逻辑集中在 plugins/catalog-backend（后端处理与 API）与 plugins/catalog-react（前端展示与过滤）中；UI 中关于实体的展示信息（About 卡片等）位于 plugins/catalog/src/components/AboutCard/AboutCard.tsx，是你在编辑后查看更新结果时会直接打交道的界面组件。

更新时的注意事项

• 改名需谨慎：name 被实体引用（Entity Reference）与 URL 引用，修改后任何指向旧名称的引用（如其他实体的 spec.owner、dependsOn）都会失效，需要同步排查；
• 使用命名空间隔离重名：如果同一 kind 下出现重名风险，可在 metadata.namespace 中指定命名空间，引用时使用 <namespace>/<name> 语法；
• 删除文件不等于更新：删除或损坏 catalog-info.yaml 并不会导致实体被自动移除，而是会在实体上标记错误或使其“孤儿化”（orphaning）。若你希望彻底移除组件，请遵循注销与删除组件指南，其中解释了隐式删除与显式删除的区别，以及必须同时删除实体定义文件的前置条件。

相关指南

• 创建组件：通过模板创建组件并生成 catalog-info.yaml
• 注册组件：将已存在的 YAML 文件注册进目录
• 注销与删除组件：从目录中移除实体
• 目录实体描述符格式：完整的 YAML/JSON 字段规范
• 实体的生命周期：摄取、处理与缝合的内部机制