内部开发者平台（IDP）工程化：Backstage、Golden Path 与自服务能力

现代开发者要掌握的"基础设施知识"：
  K8s + Helm + Terraform + CI 流水线 + 可观测性 + 密钥管理 + 网络策略...

问题：
  - 每个团队重复搭脚手架，浪费大量时间
  - 团队各自为政 → 环境不一致、安全基线不一、维护成本高
  - 新同学 onboarding 要学几个月才能"独立交付"

平台工程的解法：
  平台团队把复杂抽象成"简单入口"，开发者走 Golden Path 自服务交付

不是替代，而是接力：
  DevOps 解决"要不要自己管"，平台工程解决"怎么管才不累"

平台工程是 DevOps 的进阶形态：
  把反复出现的模式（环境/流水线/部署）固化为平台能力
  → 开发团队从"每个都自己做"变成"用平台的标准能力快速组合"

平台团队不该做的：
  - 什么都自己做（垄断能力，让开发更依赖）
  - 只做工具不管体验（做出来没人用）

平台团队该做的：
  - 提供"最小可用 + 持续演进"的黄金路径
  - 收集反馈迭代，让平台成为开发者的"默认选择"

开发者门户 = IDP 的用户界面（单一入口）：
  - 服务目录：所有服务一览（谁拥有、状态、文档）
  - 软件模板：点几下生成新服务脚手架
  - 自助动作：申请环境/权限/发布（不用提工单）
  - 技术文档：内嵌的工程知识库

# catalog-info.yaml：把一个服务注册进 Backstage 目录
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  description: "订单服务"
  annotations:
    github.com/project-slug: shop/shop-api
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: team-checkout
  system: shop-platform

Backstage 三块核心：
  - Software Catalog（服务目录，带 owner 与依赖关系）
  - Scaffolder（软件模板，生成新服务脚手架）
  - TechDocs（内嵌技术文档，随代码更新）

Golden Path（黄金路径）= 平台预定义、受支持、默认推荐的交付路径
  - 覆盖：脚手架 → 构建 → 测试 → 部署 → 监控
  - 特点：经过验证、安全默认、一条路走到底
  - 意义：把"最正确的做法"固化成"最容易的路径"

开发者可以偏离（走自定义路径），但要承担额外风险与维护

# template.yaml：Backstage 软件模板（生成 Go 服务 + CI + 部署清单）
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: go-service
  title: Go Service with CI/CD
spec:
  owner: platform
  parameters:
    - title: 基本信息
      properties:
        serviceName:
          type: string
          description: 服务名（小写）
  steps:
    - id: fetch-template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          serviceName: ${{ parameters.serviceName }}
    - id: publish
      action: publish:github
      input:
        repoUrl: github.com?owner=shop&repo=${{ parameters.serviceName }}
    - id: register
      action: catalog:register

# 脚手架产出（概念）
#   $serviceName/
#     ├── Dockerfile
#     ├── Makefile
#     ├── deploy/k8s/ (Deployment + Service + HPA)
#     ├── .github/workflows/ci.yml
#     └── README.md

  - 默认安全：镜像扫描、密钥管理、非 root 开箱即用
  - 默认可观测：日志/Trace/指标接入模板自带
  - 默认可回滚：发布策略内置（金丝雀 + 自动回滚）
  - 模板本身要当"代码"维护：升级后全平台受益

平台在 IDP 里提供一个"创建预览环境"的动作：
  - 选择服务 + 分支 → 平台自动生成 namespace + 部署 + 入口
  - 环境带 TTL，过期自动回收
  - 开发者不用懂 K8s，点按钮即可

本质：把之前手动做的"环境工程"变成平台的一个 REST 动作

