How to Build an Internal Developer Platform: A Complete Guide to Backstage, ArgoCD, and Crossplane

git clone https://github.com/aayostem/platform-toolkit
cd platform-toolkit

层1：开发者界面（Backstage）
├── 软件目录 —— 所有服务、API和资源的清单
├── 软件模板 —— 触发供应工作流程的自助服务表单
├── TechDocs —— 与每个目录实体共存的文档
└── 插件 —— 与ArgoCD、Kubernetes、PagerDuty、Grafana的集成

层2：交付层（ArgoCD）
├── GitOps同步 —— 持续将集群状态与Git保持一致
├── ApplicationSets —— 从单一定义中进行多环境部署
├── 发布管理 —— 带健康检查的渐进式交付
└── 审计追踪 —— 每个部署变更都链接到Git提交

层3：基础设施层（Crossplane）
├── 组合资源 —— 作为Kubernetes CRD定义的云资源
├── Compositions —— 将简单声明扩展为完整AWS基础设施的模板
├── ProviderConfigs —— 每个云提供商的凭证和区域配置
└── 使用跟踪 —— 每个已分配资源都标记团队和成本中心

开发者 → Backstage 模板 → Git 提交 → ArgoCD → Crossplane → AWS
                                     ↑
                          单一真实来源
                          完整审计追踪
                          回滚 = git revert

// 错误：Backstage 模板直接调用 AWS SDK
// 没有审计追踪，没有回滚，没有 reconciliation 循环
// 如果调用中途失败，您将拥有无记录的部分基础设施
import { S3Client, CreateBucketCommand } from "@aws-sdk/client-s3";

const client = new S3Client({ region: "us-east-1" });
await client.send(new CreateBucketCommand({ Bucket: bucketName }));

# 正确：Backstage 模板输出 —— 提交到 Git 的 Crossplane 声明
# ArgoCD 应用它，Crossplane 进行 reconciliation，AWS 创建存储桶
# 每个步骤都可追踪、可审计、可逆
apiVersion: platform.cloudfrugal.com/v1alpha1
kind: S3Bucket
metadata:
  name: ${{ values.bucket_name }}
  namespace: ${{ values.team_namespace }}
  labels:
    team: ${{ values.team_name }}
    cost-centre: ${{ values.cost_centre }}
    environment: ${{ values.environment }}
spec:
  versioning: true
  encryption: AES256
  region: us-east-1

步骤1：ArgoCD —— 所有其他内容依赖的交付基础
步骤2：Crossplane —— 基础设施控制平面，由 ArgoCD 提供
步骤3：Backstage —— 门户，指向 ArgoCD 和 Crossplane 作为后端
步骤4：连接集成 —— 生成 GitOps 清单的软件模板
步骤5：FinOps 层 —— 每个已配置资源中的成本归属元数据

# 创建 ArgoCD 命名空间
kubectl create namespace argocd

# 使用官方清单文件安装 ArgoCD
kubectl apply -n argocd \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# 在继续之前等待所有 Pod 运行就绪
kubectl wait --for=condition=Ready pods \
  --all -n argocd --timeout=300s

# 获取初始管理员密码
argocd_password=$(kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d)

echo "ArgoCD 初始密码: $argocd_password"
echo "在继续之前请将此密码保存在安全的位置"

# 通过端口转发本地访问 ArgoCD UI
kubectl port-forward svc/argocd-server -n argocd 8080:443 &

# 通过 CLI 登录
argocd login localhost:8080 \
  --username admin \
  --password "$argocd_password" \
  --insecure

# 立即修改密码
argocd account update-password \
  --current-password "$argocd_password" \
  --new-password "your-secure-password"

gitops-repo/
├── apps/
│   ├── base/                    # 所有环境共享的配置
│   │   ├── payment-api/
│   │   │   ├── deployment.yaml
│   │   │   ├── service.yaml
│   │   │   └── kustomization.yaml
│   │   └── user-api/
│   │       ├── deployment.yaml
│   │       ├── service.yaml
│   │       └── kustomization.yaml
│   └── overlays/
│       ├── staging/             # 预发布环境的覆盖配置
│       │   ├── payment-api/
│       │   │   └── kustomization.yaml   # 覆盖配置：1 个副本，预发布镜像标签
│       │   └── kustomization.yaml
│       └── production/          # 生产环境的覆盖配置
│           ├── payment-api/
│           │   └── kustomization.yaml   # 覆盖配置：3 个副本，固定镜像标签
│           └── kustomization.yaml
└── infrastructure/
    ├── crossplane/              # Crossplane 安装和提供者
    ├── monitoring/              # Prometheus, Grafana
    └── ingress/                 # NGINX 或 ALB 入口控制器

