Backstage 入门实操：使用 Software Templates 创建 Component（以 Example Node.js Template 为例）

Backstage 入门实操：使用 Software Templates 创建 Component（以 Example Node.js Template 为例）

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

导读：本文围绕 Backstage 的软件模板（Software Templates）体系，完整演示如何通过 Scaffolder 从零创建一个新组件（Component）。你将学会在独立安装的 Backstage 应用中，通过Create页面一步步引导创建服务、掌握catalog-info.yaml实体描述文件的核心字段，并理解模板定义（template.yaml）中参数、步骤与输出之间的底层协作机制。读完即可在自己环境中复现"模板生成代码 → 发布到 GitHub → 注册进软件目录"的完整闭环。

背景：Component 与软件模板的关系

在 Backstage 的软件目录（Software Catalog）中，Component是核心实体之一，用于描述一个软件单元（服务、网站、库等）及其元数据。而组件通常不是手工登记到目录中的，而是通过**软件模板（Software Templates）**来创建：模板携带一组代码骨架（skeleton），骨架中可以包含变量占位符，并融入你所在组织的最佳实践（如 CI 配置、目录文件、文档规范）。模板本身作为一个kind: Template的实体发布到某个位置（例如 GitHub 或 GitLab 仓库），用户在 Backstage 前端选择该模板后，由 Scaffolder 插件执行整个创建流程。

独立安装的 Backstage 应用内置了Example Node.js Template——一个用于创建并注册简单 Node.js 服务的示例模板，存放在 packages/create-app/templates/default-app/examples/template/template.yaml。如果你想了解如何编写自己的模板，可以参考 添加自有模板 与 编写模板。

前置条件

本教程使用默认的 Node.js 模板，该模板会在 GitHub 上创建一个仓库并向其中写入必要文件，使组件能够被集成进软件目录。由于涉及创建仓库，你必须先建立 Backstage 与 GitHub 之间的集成：

1. 已完成独立应用安装：参见 独立安装指南（通过npx @backstage/create-app@latest创建应用，并以yarn start同时启动前端与后端，默认端口分别为 3000 和 7007）。
2. 注册 GitHub Scaffolder Action 模块：安装@backstage/plugin-scaffolder-backend-module-github，详见 内置 Actions 与 Action 模块安装。
3. 配置 GitHub Integration：使用 GitHub Personal Access Token 建立集成，详见 设置 GitHub 集成。

其中，GitHub 集成的核心配置写在根目录的app-config.local.yaml（该文件应被.gitignore排除，避免密钥入库）：

integrations: github: - host: github.com token: ghp_urtokendeinfewinfiwebfweb # 替换为你的 GitHub Token

更推荐的安全做法是从环境变量读取 Token：

integrations: github: - host: github.com token: ${GITHUB_TOKEN} # 使用环境变量 GITHUB_TOKEN

创建组件的完整步骤

在满足上述前置条件并完成yarn start后，按以下步骤创建你的第一个组件：

1. 在 Backstage 顶栏或侧边栏选择Create，进入软件模板列表页。
2. 在CATEGORIES下拉列表中选择Service，过滤出服务类模板。
3. 选择Owner（拥有者）。本教程可直接选择guest。
4. 在Example Node.js Template卡片上点击Choose，进入参数填写向导。
5. 在第一步"Fill in some steps"中，为服务输入Name（本教程填tutorial），点击NEXT。
6. 在第二步"Choose a location"中，输入你的GitHub 用户名作为Owner。
7. 将Repository填为tutorial，点击REVIEW进入复核页。
8. 核对所有信息无误后，点击CREATE，开始执行模板任务。

点击CREATE后，页面会展示任务的实时执行进度。所有步骤完成后，你可以在 GitHub 仓库或软件目录中查看新创建的服务：

• 点击REPOSITORY：跳转到tutorial仓库的main分支，查看新组件生成的catalog-info.yaml及其他项目初始化文件。
• 点击OPEN IN CATALOG：查看新组件的详情，包括其关系（Relationships）、链接（Links）与子组件（Subcomponents）。
• 点击侧边栏Home：在软件目录的组件列表中即可看到新出现的tutorial组件。

理解生成的 catalog-info.yaml

模板执行后在仓库中生成的catalog-info.yaml是描述软件目录实体（Entity）的描述符文件。Example Node.js Template渲染出的实体内容如下：

apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: 'tutorial' spec: type: service owner: user:guest lifecycle: experimental

