企业官网建设流程全解析

Backstage 组件注册实战：将 catalog-info.yaml 实体导入软件目录

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

本篇技术指南围绕 Backstage 官方文档 docs/getting-started/register-a-component.md 展开，系统讲解如何通过界面手动将外部数据（实体描述文件或整个仓库）注册进 Backstage 的软件目录（Software Catalog）。读完本文，你将掌握两种注册方式的完整操作流程、背后catalog-import插件的分析原理，以及catalog-info.yaml描述文件的字段语义，能够独立为你的组织接入第一批目录实体。

前置条件

• 已经按照 独立安装指南 安装并运行了一个 Backstage 应用（Standalone App）。官方安装命令为npx @backstage/create-app@latest，随后进入应用目录执行yarn start，应用默认运行在http://localhost:3000，后端在http://localhost:7007。
• 需要理解基本的 YAML 语法。Backstage 的实体描述文件（entity file）以 YAML 格式存储，不了解 YAML 的读者建议先补充相关基础。
• 本文默认使用的是带演示数据（demo content）的本地环境，数据存储于内存 SQLite，适合评估、开发和演示，并非生产级安装。

实体描述文件的完整字段规范参见 软件目录实体的描述格式（Descriptor Format of Catalog Entities），本文第三节会对其中最核心的部分进行展开。

两种注册方式总览

注册组件（Register a Component）的本质是：告诉 Backstage 软件目录去哪里读取数据，以及如何把读到的实体加载进目录。官方文档指出，注册组件有两种方式：

针对第二种方式，官方文档有一条重要提示：

如果在仓库中没有找到任何实体，系统会创建一个 Pull Request，向仓库中添加一个示例catalog-info.yaml文件。当该 Pull Request 被合并后，目录就会加载其中定义的全部实体。

这意味着"链接到仓库"既是一条数据导入通道，也是一个帮助仓库"补上元数据"的引导机制。

手动注册组件的完整操作步骤

按照官方文档，在软件目录中手动注册组件的步骤如下：

1. 选择Create（创建入口）。

2. 选择REGISTER EXISTING COMPONENT（注册已有组件）。

3. 填写模板。独立安装的 Backstage 应用自带一个模板。例如输入实体文件的仓库 URL：https://github.com/backstage/backstage/blob/master/catalog-info.yaml，该地址也用于官方 demo 站点 的目录。

4. 选择ANALYZE（分析）。系统会对 URL 进行预分析（dry-run），判断 URL 指向的是单个实体文件还是整个仓库，并列出将要导入的实体清单。

5. 如果ANALYZE的分析结果正确，选择IMPORT（导入）。导入成功后，界面会展示该实体的详情页。

6. 选择Home回到软件目录首页，即可看到新注册的实体出现在目录列表中。

界面中输入框的占位提示就是https://github.com/backstage/backstage/blob/master/catalog-info.yaml，这一点可以在前端源码中得到印证——在 StepInitAnalyzeUrl.tsx 中，exampleLocationUrl的默认值正是该 URL，并且输入框校验规则要求 URL 必须以http://或https://开头。

源码视角：ANALYZE 与 IMPORT 背后发生了什么

UI 上的一步步操作，对应的核心逻辑位于catalog-import插件中。阅读 CatalogImportClient.ts 的analyzeUrl方法，可以看到分析流程的关键分叉：

1. 识别 URL 是否指向实体文件：代码检查 URL 路径是否以.yaml/.yml结尾，或查询参数path是否匹配该模式。若是，则调用目录 API 的addLocation({ type: 'url', target: url, dryRun: true })进行试运行（dry-run）添加，返回locations类型的结果（含exists标记和实体清单），这就是ANALYZE步骤在"预览"阶段做的事情——此时并不会真正写入数据。
2. 否则按仓库处理：代码通过scmIntegrationsApi.byUrl(url)查找已配置的 SCM 集成。从源码看，仓库级发现目前只支持 GitHub 和 Azure DevOps两种集成类型；如果 URL 的主机没有匹配到任何已配置集成，会抛出错误，提示"该 URL 未被识别为有效的 git URL……你可以改为粘贴指向catalog-info.yaml文件的完整 URL"。
3. 调用分析接口：对于仓库 URL，前端会向目录后端发送POST /catalog/analyze-location请求，并带上catalog.import.entityFilename配置（默认catalog-info.yaml），由后端在仓库中扫描该文件。
4. 根据结果分流：
   • 若仓库中已存在实体文件，返回locations类型结果（一个文件对应一个 location），前端进入"单 location / 多 location"流程；
   • 若仓库中没有实体文件，返回repository类型结果，并携带generatedEntities（自动生成的示例实体）。此时前端进入"no-location"流程，即官方文档提到的自动创建 Pull Request分支。

IMPORT对应的是把分析结果正式提交：在submitPullRequest中，系统会先用catalogApi.validateEntity校验 YAML 实体是否合法，再根据集成类型调用 GitHub 或 Azure DevOps 的接口提交 PR，PR 标题形如Add catalog-info.yaml config file，正文会说明"合并此 PR 后组件将加入软件目录"。这一流程与 StepInitAnalyzeUrl.tsx 中single-location、multiple-locations、no-location三种ImportFlows一一对应。

理解实体描述文件：catalog-info.yaml 的核心结构

无论通过哪种方式注册，最终进入目录的都是实体描述文件中的数据。因此，理解描述文件的格式是注册动作的"内功"。以下内容来自官方文档 软件目录实体的描述格式，摘取其与注册最相关的部分。