验证 ApplicationSet 是否生成了预期的应用程序：

### 2.4 平台团队的 ArgoCD RBAC

在多团队 IDP 中，不同团队需要对 ArgoCD 有不同级别的访问权限。应用程序团队应能查看和同步自己的应用程序。平台团队应拥有更广泛的访问权限。没有人应能通过 ArgoCD 获得无限制的集群管理员权限。

默认策略是只读 —— 每个经过身份验证的用户可以看到所有内容但无法进行任何更改：

## 第 3 部分：Crossplane — 将基础设施作为 Kubernetes 资源

Crossplane 是一个 CNCF 毕业的开源框架，它将 Kubernetes 扩展为一个通用的基础设施控制平面。

核心思想：与其使用 Terraform 或 CloudFormation 等独立于集群的工具来管理云资源，不如将云资源（如 RDS 数据库、S3 存储桶、VPC 和 IAM 角色）定义为 Kubernetes 自定义资源定义。

当将 Crossplane 资源应用到集群后，Crossplane 的控制器会接管并协调期望状态与实际 AWS 状态的一致性，这一过程与 Kubernetes 协调 Deployment 到运行中的 Pod 集合的方式完全一致。

Crossplane 在此基础上增加的关键抽象是组合资源（Composite Resource）。平台团队可以定义一个高级的 PostgreSQLDatabase 类型，该类型封装了实际 RDS 实例所需的三十多个配置字段。

开发者只需与简化后的类型进行交互。Crossplane 会在后台将其扩展为完整的 AWS 资源配置，自动应用平台团队的安全和运维标准——这些标准开发者无法绕过，因为他们根本看不到底层字段。

### 3.1 安装 Crossplane

Crossplane 通过 ArgoCD 部署到你的集群——这是两个工具的首次集成。通过 ArgoCD Application 安装 Crossplane 而不是直接运行 helm install，可以将 Crossplane 本身纳入 GitOps 管理的基础设施中。任何对 Crossplane 配置的更改都需要经过 Git 提交和代码审查：

### 3.2 提供商凭证

Crossplane 需要 AWS 凭证来创建资源。对于 EKS，推荐使用 IAM Roles for Service Accounts（IRSA）——这是一种允许 Kubernetes Pod 直接担任 IAM 角色而无需在集群中存储任何凭证的机制。

Pod 的 Kubernetes 服务账户会标注 IAM 角色 ARN，当 Pod 发起 API 调用时，AWS 会自动提供短期凭证。无需访问密钥，无需轮换密钥，也无需暴露凭证：

### 3.3 定义复合资源 —— PostgreSQL数据库

这是IDP抽象的实现位置。平台团队定义两个YAML文件：定义开发者可请求资源形状的CompositeResourceDefinition（XRD），以及定义请求如何扩展为实际AWS资源并应用平台标准的Composition。

XRD是与开发者之间的API契约。保持简洁 —— 仅包含开发者真正需要控制的字段：

Composition是平台团队的实现。它将简单的开发者字段映射到完整的RDS配置，并强制执行开发者无法覆盖的平台标准：

现在申请 PostgreSQL 数据库的开发者只需编写以下内容即可：

Crossplane 会在几分钟内将此声明转换为完整的RDS实例，自动应用加密、备份和所有平台标准。

### 3.4 验证 Crossplane 资源供应

# 验证实际 AWS 资源是否已创建
aws rds describe-db-instances \
  --query 'DBInstances[?TagList[?Key==`team` && Value==`payments`]].[DBInstanceIdentifier,DBInstanceStatus]' \
  --output table

# 创建一个新的 Backstage 应用
npx @backstage/create-app@latest

# 当被提示时：
# 应用名称：platform-portal
# 本地开发选择 SQLite，生产环境选择 PostgreSQL

cd platform-portal

# app-config.production.yaml
app:

  baseUrl: https://platform.your-company.com

