backstage

Backstage 开发者门户

补充说明

Backstage 是 CNCF 的开发者门户框架，用软件目录、模板、TechDocs 和插件把服务、文档、流水线和基础设施入口集中到一个界面。适合平台工程做自助服务入口。

核心概念：catalog、entity、template、plugin、TechDocs、scaffolder。

常用示例

创建应用：

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

启动后访问 http://localhost:3000。

注册组件（catalog-info.yaml）：

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  annotations:
    github.com/project-slug: example/order-service
spec:
  type: service
  lifecycle: production
  owner: team-a
  system: commerce

启动模板放在 templates/，通过 backstage.io/v1beta3 Template 定义参数和步骤。

生产构建：

yarn build
yarn workspace backend start

易错点与排错

• catalog-info.yaml 的 owner 或 system 不存在，实体注册失败。
• 插件版本与 Backstage 主版本不兼容，启动报错。
• GitHub/GitLab 集成 token 权限不足，目录无法同步。
• TechDocs 没有配置存储，文档构建后不可访问。
• 模板步骤中的 action 没有安装对应插件。
• 生产部署没有配置 PostgreSQL 和外部存储。
• 门户没有 SSO，权限和审计缺失。
• 插件太多，升级和维护成本高。