实体的整体骨架（Envelope）

每个实体由四个根字段构成：

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

• apiVersion：实体规范格式的版本号，Backstage 自有实体以backstage.io/为前缀，早期阶段使用backstage.io/v1alpha1之类的 alpha/beta 版本，之后会演进到backstage.io/v1。
• kind：实体类型，即Component、API、System、Group、User、Resource、Domain、Template、Location等。apiVersion与kind的组合足以让解析器判断如何解释其余数据。
• metadata：实体元数据（详见下文）。
• spec：实体规格数据，其结构随apiVersion/kind组合而变，有些 kind 甚至可以没有spec。

在 API 的请求/响应周期中使用 JSON 表示，而描述文件使用 YAML 便于人工维护，二者结构与语义一致。

metadata 中具有特殊语义的字段

relations 与 status：只读字段

• relations是只读的实体间关系列表（如ownedBy、partOf），描述文件不应包含该字段，而是由目录处理器（catalog processors）分析实体描述数据及其周边环境后自动推导并附加。例如spec.owner为dev.infra时，处理器会生成"relations": [{"type": "ownedBy", "targetRef": "group:default/dev.infra"}]。
• status同样是只读的状态集合，当前主要用途是让目录自身的摄取过程向用户反馈错误与警告（如backstage.io/catalog-processing类型的错误状态）。描述文件也不应包含该字段。

Component kind 的关键 spec 字段

注册时最常见的实体类型就是 Component。其关键 spec 字段如下：

除 Component 外，目录还内置了Template、API、Group、User、Resource、System、Domain、Location等核心 kind（ADR005 描述了这些核心种类），组织也可以按需扩展其他 kind。

描述文件中的替换（Substitutions）

描述文件支持$text、$json、$yaml三种占位替换，用于把其他文件的内容嵌入当前实体。例如把 API 定义从远端 Web 服务器拉取并嵌入spec.definition：

apiVersion: backstage.io/v1alpha1 kind: API metadata: name: petstore description: The Petstore API spec: type: openapi lifecycle: production owner: petstore@example.com definition: $text: https://petstore.swagger.io/v2/swagger.json

需要注意：要读取github.com等常规集成点之外的目标，必须在backend.reading.allow列表中显式放行，还可以用paths进一步限定：

backend: baseUrl: ... reading: allow: - host: example.com - host: '*.examples.org' - host: example.net paths: ['/api/']

仓库中的真实范例：本仓库的 catalog-info.yaml

本仓库根目录就存放着一个真实的实体描述文件 catalog-info.yaml，它就是"链接到已有实体文件"这种方式可以直接使用的示例：

apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: backstage description: | Backstage is an open-source developer portal that puts the developer experience first. links: - title: Website url: http://backstage.io - title: Documentation url: https://backstage.io/docs - title: Storybook url: https://backstage.io/storybook - title: Discord Chat url: https://discord.com/invite/EBHEGzX annotations: github.com/project-slug: backstage/backstage backstage.io/techdocs-ref: dir:. lighthouse.com/website-url: https://backstage.io spec: type: library owner: CNCF lifecycle: production

对照上文字段表可以看到：metadata.name、metadata.links、metadata.annotations（github.com/project-slug用于 GitHub 集成，backstage.io/techdocs-ref用于 TechDocs）、spec.type: library、spec.owner、spec.lifecycle: production一应俱全，是组织为自身服务编写实体文件的良好范本。

相关配置：让注册流程贴合你的组织

注册流程的行为可以通过 app-config.yaml 进行调整，其中与注册最直接相关的配置如下：

catalog: import: entityFilename: catalog-info.yaml pullRequestBranchName: backstage-integration

• catalog.import.entityFilename：仓库发现时要查找的实体文件名，默认catalog-info.yaml。
• catalog.import.pullRequestBranchName：当仓库中不存在实体文件、系统自动创建 PR 时使用的分支名，默认backstage-integration。

此外，有两类配置会直接影响注册能否成功：

1. SCM 集成（integrations）：仓库级 URL 发现依赖integrations下配置的 Git 主机（如github.com、gitlab.com、dev.azure.com），且从 CatalogImportClient.ts 的源码可知，仓库级 PR 流程目前支持 GitHub 与 Azure DevOps。文件级 URL 也需要对应的集成或backend.reading.allow放行。
2. 规则与预置位置（catalog.rules / catalog.locations）：catalog.rules控制允许导入的实体 kind（示例配置中允许了Component、API、Resource、System、Domain、Location等），catalog.locations则可以在启动时直接预置一批 location（例如本仓库示例配置中通过type: file引入了示例实体、示例组织数据与示例模板），这部分属于"自动化摄取"，与本文的手动注册互为补充。

关于目录配置的完整说明，可继续阅读 软件目录配置文档。

注册之后的下一步

组件注册成功后，你可以：

• 在 查看目录 中浏览已注册的实体及其展示方式；
• 通过 实体的生命周期 理解实体从注册、处理、存储到被读取的完整过程；
• 通过 注销与删除组件 了解如何移除不再需要的实体（注意：注销并重新注册同一文件会生成新的uid）；
• 通过 实体引用 掌握跨实体引用语法，为编写更复杂的描述文件做准备。

手动注册是理解目录工作方式的起点；当你的组织规模增长后，可以转向自动集成与位置预置（catalog.locations、providers 等）来持续同步数据。无论是哪种方式，catalog-info.yaml描述文件都是贯穿始终的核心载体。

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