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修改为mytutorialapiVersion: 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提交更改将变更提交到合适的分支然后走你团队常规的 PRPull 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/v1alpha1kind必填实体的高层类型本指南场景下为Component。Backstage 的核心类型由 ADR005 核心实体 定义组织也可以自由添加自有类型metadata必填实体本身的元数据名称、描述、标签、注解等不属于实体规范本身spec因类型而异描述实体的实际规范数据其结构取决于apiVersion与kind的组合。metadata 常用字段字段必填说明name是实体名称须在同一命名空间下按 kind 唯一不区分大小写长度为 163由[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、deprecatedspec.owner是组件负责人的实体引用默认为Group类型如artist-relations-teamspec.system否组件所属系统的实体引用生成partOf/hasPart关系spec.subcomponentOf否组件所属父组件的实体引用spec.providesApis否组件提供的 API 实体引用数组生成providesApi/apiProvidedBy关系spec.consumesApis否组件消费的 API 实体引用数组生成consumesApi/apiConsumedBy关系spec.dependsOn否组件依赖的组件/资源引用数组生成dependsOn/dependencyOf关系spec.dependencyOf否依赖该组件的组件/资源引用数组完整的关系类型语义可参见已知关系列表。更新后的生效链路从仓库合并到目录刷新你可能好奇为什么合并catalog-info.yaml后目录会自动更新这背后的机制记录在实体的生命周期文档中。软件目录后端由三条流水线驱动摄取Ingestion实体提供者Entity Provider从外部权威源如你注册的 YAML 文件 URL拉取原始实体数据并写入数据库。通过Create按钮或 app-config 注册的 YAML 文件 URL 都由实体提供者管理处理Processing处理器Processor循环校验、分析并加工原始实体数据可能产出子实体、错误以及到其他实体的关系。当你在 UI 中把name从tutorial改成mytutorial并合并后处理循环会重新读取文件并更新数据库中的实体若 YAML 语法错误错误会以状态条目如backstage.io/catalog-processing的形式附加到实体上缝合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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考