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

★ FEATURED ARTICLE

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 之间的集成已完成独立应用安装参见独立安装指南通过npx backstage/create-applatest创建应用并以yarn start同时启动前端与后端默认端口分别为 3000 和 7007。注册 GitHub Scaffolder Action 模块安装backstage/plugin-scaffolder-backend-module-github详见内置 Actions 与 Action 模块安装。配置 GitHub Integration使用 GitHub Personal Access Token 建立集成详见设置 GitHub 集成。其中GitHub 集成的核心配置写在根目录的app-config.local.yaml该文件应被.gitignore排除避免密钥入库integrations: github: - host: github.com token: ghp_urtokendeinfewinfiwebfweb # 替换为你的 GitHub Token更推荐的安全做法是从环境变量读取 Tokenintegrations: github: - host: github.com token: ${GITHUB_TOKEN} # 使用环境变量 GITHUB_TOKEN创建组件的完整步骤在满足上述前置条件并完成yarn start后按以下步骤创建你的第一个组件在 Backstage 顶栏或侧边栏选择Create进入软件模板列表页。在CATEGORIES下拉列表中选择Service过滤出服务类模板。选择Owner拥有者。本教程可直接选择guest。在Example Node.js Template卡片上点击Choose进入参数填写向导。在第一步Fill in some steps中为服务输入Name本教程填tutorial点击NEXT。在第二步Choose a location中输入你的GitHub 用户名作为Owner。将Repository填为tutorial点击REVIEW进入复核页。核对所有信息无误后点击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 后端会按顺序执行每个步骤每步调用一个 Actionfetch: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.yamlcatalog: 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安装新模块后需重启后端CtrlC后重新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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

阅读完成 · 觉得有帮助？

咨询建站