〇、写在前面

如果你的公司有超过 3 个微服务，并且每次找个 API 文档都要翻遍 Confluence、SharePoint、钉钉群聊和某位离职同事的脑子，那么恭喜你——你可能需要 Backstage。

如果你的公司只有一个单体应用，那你可以现在就放弃了，省下来的时间去健身房撸个铁不香吗？

Backstage 是 Spotify 在 2020 年开源的内部开发者门户（Internal Developer Portal, IDP），后来捐给了 CNCF，目前是 Incubating 项目。它的核心愿景是：把所有开发者需要的东西，塞进一个统一的界面里。

听起来很美好对吧？就像"我要把所有支付系统统一到一个平台"一样美好。

一、Backstage 是什么？

1.1 一句话定义

Backstage 是一个构建开发者门户的开源框架（注意，是框架，不是开箱即用的产品）。

1.2 核心功能三板斧

1.3 架构全景图

划重点：Backstage 本质上是一个 React + Node.js 的全栈应用，前端是 SPA，后端是一堆插件化的 API 服务。数据存在 PostgreSQL 里，和你的 Git、CI/CD、Cloud 通过插件集成。

二、Software Catalog：你的服务大管家

2.1 核心概念

Catalog 是 Backstage 的灵魂。它用 YAML 文件（catalog-info.yaml）来描述你的软件资产，这些 YAML 文件通常放在各个 Repo 的根目录。

# catalog-info.yaml - 放在你的服务仓库根目录
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: deposit-service
  description: AstraTech 存款服务 - 管理所有存款相关业务
  annotations:
    github.com/project-slug: astratech/deposit-service
    backstage.io/techdocs-ref: dir:.
  tags:
    - java
    - spring-boot
    - payments
  links:
    - url: https://grafana.astratech.ae/d/deposit
      title: Grafana Dashboard
      icon: dashboard
spec:
  type: service
  lifecycle: production
  owner: team-deposit
  system: payment-platform
  providesApis:
    - deposit-api
  consumesApis:
    - npss-api
    - vis-api
  dependsOn:
    - resource:deposit-db
    - component:escrow-service

2.2 实体关系模型

2.3 以 AstraTech 为例

假设要把 Deposit Team 的系统全部注册到 Catalog，大概长这样：

现实检查：要让所有团队都老老实实写 catalog-info.yaml，难度约等于让所有开发者都写单元测试。所以 Backstage 也支持从 LDAP/AD、GitHub Org、Kubernetes 等地方自动发现和导入实体。

三、Software Templates：一键生成标准项目

3.1 它解决什么问题？

每次新建一个微服务，你是不是要：

1. 创建 Git 仓库
2. 复制粘贴某个"模板项目"
3. 改一堆 pom.xml / build.gradle 里的名字
4. 配 CI/CD Pipeline
5. 注册到服务发现
6. 创建 Jira Board
7. 然后发现忘了改某个配置，线上出 Bug

Software Templates 就是把上面这些步骤全部自动化。

3.2 模板工作流

3.3 模板定义示例

# template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: springboot-service
  title: Spring Boot 微服务模板
  description: 创建一个标准的 Spring Boot 微服务，包含 CI/CD 和监控
  tags:
    - java
    - spring-boot
    - recommended
spec:
  owner: team-platform
  type: service

  # === 第一步：收集参数 ===
  parameters:
    - title: 基本信息
      required:
        - name
        - owner
        - description
      properties:
        name:
          title: 服务名称
          type: string
          description: 例如 deposit-service
          pattern: '^[a-z][a-z0-9-]*$'
        owner:
          title: 所属团队
          type: string
          ui:field: OwnerPicker
        description:
          title: 服务描述
          type: string

    - title: 技术选型
      properties:
        javaVersion:
          title: Java 版本
          type: string
          enum: ['17', '21']
          default: '21'
        database:
          title: 数据库
          type: string
          enum: ['postgresql', 'mysql', 'none']
          default: 'postgresql'

  # === 第二步：执行动作 ===
  steps:
    - id: fetch-template
      name: 拉取模板
      action: fetch:template
      input:
        url: ./skeleton  # 模板文件目录
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
          javaVersion: ${{ parameters.javaVersion }}

    - id: publish
      name: 创建 Git 仓库
      action: publish:github
      input:
        allowedHosts: ['github.com']
        repoUrl: github.com?owner=astratech&repo=${{ parameters.name }}
        description: ${{ parameters.description }}

    - id: register
      name: 注册到 Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

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

四、TechDocs：让文档不再躺在 Confluence 里吃灰

4.1 核心理念：Docs as Code

4.2 文档结构

your-service-repo/
├── catalog-info.yaml          # 注册到 Backstage
├── mkdocs.yml                 # MkDocs 配置
├── docs/
│   ├── index.md               # 首页
│   ├── getting-started.md     # 快速开始
│   ├── architecture.md        # 架构说明
│   ├── api-reference.md       # API 参考
│   └── runbook.md             # 运维手册
└── src/
    └── ...                    # 你的代码

# mkdocs.yml
site_name: Deposit Service
nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Architecture: architecture.md
  - API Reference: api-reference.md
  - Runbook: runbook.md
plugins:
  - techdocs-core

真话时间：TechDocs 体验说实话一般般。MkDocs 的渲染能力有限，不支持复杂布局。如果你们已经在用 Confluence 并且用得还行，TechDocs 可能不是迁移的充分理由。

五、插件生态：Backstage 的真正杀手锏

Backstage 本身只是个框架，真正的价值在于插件生态。

5.1 官方 & 热门插件

5.2 插件架构

