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-applatest随后进入应用目录执行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 软件目录去哪里读取数据以及如何把读到的实体加载进目录。官方文档指出注册组件有两种方式方式输入内容处理逻辑官方示例链接到已有实体文件指向某个catalog-info.yaml文件的 URL分析该文件确定其中定义了哪些实体并将实体加入目录https://github.com/backstage/backstage/blob/master/catalog-info.yaml链接到仓库仓库根 URL在仓库中发现所有catalog-info.yaml文件将其定义的实体加入目录https://github.com/backstage/backstage针对第二种方式官方文档有一条重要提示如果在仓库中没有找到任何实体系统会创建一个 Pull Request向仓库中添加一个示例catalog-info.yaml文件。当该 Pull Request 被合并后目录就会加载其中定义的全部实体。这意味着链接到仓库既是一条数据导入通道也是一个帮助仓库补上元数据的引导机制。手动注册组件的完整操作步骤按照官方文档在软件目录中手动注册组件的步骤如下选择Create创建入口。选择REGISTER EXISTING COMPONENT注册已有组件。填写模板。独立安装的 Backstage 应用自带一个模板。例如输入实体文件的仓库 URLhttps://github.com/backstage/backstage/blob/master/catalog-info.yaml该地址也用于官方 demo 站点 的目录。选择ANALYZE分析。系统会对 URL 进行预分析dry-run判断 URL 指向的是单个实体文件还是整个仓库并列出将要导入的实体清单。如果ANALYZE的分析结果正确选择IMPORT导入。导入成功后界面会展示该实体的详情页。选择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方法可以看到分析流程的关键分叉识别 URL 是否指向实体文件代码检查 URL 路径是否以.yaml/.yml结尾或查询参数path是否匹配该模式。若是则调用目录 API 的addLocation({ type: url, target: url, dryRun: true })进行试运行dry-run添加返回locations类型的结果含exists标记和实体清单这就是ANALYZE步骤在预览阶段做的事情——此时并不会真正写入数据。否则按仓库处理代码通过scmIntegrationsApi.byUrl(url)查找已配置的 SCM 集成。从源码看仓库级发现目前只支持 GitHub 和 Azure DevOps两种集成类型如果 URL 的主机没有匹配到任何已配置集成会抛出错误提示该 URL 未被识别为有效的 git URL……你可以改为粘贴指向catalog-info.yaml文件的完整 URL。调用分析接口对于仓库 URL前端会向目录后端发送POST /catalog/analyze-location请求并带上catalog.import.entityFilename配置默认catalog-info.yaml由后端在仓库中扫描该文件。根据结果分流若仓库中已存在实体文件返回locations类型结果一个文件对应一个 location前端进入单 location / 多 location流程若仓库中没有实体文件返回repository类型结果并携带generatedEntities自动生成的示例实体。此时前端进入no-location流程即官方文档提到的自动创建 Pull Request分支。IMPORT对应的是把分析结果正式提交在submitPullRequest中系统会先用catalogApi.validateEntity校验 YAML 实体是否合法再根据集成类型调用 GitHub 或 Azure DevOps 的接口提交 PRPR 标题形如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-websitesapiVersion实体规范格式的版本号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 中具有特殊语义的字段字段必填说明name是实体名称用于人眼识别也用于机器引用URL、其他实体文件中的引用。同一命名空间内同 kind 名称唯一不区分大小写。长度 1~63由[a-z0-9A-Z]构成可用[-_.]分隔namespace否实体所属命名空间省略时默认default。跨命名空间引用须使用namespace/name语法uid输出字段实体首次入库时由数据库自动生成的全局唯一 ID不应作为外部引用注销再注册同名文件会产生新的 uidtitle否UI 中展示的显示名仅用于展示实体引用仍使用namedescription否对人类可读的实体描述应简短有信息量labels否键值对语义与 Kubernetes labels 一致常用于查询与过滤annotations否任意非标识性元数据语义与 Kubernetes annotations 一致常用于引用外部系统git ref、监控、PagerDuty 等。backstage.io/前缀为 Backstage 核心保留完整列表见 well-known annotationstags否单值字符串列表如编程语言java、go由[a-z0-9:#]用-分隔最长 63 字符links否与实体相关的外部超链接列表url必填title/icon/type可选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 字段如下字段必填说明spec.type是组件类型。常见取值service后端服务、website网站、library软件库。软件目录接受任意值但组织应建立自己的分类体系spec.lifecycle是生命周期状态。常见取值experimental实验/早期非生产、production已建立、有人负责维护、deprecated处于生命周期末期spec.owner是指向负责人通常是团队 Group也可以是 User的实体引用默认 kind 为Group。它主要用于展示不应被自动化流程用来做授权spec.system否组件所属系统System的实体引用spec.subcomponentOf否组件所属的上级组件spec.providesApis/spec.consumesApis否组件提供/消费的 API 实体引用数组spec.dependsOn/spec.dependencyOf否组件依赖/被依赖的组件与资源引用数组除 Component 外目录还内置了Template、API、Group、User、Resource、System、Domain、Location等核心 kindADR005 描述了这些核心种类组织也可以按需扩展其他 kind。描述文件中的替换Substitutions描述文件支持$text、$json、$yaml三种占位替换用于把其他文件的内容嵌入当前实体。例如把 API 定义从远端 Web 服务器拉取并嵌入spec.definitionapiVersion: backstage.io/v1alpha1 kind: API metadata: name: petstore description: The Petstore API spec: type: openapi lifecycle: production owner: petstoreexample.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.annotationsgithub.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-integrationcatalog.import.entityFilename仓库发现时要查找的实体文件名默认catalog-info.yaml。catalog.import.pullRequestBranchName当仓库中不存在实体文件、系统自动创建 PR 时使用的分支名默认backstage-integration。此外有两类配置会直接影响注册能否成功SCM 集成integrations仓库级 URL 发现依赖integrations下配置的 Git 主机如github.com、gitlab.com、dev.azure.com且从 CatalogImportClient.ts 的源码可知仓库级 PR 流程目前支持 GitHub 与 Azure DevOps。文件级 URL 也需要对应的集成或backend.reading.allow放行。规则与预置位置catalog.rules / catalog.locationscatalog.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