backend:
  baseUrl: https://platform.your-company.com
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: 5432
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
      database: backstage

# GitHub 集成用于目录发现和模板脚手架
integrations:
  github:
    - host: github.com
      apps:
        - appId: ${GITHUB_APP_ID}
          webhookSecret: ${GITHUB_WEBHOOK_SECRET}
          clientId: ${GITHUB_CLIENT_ID}
          clientSecret: ${GITHUB_CLIENT_SECRET}
          privateKey: ${GITHUB_PRIVATE_KEY}

# ArgoCD 插件配置
argocd:
  username: ${ARGOCD_USERNAME}
  password: ${ARGOCD_PASSWORD}
  appLocatorMethods:
    - type: 'config'
      instances:
        - name: main
          url: https://argocd.your-company.com

# 目录自动发现 —— 在您的 GitHub 组织中查找 catalog-info.yaml 文件
catalog:
  providers:
    github:
      your-org:
        organization: 'your-github-org'
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: 'main'

# catalog-info.yaml — 提交到每个服务仓库的根目录
# Backstage 通过 GitHub 集成会自动发现此文件
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-api

  description: "核心支付处理服务。负责交易发起、授权和结算。"
  annotations:
    # 将 ArgoCD 链接到 Backstage UI 显示部署状态
    argocd/app-name: production-payment-api
    # 链接 GitHub Actions 工作流状态
    github.com/project-slug: your-org/payment-api
    # 链接该服务的 Grafana 仪表盘
    grafana/dashboard-selector: "title=Payment API"
    # 链接 PagerDuty 值班时间表
    pagerduty.com/service-id: P123456
  tags:
    - 支付
    - typescript
    - 关键服务
  links:
    - url: https://payment-api.docs.your-company.com

    - url: https://grafana.your-company.com/d/payment-api

spec:
  type: 服务
  lifecycle: 生产环境
  owner: group:payments-team
  system: 支付平台
  dependsOn:
    - component:user-api
    - resource:payment-service-db
  providesApis:
    - payment-api-v2

# templates/postgresql-database/template.yaml
# 该模板为开发者提供一个表单以申请 PostgreSQL 数据库
# 输出是一个提交到 GitOps 仓库的 Crossplane PostgreSQLDatabase 声明
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: postgresql-database

  description: 在 AWS RDS 上配置托管的 PostgreSQL 数据库。平台会自动配置加密、备份和删除保护。
  tags:
    - 数据库
    - postgresql
    - aws
spec:
  owner: group:platform-team
  type: 基础设施

  # 开发者在 Backstage UI 中填写的表单
  parameters:
    - title: 数据库配置
      required: [name, team, environment, storageGB, instanceClass]
      properties:
        name:

          type: string
          description: "仅小写字母和连字符。例如 payment-service-db"
          pattern: '^[a-z][a-z0-9-]*$'

        team:

          type: string
          description: "您的团队名称。用于成本归属和所有权。"
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group

        environment:

          type: string
          enum: [staging, production]
          default: staging

        storageGB:

          type: integer
          minimum: 20
          maximum: 1000
          default: 50

        instanceClass:

          type: string
          enum: [small, medium, large]
          enumNames:
            - "小型 (db.t4g.medium) — 开发/预发布工作负载"
            - "中型 (db.r7g.large) — 中等生产流量"
            - "大型 (db.r7g.2xlarge) — 高吞吐量生产环境"
          default: small

  # 提交模板后执行的操作
  steps:
    - id: generate-claim
      name: 生成 Crossplane 声明
      action: fetch:template
      input:
        url: ./skeleton    # 包含 Crossplane 声明 YAML 模板
        values:
          name: ${{ parameters.name }}
          team: ${{ parameters.team | parseEntityRef | pick('name') }}
          environment: ${{ parameters.environment }}
          storageGB: ${{ parameters.storageGB }}
          instanceClass: ${{ parameters.instanceClass }}

    - id: create-pr
      name: 向 GitOps 仓库创建 Pull Request
      action: publish:github:pull-request
      input:
        repoUrl: github.com?repo=gitops-repo&owner=your-org

        branchName: "provision-db-${{ parameters.name }}-${{ '' | now }}"
        description: |
          请求通过 Crossplane 部署 PostgreSQL 数据库。

          - **名称:** ${{ parameters.name }}
          - **团队:** ${{ parameters.team }}
          - **环境:** ${{ parameters.environment }}
          - **存储:** ${{ parameters.storageGB }}GB
          - **实例规格:** ${{ parameters.instanceClass }}

          批准此 PR 以触发部署。ArgoCD 将检测到变更，Crossplane 在合并后约 5 分钟内创建 RDS 实例。
        sourcePath: ./skeleton

  output:
    links:
      - title: 查看 Pull Request
        url: ${{ steps['create-pr'].output.remoteUrl }}
      - title: 在 ArgoCD 中跟踪部署
        url: https://argocd.your-company.com/applications

