🏗️ 治理与自动化一次搞定！Backstage标准脚手架（模板）完整指南

7 月 7, 2026

—

cslab

in IT Security

大家好！今天，我们将探讨如何利用平台工程的核心——Backstage 脚手架（Scaffolder），来“快速生成包含安全护栏的标准项目”。

我们分享的不仅仅是“复制代码”，而是如何通过代码管理谁创建、出于何种目的、以及遵循哪些安全策略来生成项目。🛠️

1. 模板的整体结构 (Anatomy of a Template) 🦴

Backstage 模板主要分为元数据（Metadata）（名称、描述）、参数（Parameters）（用户输入）、步骤（Steps）（执行阶段）和输出（Output）（结果指引）。

YAML

# 1. 定义模板的身份
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: standard-python-service
  title: "🛡️ 보안 표준 Python Flask 서비스"
  description: "KISA 보안 가이드라인과 CI/CD 스캔이 내장된 표준 API 서버를 생성합니다."
  tags: [standard, security, python]

spec:
  owner: platform-team
  type: service

  # 2. 从用户接收输入的“问卷”
  parameters:
    - title: "기본 정보"
      required: [component_id, owner]
      properties:
        component_id:
          title: "서비스 이름"
          type: string
          description: "생성할 프로젝트의 이름 (영문/숫자/-)"
        owner:
          title: "담당 팀"
          type: string
          ui:field: OwnerPicker # 选择 Backstage 注册组

    - title: "저장소 설정"
      required: [repoUrl]
      properties:
        repoUrl:
          title: "GitHub 위치"
          type: string
          ui:field: RepoUrlPicker # 选择仓库创建位置
          ui:options:
            allowedHosts: [github.com]

  # 3. 真正魔法发生的“自动化流程”
  steps:
    - id: fetch-base
      name: "표준 스켈레톤 가져오기"
      action: fetch:template
      input:
        url: ./skeleton # 模板源文件夹
        values:
          name: ${{ parameters.component_id }}
          owner: ${{ parameters.owner }}

    - id: publish
      name: "GitHub 저장소 생성 및 푸시"
      action: publish:github
      input:
        allowedHosts: ['github.com']
        description: "Created by Backstage Scaffolder"
        repoUrl: ${{ parameters.repoUrl }}

    - id: register
      name: "카탈로그 자동 등록"
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish'].output.remoteUrl }}
        catalogInfoPath: '/catalog-info.yaml'

  # 4. 完成后向用户展示的结果
  output:
    links:
      - title: "생성된 GitHub 저장소 보기"
        url: ${{ steps['publish'].output.remoteUrl }}

2. 核心步骤代码详细说明 🔍

📍 Parameters: 数据输入的艺术

用户输入的信息不仅仅是纯文本。使用 ui:field 可以调用与 Backstage 系统集成的高级组件。

OwnerPicker: 实时搜索并选择组织架构中注册的团队。👥
RepoUrlPicker: 选择一个有权限的 GitHub 组织，并即时确定仓库名称。

📍 Steps: 自动化的核心引擎

fetch:template: 这是最关键的步骤。它会复制 ./skeleton 文件夹中的文件，并将 ${{ values.name }} 等变量“替换”为用户输入的实际值。
publish:github: 不仅仅是上传代码，它还通过 GitHub API 创建新的仓库并进行初始提交。🛰️
catalog:register: 确保新创建的服务立即出现在 Backstage 管理列表（Catalog）中，从而防止“影子 IT”。

3. 项目的核心：Skeleton 文件夹 🦴

模板引用的 ./skeleton 文件夹中包含什么？正是标准规范。

./skeleton/catalog-info.yaml (示例) 该文件在项目创建时同步生成，充当服务的“身份证”。

YAML

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{ values.name | dump }}
  description: "이 서비스는 표준 템플릿으로 자동 생성되었습니다."
spec:
  type: service
  lifecycle: experimental
  owner: ${{ values.owner | dump }} # 创建时输入的团队自动指定为所有者！

Tip: 在这里使用 ${{ values.owner }}，可以实现在创建时自动进行所有权管理。🛡️

4. 此蓝图带来的成果 🎁

执行此模板，开发人员将在1分钟内获得以下成果：

GitHub 仓库: 一个已完成标准代码结构和 CI/CD (GitHub Actions) 设置的仓库。📁
安全设置: 默认包含 Trivy 或 Snyk 等安全扫描配置。🔒
管理自动化: 注册到 Backstage Catalog，可立即查看依赖图和文档 (TechDocs)。📡

🔥 总结：为什么要用代码管理？

如果开发人员手动编写 catalog-info.yaml 并配置 GitHub 设置，很容易出现拼写错误或遗漏安全设置。但通过 Scaffolder 蓝图，“组织的标准策略”就成为了“项目的起点”。

现在，将此代码应用到您的 Backstage 中吧！您的平台工程之旅将因此变得更加坚实。🚀