5.3 写一个自定义插件（伪代码）

// packages/app/src/plugins.ts
// 前端：注册一个显示 NPSS 交易状态的插件

import { createPlugin, createRoutableExtension } from '@backstage/core-plugin-api';

export const npssPlugin = createPlugin({
  id: 'npss-dashboard',
  routes: {
    root: rootRouteRef,
  },
});

export const NpssDashboardPage = npssPlugin.provide(
  createRoutableExtension({
    name: 'NpssDashboardPage',
    component: () =>
      import('./components/NpssDashboard').then(m => m.NpssDashboard),
    mountPoint: rootRouteRef,
  }),
);

六、部署方案

6.1 部署拓扑

6.2 部署选项对比

七、快速上手：10 分钟跑起来

7.1 环境要求

• Node.js 18+ (推荐 20 LTS)
• Yarn 1.x（是的，还是 Classic Yarn 🤦）
• Docker（用于 PostgreSQL）
• Git

7.2 创建项目

# 1. 用官方 CLI 创建
npx @backstage/create-app@latest

# 2. 按提示输入项目名
? Enter a name for the app [required] astratech-portal

# 3. 进入项目
cd astratech-portal

# 4. 启动开发环境
yarn dev

7.3 项目结构

astratech-portal/
├── app-config.yaml           # 主配置文件 ⚡
├── app-config.production.yaml # 生产配置
├── catalog-info.yaml          # Backstage 自身的 catalog 注册
├── packages/
│   ├── app/                   # 前端 React 应用
│   │   ├── src/
│   │   │   ├── App.tsx        # 路由和插件注册
│   │   │   └── components/    # 自定义组件
│   │   └── package.json
│   └── backend/               # 后端 Node.js 应用
│       ├── src/
│       │   └── index.ts       # 后端入口
│       └── package.json
├── plugins/                   # 自定义插件放这里
└── package.json

7.4 核心配置

# app-config.yaml
app:
  title: AstraTech Developer Portal
  baseUrl: http://localhost:3000

backend:
  baseUrl: http://localhost:7007
  database:
    client: pg
    connection:
      host: localhost
      port: 5432
      user: backstage
      password: backstage

auth:
  providers:
    microsoft:  # Azure AD 集成
      development:
        clientId: ${AZURE_CLIENT_ID}
        clientSecret: ${AZURE_CLIENT_SECRET}
        tenantId: ${AZURE_TENANT_ID}

catalog:
  locations:
    # 本地示例
    - type: file
      target: ../../examples/entities.yaml
    # 从 GitHub Org 自动发现
    - type: github-org
      target: https://github.com/astratech
    # 从 GitHub 仓库读取
    - type: url
      target: https://github.com/astratech/deposit-service/blob/main/catalog-info.yaml

八、适用性评估：什么时候该用，什么时候该放弃

8.1 决策流程图

8.2 适用场景 ✅

8.3 不适用场景 ❌

8.4 ROI 估算模型

九、Backstage vs 竞品

十、实施路线图建议

十一、踩坑指南（从放弃到入门？）

🕳️ 坑 1：版本升级是噩梦

Backstage 的发布节奏非常快（几乎每周都有新版本），而且不保证向后兼容。每次升级都可能需要修改大量代码。

# 官方升级工具，但不要太相信它
npx @backstage/cli versions:bump

建议：不要追最新版本。选一个稳定版本，每季度评估一次是否升级。

🕳️ 坑 2：Yarn 1.x 的诅咒

是的，2025 年了，Backstage 官方仍然推荐 Yarn Classic。虽然有社区方案支持 Yarn Berry 和 pnpm，但官方文档和工具链都是基于 Yarn 1.x 的。

🕳️ 坑 3：插件质量参差不齐

官方 marketplace 列出了 200+ 插件，但很多是社区贡献的，质量和维护状态各不相同。使用前一定要检查：最后更新时间、GitHub stars、是否有活跃维护者。

🕳️ 坑 4：认证和权限系统复杂

Backstage 的权限系统（Permission Framework）是后来加的，配置复杂且文档不完善。如果你需要细粒度的 RBAC，准备花不少时间。

🕳️ 坑 5：搜索功能是半成品

内置的搜索引擎（Lunr）只适合小规模使用。大规模部署需要集成 Elasticsearch 或 OpenSearch，额外增加运维负担。

十二、总结：到底该入门还是放弃？

给 AstraTech 的建议

推荐策略：PoC 先行，小步快跑

1. 先做一个 2 周的 PoC：用 Docker Compose 部署一个最小化的 Backstage，把 Deposit Team 的几个核心服务注册进去，让团队感受一下 Software Catalog 的价值。
2. 聚焦 Catalog，暂缓其他：Software Catalog 是最核心也是最容易产生价值的功能。Templates 和 TechDocs 可以后续再加。
3. 评估 Roadie 作为 Plan B：如果 PoC 效果好但没有足够的人力做自建运维，Roadie（托管版 Backstage）是一个合理的备选。
4. 自上而下推动：内部开发者门户必须有管理层支持和强制要求，否则注定成为又一个没人维护的内部项目。

一句话总结

Backstage 就像是开发者世界的"超级 App"——理念超前、生态丰富、但组装难度约等于从零开始拼一台高达。适合有能力有耐心的团队，不适合想要银弹的管理者。

参考资料

• 📖 Backstage 官方文档
• 🐙 Backstage GitHub
• 🔌 Backstage 插件市场
• 🎓 Backstage Community
• 📺 Spotify Engineering Blog - Backstage
• 🏗️ CNCF Backstage Project
• 💰 Roadie - Managed Backstage