name: 内部开发者平台 description: 用于设计内部开发者平台（IDPs）、构建平台团队或改善开发者体验时使用。涵盖平台工程原理、Backstage、门户设计和平台团队结构。 allowed-tools: Read, Glob, Grep
内部开发者平台
设计和构建内部开发者平台（IDPs）的全面指南，以提升开发者生产力和体验。
何时使用此技能
- 设计内部开发者平台
- 构建或重组平台团队
- 改善开发者体验（DevEx）
- 评估平台技术（Backstage、Port等）
- 为开发者创建自服务能力
- 衡量平台采用和成功
平台工程基础
什么是内部开发者平台？
内部开发者平台（IDP）：
基础设施之上的一个层，提供自服务能力给开发团队，同时保持治理。
┌─────────────────────────────────────────────────────────────┐
│ 开发者 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 团队 A │ │ 团队 B │ │ 团队 C │ │ 团队 D │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └────────────┴─────┬──────┴────────────┘ │
│ │ │
│ ┌───────────────────────┴───────────────────────────────┐ │
│ │ 内部开发者平台 │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ 服务目录 │ │ 模板库 │ │ 自服务 │ │ 文档与 │ │ │
│ │ │ │ │ │ │ 门户 │ │ 发现 │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────┴───────────────────────────────┐ │
│ │ 基础设施 │ │
│ │ Kubernetes │ 云 │ CI/CD │ 可观察性 │ 安全 │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
关键价值主张：
├── 自服务：开发者无需工单即可配置
├── 标准化：跨团队的一致模式
├── 护栏：内置安全和合规
├── 可见性：集中式服务目录和文档
└── 效率：减少开发者的认知负荷
平台与基础设施
基础设施团队（传统）：
- 基于工单的请求
- 手动配置
- 每个团队的定制解决方案
- 运维处理部署
- 文档分散
平台团队（现代）：
- 自服务能力
- 自动化配置
- 标准化模板
- 开发者拥有部署
- 集中式文档
关键转变：
"你构建它，你运行它" + "平台处理如何"
平台核心组件
服务目录
服务目录：
所有服务的集中注册表，包含所有权、文档和元数据。
┌─────────────────────────────────────────────────────────────┐
│ 服务目录 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 支付服务 [API] │ │
│ │ 所有者：支付团队 │ 等级：关键 │ │
│ │ 技术：Node.js, PostgreSQL │ 依赖：4 │ │
│ │ [文档] [API规范] [运行手册] [告警] [部署] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 用户服务 [后端] │ │
│ │ 所有者：身份团队 │ 等级：高 │ │
│ │ 技术：Go, MongoDB │ 依赖：2 │ │
│ │ [文档] [API规范] [运行手册] [告警] [部署] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 服务元数据： │
│ ├── 所有者团队和联系人 │
│ ├── 技术栈 │
│ ├── 服务等级/关键性 │
│ ├── 依赖（上游/下游） │
│ ├── API规范 │
│ ├── 文档链接 │
│ ├── 部署信息 │
│ └── 可观察性仪表板 │
└─────────────────────────────────────────────────────────────┘
模板库
模板库：
预构建的常见模式模板，编码最佳实践。
模板类别：
├── 应用模板
│ ├── REST API（Go、Node.js、.NET、Python）
│ ├── GraphQL服务
│ ├── gRPC服务
│ ├── 事件消费者
│ ├── 定时作业
│ └── 前端（React、Vue、Angular）
│
├── 基础设施模板
│ ├── 数据库（PostgreSQL、MySQL、MongoDB）
│ ├── 缓存（Redis、Memcached）
│ ├── 消息队列（Kafka、RabbitMQ）
│ └── 存储（S3、GCS）
│
└── 集成模板
├── 第三方API客户端
├── 认证流程
└── Webhook处理器
模板内容：
┌─────────────────────────────────────────────────────────────┐
│ 模板：node-rest-api │
├─────────────────────────────────────────────────────────────┤
│ ├── src/ │ 应用代码 │
│ ├── tests/ │ 测试设置 │
│ ├── Dockerfile │ 容器镜像 │
│ ├── helm/ │ Kubernetes部署 │
│ ├── .github/workflows/ │ CI/CD流水线 │
│ ├── docs/ │ 文档模板 │
│ ├── catalog-info.yaml │ Backstage注册 │
│ └── terraform/ │ 基础设施即代码 │
│ │
│ 内置： │
│ ✓ 健康检查 ✓ 结构化日志 │
│ ✓ OpenTelemetry追踪 ✓ Prometheus指标 │
│ ✓ 安全头 ✓ 输入验证 │
│ ✓ 错误处理 ✓ API文档 │
└─────────────────────────────────────────────────────────────┘
自服务门户
自服务能力：
开发者无需工单或批准即可执行的操作。
┌─────────────────────────────────────────────────────────────┐
│ 自服务门户 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 创建新服务 [5分钟设置，无需工单] │
│ ├── 选择模板 │
│ ├── 配置选项 │
│ ├── 生成仓库 │
│ ├── 创建CI/CD流水线 │
│ ├── 配置基础设施 │
│ └── 在目录中注册 │
│ │
│ 常见自服务操作： │
│ ┌────────────────┬────────────────┬────────────────┐ │
│ │ 环境 │ 数据库 │ 密钥 │ │
│ │ ├── 创建环境 │ ├── 配置 │ ├── 创建 │ │
│ │ ├── 克隆环境 │ ├── 扩展 │ ├── 轮换 │ │
│ │ └── 销毁 │ └── 备份 │ └── 访问 │ │
│ └────────────────┴────────────────┴────────────────┘ │
│ ┌────────────────┬────────────────┬────────────────┐ │
│ │ 部署 │ 域名 │ 访问 │ │
│ │ ├── 部署 │ ├── 请求 │ ├── 请求 │ │
│ │ ├── 回滚 │ ├── 配置 │ ├── 审核 │ │
│ │ └── 推广 │ └── 证书 │ └── 审计 │ │
│ └────────────────┴────────────────┴────────────────┘ │
│ │
│ 护栏（自动）： │
│ ✓ 安全扫描 ✓ 合规检查 │
│ ✓ 成本限制 ✓ 命名约定 │
│ ✓ 资源配额 ✓ 批准工作流 │
└─────────────────────────────────────────────────────────────┘
平台团队结构
团队拓扑
平台团队类型：
1. 赋能团队（推荐起点）
目的：帮助流对齐团队采用平台
规模：3-5人
活动：
├── 与产品团队结对编程
├── 创建文档和指南
├── 收集反馈和需求
└── 提供培训和支持
2. 平台团队（成熟）
目的：构建和维护平台
规模：5-15人（随组织扩展）
活动：
├── 构建自服务能力
├── 维护模板和工具
├── 定义和执行标准
└── 运营平台基础设施
3. 复杂子系统团队（专业化）
目的：处理复杂技术领域
规模：每个领域3-7人
示例：
├── 数据平台团队
├── ML平台团队
└── 安全平台团队
团队互动：
┌─────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 流对齐 │◄───────►│ 平台 │ │
│ │ 团队 │ X-as-a- │ 团队 │ │
│ └──────────────┘ Service └──────────────┘ │
│ │ │ │
│ │ 协作 │ 促进 │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 复杂 │◄───────►│ 赋能 │ │
│ │ 子系统 │ Service │ 团队 │ │
│ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
平台团队技能
平台团队能力：
技术：
├── Kubernetes和容器编排
├── 基础设施即代码（Terraform、Pulumi）
├── CI/CD流水线设计
├── API设计和开发
├── 可观察性工具
├── 安全工程
└── 云平台（AWS、GCP、Azure）
产品：
├── 开发者体验研究
├── 用户旅程映射
├── 度量和分析
├── 文档写作
└── 培训和赋能
组织：
├── 利益相关者管理
├── 沟通技能
├── 变更管理
└── 技术领导力
平台技术选择
Backstage（Spotify）
Backstage：
Spotify的开源开发者门户框架。
核心功能：
├── 服务目录（软件组件注册表）
├── 软件模板（脚手架）
├── TechDocs（代码即文档）
├── 搜索（统一搜索）
└── 插件（可扩展生态系统）
架构：
┌─────────────────────────────────────────────────────────────┐
│ BACKSTAGE │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 前端（React） │ │
│ │ ├── 目录UI ├── 模板UI ├── 插件 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 后端（Node.js） │ │
│ │ ├── 目录API ├── 认证 ├── 插件API │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 集成 │ │
│ │ ├── GitHub ├── Kubernetes ├── CI/CD │ │
│ │ ├── PagerDuty ├── Prometheus ├── 自定义 │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
目录实体：
# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-service
description: 处理支付流程
annotations:
github.com/project-slug: org/payment-service
backstage.io/techdocs-ref: dir:.
spec:
type: service
lifecycle: production
owner: payments-team
system: payments
dependsOn:
- component:user-service
providesApis:
- payment-api
替代平台
平台选项比较：
| 平台 | 类型 | 优势 | 考虑因素 |
|------------|------------|--------------------------|------------------------|
| Backstage | 开源 | 可扩展，活跃社区 | 需要定制 |
| Port | 商业 | 快速设置，精致UI | 供应商锁定 |
| Cortex | 商业 | SRE专注，评分卡 | 企业定价 |
| OpsLevel | 商业 | 服务成熟度 | 较小生态系统 |
| Roadie | 托管 | 托管Backstage | 较少控制 |
决策因素：
├── 构建与购买的容忍度
├── 定制需求
├── 团队维护能力
├── 集成需求
├── 预算限制
└── 时间线预期
开发者体验度量
DORA度量
DORA（DevOps研究与评估）度量：
1. 部署频率
生产部署的频率
├── 精英：每天多次
├── 高：每周到每月
├── 中：每月到每六个月
└── 低：每六个月以上
2. 变更前置时间
从代码提交到生产的时间
├── 精英：< 1小时
├── 高：1天到1周
├── 中：1周到1月
└── 低：1月到6个月
3. 平均恢复时间（MTTR）
从生产故障恢复的时间
├── 精英：< 1小时
├── 高：< 1天
├── 中：< 1周
└── 低：1周到1月
4. 变更失败率
导致失败的部署百分比
├── 精英：0-15%
├── 高：16-30%
├── 中：31-45%
└── 低：46-60%
平台特定度量
平台成功度量：
采用：
├── 目录中服务百分比
├── 使用模板的团队百分比
├── 自服务使用率
├── 门户活跃用户
└── 模板利用率
效率：
├── 首次部署时间（新服务）
├── 配置基础设施时间
├── 工单减少率
├── 苦工自动化百分比
└── 开发者节省时间
满意度：
├── 开发者NPS
├── 平台满意度调查
├── 支持工单量
├── 文档有用性
└── 入职反馈
质量：
├── 模板采用 vs 自定义构建
├── 安全合规率
├── 标准遵循
└── 平台构建服务的事件率
实施路线图
分阶段方法
阶段1：基础（3-6个月）
├── 服务目录（盘点现有内容）
├── 基本文档站点
├── 初始模板（1-2个黄金路径）
├── 平台团队组建
└── 度量基线
阶段2：自服务（6-12个月）
├── 模板库扩展
├── 自服务配置
├── CI/CD标准化
├── 开发者门户启动
└── 采用活动
阶段3：优化（12-18个月）
├── 高级模板
├── 平台API
├── 自动化扩展
├── 成本优化
└── 高级分析
阶段4：生态系统（18+个月）
├── 插件生态系统
├── ML/数据平台集成
├── 跨团队协作功能
├── 外部开发者体验
└── 持续演进
每阶段成功标准：
阶段1：50%服务发现完成
阶段2：70%新服务使用模板
阶段3：80%自服务能力
阶段4：平台不可或缺
常见反模式
平台反模式：
1. "构建它，他们就会来"
❌ 没有用户研究就构建功能
✓ 从开发者访谈和痛点开始
2. "一刀切"
❌ 强迫每个团队进入相同工作流
✓ 提供灵活性，有合理默认
3. "平台作为守门人"
❌ 增加摩擦和批准关卡
✓ 启用自服务，有护栏
4. "技术纯粹性"
❌ 选择平台团队兴奋的技术
✓ 选择解决开发者问题的技术
5. "大爆炸发布"
❌ 构建2年才发布
✓ 与早期采用者快速迭代
6. "没有价值的强制"
❌ 通过政策强制采用
✓ 让平台如此好，团队想用
7. "文档事后考虑"
❌ 最小化或过时文档
✓ 将文档视为产品功能
8. "象牙塔平台"
❌ 平台团队与用户隔离
✓ 定期嵌入产品团队
最佳实践
平台工程最佳实践：
1. 将平台视为产品
├── 有产品所有者/经理
├── 进行用户研究
├── 基于影响优先
└── 衡量结果，而非输出
2. 从黄金路径开始
├── 识别最常见用例
├── 为这些创建模板
├── 让黄金路径最容易选择
└── 不阻止非黄金路径
3. 优化自服务
├── 目标常见任务 <5分钟
├── 在安全时消除手动批准
├── 提供逃生通道
└── 清晰的错误消息和指导
4. 构建社区
├── 开发者倡导者/冠军
├── 办公时间和支持渠道
├── 贡献指南
└── 庆祝平台胜利
5. 测量一切
├── 采用度量
├── 开发者满意度
├── 时间节省
└── 平台可靠性
6. 快速迭代
├── 早期发布，经常改进
├── 持续收集反馈
├── 优雅废弃
└── 清晰沟通变更
相关技能
golden-paths- 设计标准化开发工作流self-service-infrastructure- 基础设施自服务模式slo-sli-error-budget- 平台可靠性目标observability-patterns- 平台可观察性