# templates/postgresql-database/skeleton/databases/${{ values.name }}.yaml
apiVersion: platform.cloudfrugal.com/v1alpha1
kind: PostgreSQLDatabase
metadata:
  name: ${{ values.name }}
  namespace: ${{ values.team }}-platform
  labels:
    team: ${{ values.team }}
    cost-centre: ${{ values.team }}-engineering
    environment: ${{ values.environment }}
    managed-by: backstage-scaffolder
spec:
  storageGB: ${{ values.storageGB }}
  instanceClass: ${{ values.instanceClass }}
  environment: ${{ values.environment }}

开发者在 Backstage 填写表单
    ↓
Backstage 软件模板渲染 Crossplane 声明 YAML
    ↓
Backstage 在 GitOps 仓库中创建 Pull Request
    ↓
平台工程师（或自动合并策略）批准并合并 PR
    ↓
ArgoCD 检测到 GitOps 仓库中的新文件
    ↓
ArgoCD 将 Crossplane 声明应用到集群
    ↓
Crossplane 将声明同步为实际的 AWS RDS 实例
    ↓
开发者通过 Kubernetes Secret 接收数据库端点
    ↓
Backstage 目录显示新资源，由请求团队拥有

# 安装 Kubernetes 插件包
cd platform-portal
yarn --cwd packages/app add @backstage/plugin-kubernetes
yarn --cwd packages/backend add @backstage/plugin-kubernetes-backend

# app-config.production.yaml — 添加 Kubernetes 集群配置
kubernetes:
  serviceLocatorMethod:
    type: 'multiTenant'
  clusterLocatorMethods:
    - type: 'config'
      clusters:
        - name: production-eks
          url: ${PRODUCTION_CLUSTER_URL}
          authProvider: serviceAccount
          serviceAccountToken: ${PRODUCTION_SA_TOKEN}
          caData: ${PRODUCTION_CA_DATA}
        - name: staging-eks
          url: ${STAGING_CLUSTER_URL}
          authProvider: serviceAccount
          serviceAccountToken: ${STAGING_SA_TOKEN}
          caData: ${STAGING_CA_DATA}

# 在每个服务的 catalog-info.yaml 中
annotations:
  backstage.io/kubernetes-label-selector: 'app=payment-api'
  backstage.io/kubernetes-namespace: payments-team

yarn --cwd packages/app add @roadiehq/backstage-plugin-argo-cd

// packages/app/src/components/catalog/EntityPage.tsx
import { EntityArgoCDOverviewCard } from '@roadiehq/backstage-plugin-argo-cd';

// 添加到服务实体页面布局
const serviceEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      <Grid container spacing={3}>
        <Grid item md={6}>
          <EntityAboutCard variant="gridItem" />
        </Grid>
        <Grid item md={6}>
          {/* ArgoCD 部署状态 —— 显示同步状态和最近部署 */}
          <EntityArgoCDOverviewCard />
        </Grid>
      </Grid>
    </EntityLayout.Route>
  </EntityLayout>
);

Crossplane Compositions 是强制执行成本归属的关键位置 —— 不是在面向开发者的声明中，而是在开发者无法绕过的平台层。这些标签会传递到实际的 AWS 资源作为标签，这意味着它们会出现在 AWS Cost Explorer 中，并可用于生成团队级别的成本报告：

### 6.2 成本归属查询

通过在每个资源上添加强制性标签，你可以直接从 AWS Cost Explorer 查询团队的实际成本：

现在每个通过 IDP 部署资源的团队都会在成本报告中拥有自己的条目并显示团队名称。这种自动化的成本归属模式使 FinOps 在平台规模上得以持续运行 —— 归属是自动完成的，而非人工操作。