各字段含义（详细规范见 Catalog 实体描述符格式）：

• apiVersion：实体 API 版本，当前为backstage.io/v1alpha1，属于实体信封（envelope）的一部分，与kind、metadata、spec共同构成所有实体的统一外层结构。
• kind：实体类型，这里是Component。其余常见类型包括Template、System、API、Group、User、Resource等。
• metadata.name：实体在目录中的唯一标识名，来自你在向导中填写的Name参数。从源码看，模板内容文件 content/catalog-info.yaml 中通过${{ values.name | dump }}占位符在渲染阶段注入该值。
• spec.type：组件类型，这里为service（服务）。
• spec.owner：实体的拥有者引用，这里指向user:guest，即你选择guest作为拥有者时的结果。拥有者也可以是Group或User实体引用。
• spec.lifecycle：组件生命周期阶段，此处为experimental。常用取值还包括production、development等，描述该组件的成熟度与维护状态。

实体描述符支持通过$text、$json、$yaml占位符从外部文件做内容替换，也支持metadata.labels、metadata.annotations、metadata.links等更丰富的元数据，供自定义场景使用（详见 描述符格式）。

深入：Example Node.js Template 的底层执行原理

组件创建流程由 Scaffolder 插件驱动。模板定义文件 template.yaml 采用scaffolder.backstage.io/v1beta3版本，分为三大区块：parameters（前端表单参数）、steps（后端按序执行的步骤）、output（执行成功后展示给用户的输出）。

apiVersion: scaffolder.backstage.io/v1beta3 kind: Template metadata: name: example-nodejs-template title: Example Node.js Template description: An example template for the scaffolder that creates a simple Node.js service spec: owner: user:guest type: service parameters: - title: Fill in some steps required: - name properties: name: title: Name type: string description: Unique name of the component ui:field: EntityNamePicker ui:autofocus: true - title: Choose a location required: - repoUrl properties: repoUrl: title: Repository Location type: string ui:field: RepoUrlPicker ui:options: allowedHosts: - github.com steps: - id: fetch-base name: Fetch Base action: fetch:template input: url: ./content values: name: ${{ parameters.name }} - id: publish name: Publish action: publish:github input: description: This is ${{ parameters.name }} repoUrl: ${{ parameters.repoUrl }} defaultBranch: 'main' - id: register name: Register action: catalog:register input: repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }} catalogInfoPath: '/catalog-info.yaml' - id: notify name: Notify action: notification:send input: recipients: entity entityRefs: - user:default/guest title: 'Template executed' info: 'Your template has been executed' severity: 'normal' output: links: - title: Repository url: ${{ steps['publish'].output.remoteUrl }} - title: Open in catalog icon: catalog entityRef: ${{ steps['register'].output.entityRef }}

结合源码逐段拆解：

• spec.parameters（前端表单）：模板定义的parameters会被渲染成前端的表单输入序列，使用 JSON Schema 描述字段。EntityNamePicker是实体名校验器，RepoUrlPicker是仓库地址选择器，通过ui:field指定；ui:autofocus: true让表单自动聚焦该输入框。allowedHosts限定仓库可发布的主机为github.com。本仓库的 示例模板 还展示了"多步表单"的组织方式，每个title即一个独立的表单步骤。
• spec.steps（后端执行步骤）：Scaffolder 后端会按顺序执行每个步骤，每步调用一个 Action：
  • fetch:template：从模板内置的./content目录取回代码骨架，并用values中的变量（来自parameters.name）完成渲染。渲染规则与 编写模板 中描述的模板引擎一致。
  • publish:github：将工作目录中的内容发布为 GitHub 仓库，仓库地址来自parameters.repoUrl，默认分支main。
  • catalog:register：把catalog-info.yaml注册进软件目录，repoContentsUrl取自上一步输出的steps['publish'].output.repoContentsUrl——这正是步骤之间通过输出（output）传递数据的调用链证据。
  • notification:send：任务完成后向指定实体（user:default/guest）发送通知。
• spec.output（结果输出）：执行成功后，前端会展示Repository（仓库链接）与Open in catalog（目录实体链接）两个按钮，分别对应steps['publish'].output.remoteUrl与steps['register'].output.entityRef，这就是创建成功页面上两个入口的来源。

Action 模块的注册：让publish:github等 Action 可用

publish:github、catalog:register等 Action 由不同的 Action 模块提供。为了在模板中调用 GitHub 相关 Action，需先安装并注册模块（详见 内置 Actions 文档）：

yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-github

然后在后端入口packages/backend/src/index.ts中注册：

import { createBackend } from '@backstage/backend-defaults'; const backend = createBackend(); backend.add(import('@backstage/plugin-app-backend')); backend.add(import('@backstage/plugin-catalog-backend')); backend.add( import('@backstage/plugin-catalog-backend-module-scaffolder-entity-model'), ); // scaffolder plugin backend.add(import('@backstage/plugin-scaffolder-backend')); backend.add(import('@backstage/plugin-scaffolder-backend-module-github')); backend.start();

除 GitHub 外，仓库还提供 Azure DevOps、Bitbucket Cloud、Bitbucket Server、Gerrit、Gitea、GitLab、Rails、Yeoman、Sentry、Cookiecutter 等 Action 模块（对应plugins/scaffolder-backend-module-*目录）。所有已注册 Action 的列表可通过前端访问/create/actions（本地开发环境为http://localhost:3000/create/actions）查看，便于排查"Action 不存在"类问题。

编写并接入自己的模板

理解Example Node.js Template之后，你可以仿照它编写自己的模板。一个最小可用的template.yaml示例如下（摘自 添加自有模板）：

apiVersion: scaffolder.backstage.io/v1beta3 kind: Template metadata: name: v1beta3-demo title: Test Action template description: scaffolder v1beta3 template demo spec: owner: backstage/techdocs-core type: service parameters: - title: Fill in some steps required: - name properties: name: title: Name type: string description: Unique name of the component ui:autofocus: true ui:options: rows: 5 - title: Choose a location required: - repoUrl properties: repoUrl: title: Repository Location type: string ui:field: RepoUrlPicker ui:options: allowedHosts: - github.com steps: - id: fetchBase name: Fetch Base action: fetch:template input: url: ./template values: name: ${{ parameters.name }} - id: publish name: Publish action: publish:github input: description: This is ${{ parameters.name }} repoUrl: ${{ parameters.repoUrl }} defaultBranch: 'main' - id: register name: Register action: catalog:register input: repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }} catalogInfoPath: '/catalog-info.yaml' output: links: - title: Repository url: ${{ steps['publish'].output.remoteUrl }} - title: Open in catalog icon: catalog entityRef: ${{ steps['register'].output.entityRef }}

编写完成后，需要把模板接入软件目录才能被 Scaffolder 使用。两种常用方式：

方式一：静态位置配置（app-config.yaml）

catalog: locations: - type: url target: https://github.com/backstage/software-templates/blob/main/scaffolder-templates/react-ssr-template/template.yaml rules: - allow: [Template] - type: file target: template.yaml # Backstage 会从 packages/backend/template.yaml 读取该文件

方式二：使用catalog-import插件：在/catalog-import页面按引导注册模板仓库。更详细的写法（参数校验、自定义字段、模板引擎语法）参见 编写模板 与 配置软件模板。

注意：新增或修改模板后，需要刷新对应的 location 实体，否则目录仍会显示旧模板甚至不显示新模板。在Catalog页面切换到Locations视图，找到对应 location 条目，点击代表 "Scheduled entity refresh" 的刷新图标即可。

常见问题与故障排查

• 登录后无法创建组件：确认已配置 GitHub Integration 与鉴权，并已安装@backstage/plugin-scaffolder-backend-module-github；安装新模块后需重启后端（Ctrl+C后重新yarn start）。
• publish:github报错：检查app-config.local.yaml中 GitHub Token 的repo与workflow权限（模板执行会配置 GitHub Actions workflow），并确认 Token 未过期；更新集成配置后同样需要重启后端生效。
• 目录中看不到新模板：模板需以kind: Template注册进目录（静态位置配置或catalog-import），并刷新 location 实体。
• 想查看可用的 Action 有哪些：访问/create/actions页面（本地为http://localhost:3000/create/actions），可看到全部已注册 Action 及其参数定义。

小结

本文以Example Node.js Template为线索，走通了"在 Create 页面选择模板 → 填写参数 → 执行模板 → 发布 GitHub 仓库 → 注册进软件目录 → 在目录中查看组件"的完整链路。同时，通过阅读 模板定义、模板内容 与 实体描述符格式，理解了parameters、steps、output的协作机制与catalog-info.yaml的关键字段。以此为基础，你可以进一步参考 编写自己的模板，把团队的最佳实践沉淀为可复用的软件模板。

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