32-Backstage实操

Backstage 是 Spotify 开源的内部开发者平台（IDP）框架，目前是构建 IDP 的事实标准。本章简要介绍 Backstage 的架构、软件目录、模板脚手架、插件生态与 TechDocs。

为什么需要 Backstage#

团队 10 人的时候，口耳相传就够了。团队 100 人的时候，口耳相传是灾难：谁知道 payment-service 用的是哪个 Kafka topic？新建一个 Go 微服务需要配哪些 CI/CD 变量？这些知识分散在 Confluence、Slack、脑子里。

Backstage 把零散的知识和工具塞进一个入口，解决信息孤岛和配置漂移。业界落地案例普遍反馈，成熟的 IDP 能显著缩短新服务上线时间、降低查找信息的沟通成本（注：DORA 2024 报告对平台工程的观察更为审慎——它提升开发者生产力与满意度，但在个体度量点上对交付吞吐/稳定性略有拖累，收益需结合治理才能兑现）。

核心概念#

Software Catalog（软件目录）#

Catalog 是 Backstage 的核心，存储所有"软件实体"的元数据：

Component：服务、库、网站
API：服务暴露的接口（OpenAPI/AsyncAPI/GraphQL）
Resource：数据库、S3 bucket、消息队列
Group：团队或部门
System：相关组件的集合（如"支付系统"）
Domain：业务领域

每个实体通过 catalog-info.yaml 描述，存在对应的代码仓库里。

Scaffolder Templates（脚手架模板）#

通过表单界面一键创建符合团队规范的新服务——代码仓库、CI/CD 流水线、K8s 配置一次性生成。

TechDocs（技术文档）#

基于 MkDocs 的文档系统，文档以 Markdown 存在代码仓库里（文档即代码），Backstage 构建展示，自动关联到对应 Component。

Plugins（插件）#

Backstage 的扩展机制，官方 100+ 插件，社区更多。插件可以在 Catalog 页面增加 Tab，提供额外上下文。

部署#

本地快速体验#

bash
npx @backstage/create-app@latest
cd my-backstage
yarn install
yarn dev

浏览器访问 http://localhost:3000。

生产环境：K8s + Helm#

bash
helm repo add backstage https://backstage.github.io/charts
helm install backstage backstage/backstage \
  --namespace backstage --create-namespace \
  --values values.yaml

values.yaml 核心配置：

yaml
backstage:
  appConfig:
    app:
      baseUrl: https://backstage.company.com
    backend:
      database:
        client: pg
        connection:
          host: ${POSTGRES_HOST}
          port: 5432
    catalog:
      providers:
        github:
          myOrg:
            organization: "my-github-org"
            catalogPath: "/catalog-info.yaml"
            schedule:
              frequency: { minutes: 30 }

postgresql:
  enabled: true

ingress:
  enabled: true
  host: backstage.company.com

Software Catalog 配置#

每个代码仓库根目录放 catalog-info.yaml：

yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  title: "支付服务"
  description: "处理订单支付、退款、对账的核心服务"
  annotations:
    github.com/project-slug: "my-org/payment-service"
    argocd/app-name: "payment-service-prod"
    grafana/dashboard-selector: "service=payment-service"
    backstage.io/techdocs-ref: dir:.
  tags: [go, payment, kafka]
  links:
    - url: https://grafana.company.com/d/payment
      title: Grafana 监控
      icon: dashboard
    - url: https://runbook.company.com/payment-service
      title: Runbook
      icon: docs
spec:
  type: service
  lifecycle: production
  owner: group:payments-team
  system: payment-system
  dependsOn:
    - resource:default/payment-db
    - component:default/order-service
  providesApis:
    - payment-api

批量导入：Backstage 可自动扫描 GitHub 组织所有仓库的 catalog-info.yaml，不需要手动逐个注册。

Scaffolder 模板#

模板由三部分组成：Parameters（表单）、Steps（操作）、Output（链接）。

yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: create-go-service
  title: "创建 Go 微服务"
