企业官网建设流程全解析

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

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

本指南介绍如何在 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 常用字段

Component 特有的 spec 字段

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

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

你可能好奇：为什么合并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 字段规范
• 实体的生命周期：摄取、处理与缝合的内部机制

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage