Backstage 概念验证PoC搭建指南脚手架、catalog-info 与 GitHub Catalog 自动发现【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文是 Backstage 采纳路线Adoption Golden Path系列的第 3 篇目标是在组织内部快速搭建一个概念验证Proof of ConceptPoC实例先用脚手架在本机跑通一个带示例数据的 Backstage 应用再为团队自有仓库添加catalog-info.yaml最后通过 GitHub Discovery Provider 实现软件目录Software Catalog的自动发现与持续同步。读完本文你将掌握从零启动一个可演示、可评估、可拿给关键干系人反馈的 Backstage PoC 的完整路径并为后续生产化改造第 2 章末尾和功能定制第 3 章打下基础。谁应该完成这一步技术伙伴协作模式原文档开篇即明确了分工如果你是非技术角色本节应由你的技术伙伴完成。这条原则在 采纳路线的开篇文档 中同样被强调——非技术成员无需掌握 Backstage 的技术细节但最好能找到一位技术伙伴协助搭建 PoC 实例以便后续向真实用户收集反馈。也就是说本文面向两类读者技术成员按本文逐步操作把实例跑起来、把数据喂进去非技术成员理解 PoC 的目标与验收标准本地可运行、目录里有真实项目、能演示把技术细节交给伙伴。PoC 的定位先跑起来别急着定制这一步的核心目标是让实例在你的本地机器上运行起来。原文明确提醒了两点边界生产化放到后面第二章deployment Golden Path末尾会专门讲解如何为生产环境准备实例PoC 阶段不要陷入部署架构。克制定制冲动你可能会忍不住改主题theme、加某个组织必需的插件——原文的建议是hold strong忍住。这些工作属于第 3 章customizing your instance的内容参见 005-customizing-your-instance。过早定制只会拖延你拿到真实用户反馈的时间。PoC 阶段唯一要交付的成果是一个本机可运行、已经能看到你组织真实项目数据的 Backstage 实例。第一步按 Create-App Golden Path 脚手架应用PoC 的第一步是创建应用。请完整走完 Create-App Golden Path其中两个关键步骤文档为 001 - Scaffolding脚手架 与 002 - Local development本地开发。前置条件参考 npx-create-app.md你需要在 Unix 系环境Linux、macOS 或 WSL中准备Node.js Active LTS推荐用nvm安装如nvm install lts/ironNode 20YarnBackstage 当前使用 Yarn 4.4.1启用 corepack 后执行yarn set version 4.4.1git、curl 或 wget以及可用的 GNU 构建环境Debian/Ubuntu 需make与build-essentialmacOS 需执行xcode-select --install。脚手架命令npx backstage/create-applatest向导会要求输入应用名称如my-backstage-app该名称即生成目录名。安装过程会执行yarn install与yarn tsc可能需要几分钟属于正常现象。完成后你将得到一个带示例数据、本地可运行的 Backstage 应用——注意它不是生产就绪安装也不包含你组织的专属信息。生成的应用结构脚手架生成的简化目录结构如下app ├── app-config.yaml ├── catalog-info.yaml ├── package.json └── packages ├── app └── backend各文件职责依据 npx-create-app.mdapp-config.yaml应用主配置文件涵盖app、backend、catalog、integrations、auth等区块是 PoC 阶段改动最频繁的文件本仓库根目录就有一份完整参考app-config.yamlcatalog-info.yaml软件目录实体描述文件Descriptor用来登记当前仓库本身这个 Componentpackage.json根包清单注意不要在根目录添加 npm 依赖应安装到对应 workspacepackages/app/完整的 Backstage 前端应用可作为前端开发的起点packages/backend/后端支撑认证Authentication、软件目录Software Catalog、软件模板Software Templates、TechDocs 等核心能力。本地启动cd my-backstage-app yarn startyarn start会同时以两个进程启动前端与后端。前端监听3000 端口React 应用本地使用 rspack 快速编译支持热更新后端监听7007 端口Node.js express HTTP 服务。数据库本地使用SQLite适合开发但数据易失——每次yarn start之间不应依赖它持久保存数据不过热重载期间数据会保留。详细说明见 local-development.md。编译完成后浏览器会自动打开http://localhost:3000若未自动打开看到webpack compiled successfully后手动访问该地址即可。第二步为你的仓库添加 catalog-info.yamlPoC 要展示真实数据所以原文建议在你拥有的几个仓库/项目中各添加一个catalog-info.yaml文件。这是软件目录的数据源头——Backstage 的核心思想之一是让团队在自己的仓库里维护所有权等信息由 Backstage 自动摄入汇总见 001-getting-started 中对 Software Catalog 的介绍。一个最小可用的catalog-info.yaml可以参考本仓库根目录的真实示例 catalog-info.yamlapiVersion: backstage.io/v1alpha1 kind: Component metadata: name: backstage description: | Backstage is an open-source developer portal that puts the developer experience first. annotations: github.com/project-slug: backstage/backstage backstage.io/techdocs-ref: dir:. spec: type: library owner: CNCF lifecycle: production关键字段说明apiVersion实体描述格式版本目前为backstage.io/v1alpha1kind实体类型常用Component、API、System、Group、User、Template、Location等metadata.name实体唯一名称metadata.annotations附加元数据如github.com/project-slug用于关联 GitHub 仓库backstage.io/techdocs-ref用于关联 TechDocsspec.type / spec.owner / spec.lifecycleComponent 的常用规格字段owner通常指向某个 Group 实体。第三步配置 GitHub Discovery Provider 自动发现实体手动注册实体只适合起步要让目录自动长出来需要配置GitHub 集成下的 discovery provider。它能够爬取整个 GitHub 组织或 App 可见的仓库按配置路径注册实体是官方推荐的目录实体摄入方式详见 GitHub Discovery 文档。3.1 安装模块GitHub 实体 provider 默认不随后端安装需要显式添加依赖yarn --cwd packages/backend add backstage/plugin-catalog-backend-module-github然后在后端入口注册packages/backend/src/index.tsbackend.add(import(backstage/plugin-catalog-backend)); backend.add(import(backstage/plugin-catalog-backend-module-github));本仓库中该模块的源码与测试位于 plugins/catalog-backend-module-github/src/其alpha.ts与index.ts负责导出 provider 与模块配置lib/目录下包含多组织配置解析lib/config.ts、默认实体转换器、事件分析等实现。3.2 配置 GitHub 集成使用 discovery provider 前需要先配置 GitHub 集成token 或 GitHub App。在app-config.yaml中integrations: github: - host: github.com token: ${GITHUB_TOKEN}本仓库根目录的 app-config.yaml 中提供了完整示例包括 GitHub Enterprise 实例的apiBaseUrl/rawBaseUrl两种配置方式。使用 Personal Access Token 时需关注 scope读取组件至少需要reposcope使用 GitHub App 时需授予Contents: Read-only权限。此外GitHub App 认证还带有更高的 API 速率上限。3.3 配置 catalog providers在app-config.yaml的catalog.providers下新增github配置依据 discovery.mdcatalog: providers: github: providerId: organization: your-org # GitHub 组织名 catalogPath: /catalog-info.yaml filters: branch: main # 只处理该分支 repository: .* # 仓库名正则 schedule: frequency: { minutes: 30 } timeout: { minutes: 3 }参数详解参数必填默认值说明organization与app二选一-GitHub 组织账号名多组织需每个组织一个 provider 配置或用appapp与organization二选一-GitHub App 的 IDhost可选github.comGitHub Enterprise 实例主机名须与integrations.github中定义的主机一致catalogPath可选/catalog-info.yaml查找catalog-info.yaml的路径支持*、**或 minimatch glob使用通配符时不能开启validateLocationsExistfilters.branch可选仓库默认分支按分支名过滤分支名不能含/filters.repository可选-按仓库名正则过滤filters.topic.include/exclude可选-按 GitHub topic 过滤exclude 优先级高于 includefilters.visibility可选-按可见性过滤可选private、internal、publicfilters.allowArchived可选false是否包含已归档仓库validateLocationsExist可选false是否校验 location 对应的 catalog 文件真实存在后再发射避免为不存在的文件生成 location因 GitHub API 限制不能与catalogPath通配符同时使用schedule.frequency推荐-任务运行频率支持 cron、ISO 时长与人类可读时长系统会尽量避免重叠调用schedule.timeout推荐-单次任务最大执行时间schedule.initialDelay/schedule.scope可选-首次执行延迟global/local并发控制范围pageSizes.repositories可选25GitHub GraphQL 分页大小遇RESOURCE_LIMITS_EXCEEDED时可调小该 provider 支持通过唯一 provider ID 配置多个组织与多个 App。provider ID 建议保留也可省略此时使用default但不推荐。3.4 关于 GitHub API 速率限制自动发现会按配置频率对 GitHub API 发起请求GitHub 对标准账号限速5,000 次/小时Enterprise 更高。如果请求过于频繁会被限流可通过调整schedule控制刷新频率例如schedule: frequency: { minutes: 35 } timeout: { minutes: 3 }每 35 分钟刷新一次即每个发现的 location 每 35 分钟触发一次 API 请求。这是所有向目录摄入 GitHub 实体的方式都会遇到的问题而自动发现尤其容易触达上限若仍不够可改用速率上限更高的 GitHub App 认证。3.5 可选进阶事件支持实时同步该 catalog 模块内置事件支持会订阅github.push、github.repository等主题让目录在仓库变更时即时更新而无需等待调度刷新。启用需要两步前置在 GitHub 创建 webhookPayload URL 形如https://your-instance-name/api/events/http/githubContent Type 设为application/json订阅push与repository事件安装并配置backstage/plugin-events-backend-module-githubyarn --cwd packages/backend add backstage/plugin-events-backend-module-githubbackend.add(import(backstage/plugin-events-backend)); backend.add(import(backstage/plugin-events-backend-module-github));events: modules: github: webhookSecret: ${GITHUB_WEBHOOK_SECRET} # 与 GitHub 上创建 webhook 时设置的值一致 http: topics: - github # 暴露 HTTP 接收端点 /api/events/http/github其中webhookSecret虽非强制但强烈建议配置用于校验事件确实来自 GitHub。PoC 阶段若不需要实时同步可跳过本节仅依赖schedule的定时刷新即可。验收标准与下一步完成上述三步后你的 PoC 应该满足本机可通过yarn start启动浏览器可访问http://localhost:3000软件目录中已出现你为团队仓库添加的真实 Component 实体通过 GitHub discovery 自动摄入实例仍保持开箱即用状态未做过主题定制或插件定制。随后进入采纳路线下一环节把 PoC 展示给第一批关键干系人并收集反馈参见 004-first-stakeholder-feedback。在第二章deployment Golden Path结束时将探讨如何把实例准备到生产就绪而主题定制、插件选型等个性化工作则留到 005-customizing-your-instance 展开。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考