spec:
  parameters:
    - title: "服务基本信息"
      required: [name, description, owner]
      properties:
        name:
          title: 服务名称
          type: string
          pattern: "^[a-z][a-z0-9-]*[a-z0-9]$"
        owner:
          title: 负责团队
          type: string
          ui:field: OwnerPicker
    - title: "技术选型"
      properties:
        enablePostgres:
          title: 是否使用 PostgreSQL
          type: boolean
          default: false
        deployEnvs:
          title: 部署环境
          type: array
          items:
            type: string
            enum: [dev, staging, production]
          ui:widget: checkboxes

  steps:
    - id: fetch-base
      name: 初始化代码模板
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
    - id: publish
      name: 创建 GitHub 仓库
      action: publish:github
      input:
        repoUrl: "github.com?owner=my-org&repo=${{ parameters.name }}"
    - id: register
      name: 注册到 Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}

  output:
    links:
      - title: 打开代码仓库
        url: ${{ steps.publish.output.remoteUrl }}
      - title: 查看 Catalog
        entityRef: ${{ steps.register.output.entityRef }}

骨架代码模板（skeleton/ 目录）包含实际文件，用 Nunjucks 语法插值——go.mod、main.go、k8s/deployment.yaml、.github/workflows/ci.yml 一次性生成。

插件生态#

最有价值的三个插件：

Kubernetes 插件：直接在 Backstage 看服务的 Pod 状态、部署历史，不需要跑 kubectl。
ArgoCD 插件：显示同步状态、最后一次部署的 commit。
Grafana 插件：关联监控仪表盘，从服务页面一键跳转。

安装：

bash
# 前端插件
yarn --cwd packages/app add @backstage/plugin-kubernetes
# 后端插件
yarn --cwd packages/backend add @backstage/plugin-kubernetes-backend

catalog-info.yaml 关联 K8s 资源：

yaml
annotations:
  backstage.io/kubernetes-id: payment-service
  backstage.io/kubernetes-label-selector: "app=payment-service"

配置后，payment-service 的 Catalog 页面会出现"Kubernetes"Tab，展示 Pod 状态、Deployment 滚动进度、最新日志。

TechDocs：文档即代码#

在 catalog-info.yaml 添加注解：

yaml
annotations:
  backstage.io/techdocs-ref: dir:.

代码仓库根目录添加 mkdocs.yml：

yaml
site_name: "支付服务文档"
nav:
  - 首页: index.md
  - 架构设计: architecture/overview.md
  - 运维手册:
    - 部署流程: ops/deployment.md
    - 告警处理: ops/alerting.md
  - API 文档: api/rest.md
plugins:
  - techdocs-core

文档和代码一起经历 review、版本控制。生产环境推荐用 S3 存储预构建的文档，CI 中自动构建发布。

推广落地#

找准第一个高价值场景。通常最痛的是新服务创建——一个后端服务从立项到第一次生产部署可能要 1-2 天。做一个好用的 Scaffolder 模板，让这个过程缩短到 10 分钟，这就是立竿见影的价值。

让 Catalog 先成为"黄页"。不要一开始就追求大而全，先把所有服务的基本信息录入，让大家养成"找服务信息就上 Backstage 查"的习惯。

运维团队先用起来。给 on-call 工程师配 K8s 插件和 PagerDuty 集成，处理告警时直接在 Backstage 看 Pod 状态。

小结#

Backstage 是构建 IDP 的骨架，真正有用的是往里填什么——服务目录更不更新得动、黄金路径黄不黄金、脚手架是真方便还是又一个祖传 YAML 生成器。Catalog 是基础（catalog-info.yaml 注册所有实体），Scaffolder 是立竿见影的价值（新服务 10 分钟上线），TechDocs 让文档和代码一起版本化，插件生态（K8s/ArgoCD/Grafana）把工具聚合到一个入口。推广要从痛点入手——先做 Scaffolder 解决新服务创建问题，再让 Catalog 成为"黄页"，最后运维团队先用起来带动全员。