## 第7部分：平台成熟度模型 —— 评估你已构建的内容

CNCF 平台工程成熟度模型定义了五个平台成熟度级别。了解你所处的阶段有助于决定下一步要构建什么，并向工程领导层传达进展。

| 等级 | 名称       | 特征描述                                       |
|------|------------|------------------------------------------------|
| 1    | 临时性     | 临时脚本、手动部署、没有标准工具               |
| 2    | 运营性     | 标准化工具、部分自动化、正在使用 Kubernetes    |
| 3    | 可扩展性   | 自助服务门户、GitOps 部署、文档化的黄金路径    |
| 4    | 优化中     | 成本归属、平台自身的 SLO、用户反馈循环         |
| 5    | 优化完成   | AI 辅助部署、预测性扩展、完整的 FinOps 集成    |

完整的 Backstage + ArgoCD + Crossplane 实现，包含成本归属和覆盖常见开发者需求的软件模板，将使你达到等级 3。要升级到等级 4，需要在平台自身健康状况上添加 SLO 告警、每季度进行开发者体验调查，并从归属标签生成月度按团队划分的成本报告。

等级 3 最常见的错误：构建更多功能而非衡量采用率。一个拥有 12 个软件模板但只有 2 个被频繁使用的平台并未达到等级 3 —— 它实际上处于等级 2，只是拥有更多 YAML。要衡量哪些黄金路径被使用，采访未使用门户的开发者，并在添加新功能前解决摩擦点。

## 最佳实践总结

✅ 做法：按顺序构建 —— 先构建 ArgoCD，然后是 Crossplane，最后是 Backstage。每一层都依赖于前一层。

✅ 做法：将 Backstage 用作 Git 提交生成器，而非基础设施调用工具。所有基础设施变更必须通过可审计的 Git 提交实现。

✅ 做法：在 Crossplane 的 Composition 层应用成本归属标签，而非在开发者声明中设置。开发者可绕过的归属机制最终会被绕过。

✅ 做法：从两到三个软件模板起步，并在构建更多模板前确保它们的卓越性。模板采用率是早期最重要的衡量指标。

✅ 做法：从第一天起就将每个服务注册到 Backstage 目录中。目录的价值与其覆盖范围成正比。

✅ 做法：通过 ArgoCD 而非 helm install 将 Crossplane 部署到集群。IDP 管理的所有内容都应由 IDP 自身管理。

❌ 不要：直接将 Backstage 连接到云 API。这会导致无审计追踪、无法回滚、无一致性保障。

❌ 不要：直接向开发者提供 Crossplane XRD。Composition 抽象层的存在是为了隐藏 RDS 特定配置并强制平台标准。绕过它将违背其初衷。

❌ 不要：孤立构建 IDP 并宣布完成。平台工程即产品工程。在前两个模板上线后安排用户访谈。

❌ 不要：跳过 ArgoCD 的 RBAC 配置。通过交付层向所有开发者授予 cluster-admin 权限的 IDP 会制造比它解决的问题更大的安全风险。

## 资源

- Backstage 文档 —— 插件开发、软件模板和目录配置的官方参考

- Crossplane 文档 —— CompositeResourceDefinition 和 Composition 参考，提供者安装指南

- ArgoCD 文档 —— ApplicationSet 生成器参考、RBAC 配置和同步策略选项

- CNCF 平台工程成熟度模型 —— 第 7 部分引用的成熟度框架

- Crossplane 的 AWS 提供者 —— Crossplane 可用所有 AWS 资源类型的完整参考

- Backstage Kubernetes 插件 —— 第 5 部分 Kubernetes 资源可视化的设置指南

- FinOps 基金会 —— 面向平台工程的 FinOps —— 第 6 部分成本归属模型的框架参考

- 附加工具库 —— 本指南中所有清单、Composition、ApplicationSet 和 Backstage 模板

- 2025 年 DORA 人工智能辅助软件开发现状报告

Ayobami Adejumo 是专注于种子轮和 A 轮公司基础设施转型的高级平台工程师。他曾就职于埃克森美孚并参与多个 B2B SaaS 团队的工作。

如果本文对你有帮助，请分享它。

免费学习编程。freeCodeCamp 的开源课程已帮助超过 40,000 人成为开发者。立即开始

ADVERTISEMENT