# 平台后端动作示例（概念）
curl -X POST https://idp.internal/api/environments \
  -H "Authorization: Bearer $IDP_TOKEN" \
  -d '{"service":"shop-api","branch":"feature/pay","ttl":"6h"}'

  - 角色即权限：开发/运维/只读等预定义角色
  - 申请走平台：请求角色 → 自动/人工审批 → 生效
  - 最小权限默认：新服务只给基础角色，扩展要申请
  - 定期权限审计：清理僵尸权限

第一级 业务级（DORA）：平台是否让交付更快更稳
  - 部署频率（Deployment Frequency）
  - 变更前置时间（Lead Time for Change）
  - 恢复时间（MTTR）
  - 变更失败率（Change Failure Rate）

第二级 开发者体验（SPACE）：平台是否真的好用
  - Satisfaction：满意度
  - Performance：效率
  - Activity：活跃度
  - Communication：协作
  - Efficiency：顺畅度（少打断、少切换）

# 从 CI/CD 平台自动采集（概念）
deployment_frequency:     # 每次生产部署计一次
lead_time_for_change:     # 提交 → 上线 的时长
change_failure_rate:      # 生产事故/发布次数
mttr:                     # 从发现到恢复的时间

关键：DORA 是"结果指标"，SPACE 是"体验指标"
  只看 DORA 可能"数字好看但开发痛苦"（靠加班堆出来的快）
  两者结合：快 + 爽 = 平台真的成功

  - 服务目录覆盖率（多少服务已接入平台）
  - 黄金路径使用率（开发者是否默认走平台）
  - 自助动作成功率（环境/权限申请一次性通过率）
  - DORA 趋势（部署频率、变更失败率）
  - 开发者 NPS（定期调研）

  - 模板生成的仓库自带标准 CI 流水线（Build/Test/Security/Deploy）
  - 平台提供发布策略组件：金丝雀、蓝绿、自动回滚
  - 平台动作与流水线互相触发：
    开发者点"创建环境" → 平台调 CI 部署预览环境
    流水线完成 → 平台更新服务目录状态

# 流水线结尾调用平台 API 更新状态（概念）
- name: Update catalog
  run: |
    curl -X PATCH https://idp.internal/api/catalog/shop-api \
      -H "Authorization: Bearer $IDP_TOKEN" \
      -d '{"deployedAt":"'$(date -u)'","version":"'${GITHUB_SHA}'"}'

  - 平台是"指挥层"：定义黄金路径与策略
  - CI/CD 是"执行层"：跑构建测试部署
  - 两者的契约：统一的模板、统一的密钥、统一的可观测性

  - 平台模板产出 ArgoCD Application 清单
  - 发布晋升（preview → staging → prod）由平台编排
  - 开发者只操作平台界面，底层 GitOps 自动推进

阶段一（0→1）：先有"一条黄金路径"
  选一个典型服务类型（如 Go API），打通脚手架→CI→部署→监控
  验证：一个团队用起来，跑通端到端

阶段二（1→N）：能力产品化
  加自服务环境、权限、发布；扩到更多服务类型
  验证：多数团队走黄金路径，不再各自为政

阶段三（N→全）：平台规模化
  加开发者门户（目录/模板/文档）、自动审批、数据驱动迭代
  验证：DORA 与开发者体验双提升

  - 先做"最小黄金路径"再扩展，不要上来就建大平台
  - 平台能力跟着真实需求走（哪个团队痛，先解决哪个）
  - 平台团队要有"产品负责人"，收集反馈排优先级
  - 老服务逐步迁移，不强制一刀切

□ 先选一条黄金路径打通端到端，再横向扩展
□ 开发者门户（Backstage/Port/自研）提供单一入口
□ 模板默认安全/可观测/可回滚
□ 环境/权限/发布三大自服务能力落地
□ DORA + SPACE 双维度度量平台效果
□ 平台与 CI/CD 双向联动，状态实时回写
□ 平台团队有产品思维：收集反馈、迭代优先级
□ 老服务渐进迁移，保留自定义路径的退出通道

平台工程 = "把最正确的路修得最宽，
让开发不是‘不能犯错’，而是‘难以犯错’。"