平台工程与内部开发者平台建设指南
平台工程不是再造一个“万能运维平台”，也不是把 Kubernetes、CI/CD 和工单系统换一个界面重新包装。它的目标是把组织内反复出现、容易出错的交付与运行工作整理成可复用的产品能力，让开发团队通过安全的自助入口完成环境申请、服务创建、发布、观测和回滚，同时由平台团队提供默认标准、权限边界和持续支持。
本文面向准备建设内部开发者平台（Internal Developer Platform，IDP）的运维、研发效能、SRE 和技术管理人员。示例强调方法和治理，不绑定某一家产品。
一、为什么会出现平台工程
当团队规模较小时，研发可以直接找运维申请服务器、数据库和发布权限。随着服务、环境和团队数量增加，常见问题会逐渐出现：
- 同一种应用存在多套脚手架、部署流程和监控标准；
- 新项目需要重复申请仓库、流水线、域名、证书、数据库和告警；
- 运维成为所有交付请求的人工中转站；
- 开发需要理解大量基础设施细节，仍然容易漏配备份、限额或监控；
- 平台提供了很多工具，但用户不知道该从哪里开始；
- 自动化脚本无人维护，失败后也缺少责任人、审计和回退。
平台工程通过“标准能力 + 自助服务 + 产品化运营”解决这些问题。它与 DevOps、SRE 的关系可以这样理解：
| 概念 | 主要关注点 | 典型产物 |
|---|---|---|
| DevOps | 打破研发与运维之间的交付壁垒 | 协作流程、自动化流水线、持续反馈 |
| SRE | 用工程方法管理可靠性 | SLI/SLO、错误预算、事件响应、容量模型 |
| 平台工程 | 把重复能力做成可消费的内部产品 | 服务目录、黄金路径、模板、自助工作流、平台 API |
平台工程不是 DevOps 的替代品。没有清晰的服务所有权、变更流程和可靠性目标，只增加一个门户不会自动改善交付效率。
二、先定义平台的用户和问题
建设前不要先问“选 Backstage 还是自己开发”，应先回答以下问题：
- 谁是平台用户：应用开发、数据团队、测试、运维，还是全部人员？
- 当前最耗时的三类请求是什么？
- 哪些错误频繁发生且可以用默认值避免？
- 哪些操作必须审批，哪些可以安全自助？
- 用户完成任务需要跨越多少系统？
- 平台失败时，用户有没有绕行和回退方案？
建议先访谈不同规模的业务团队，记录任务完成时间、等待时间、失败率和人工交接次数。优先解决高频、规则明确、风险可控的问题，例如：
- 创建标准 Web 服务；
- 申请测试环境数据库；
- 建立代码仓库和流水线；
- 发布到测试环境；
- 查看服务负责人、文档、SLO 和告警；
- 执行经过审批的回滚；
- 申请短期日志查询权限。
不要把“平台功能数量”当作成功标准。一个能稳定完成五项高频任务的平台，通常比集成几十个入口但体验割裂的平台更有价值。
三、内部开发者平台的核心组成
1. 开发者门户
门户负责提供统一入口，但不应成为新的数据孤岛。它通常展示：
- 服务目录和负责人；
- 项目文档、代码仓库和流水线；
- 环境、版本、依赖和运行状态；
- SLO、告警、值班和事故记录；
- 自助创建、变更、扩容和回滚入口；
- 权限申请和审批状态。
Backstage 是常见的开源开发者门户框架，但采用前必须评估插件维护、身份集成、数据模型和二次开发成本。门户只是界面，真正决定平台价值的是背后的标准接口和工作流。
2. 服务目录
服务目录不是简单的 CMDB 页面。每个服务至少应具备：
- 唯一名称和业务说明；
- 负责人、值班组和升级联系人；
- 代码、制品、文档和运行环境；
- 上下游依赖；
- 数据级别和合规要求；
- SLI/SLO、告警和仪表盘；
- 备份、恢复和停用策略；
- 生命周期状态：试验、生产、维护、下线。
所有权不清的数据很快会失真。服务目录应从代码仓库、部署平台、云资源和监控系统自动同步，并允许服务负责人确认或纠正。
3. 黄金路径
黄金路径（Golden Path）是组织推荐的默认交付方式，例如“创建一个 Java Web 服务”的标准路径可以自动完成：
- 生成符合规范的代码仓库；
- 配置分支保护和代码所有者；
- 创建构建、测试和安全扫描流水线；
- 创建容器镜像仓库和部署清单；
- 申请测试命名空间、资源限额和域名；
- 接入日志、指标、链路和告警；
- 注册服务目录和负责人；
- 生成 Runbook、上线检查表和回滚入口。
黄金路径应该“默认安全、可以扩展”，而不是强迫所有应用使用同一套技术。需要偏离默认方案时，应能记录原因、风险和责任人。
4. 工作流与平台 API
界面点击最终应调用稳定的 API 或自动化工作流，而不是依赖浏览器模拟。工作流需要具备：
- 输入校验和权限检查；
- 幂等性，重复提交不会创建重复资源；
- 计划或预览，执行前展示将要发生的变化；
- 超时、重试和并发控制；
- 失败补偿或回滚；
- 操作日志和关联工单；
- 任务状态查询；
- 紧急停止和人工接管。
四、参考架构
一个中等规模的 IDP 可以分为五层：
- 体验层：开发者门户、CLI、聊天机器人、IDE 插件。
- 编排层：工作流引擎、审批、任务队列、策略校验。
- 能力层：CI/CD、IaC、GitOps、制品库、密钥、监控、成本、CMDB。
- 资源层：云平台、Kubernetes、虚拟机、网络、数据库和中间件。
- 治理层：身份、权限、审计、配额、策略、合规和数据分类。
身份系统应贯穿所有层。平台不要代替用户永久持有高权限凭据，优先使用短期身份、工作负载身份和按任务授权。
五、分阶段建设方法
阶段一：建立服务目录和所有权
先让组织知道“有哪些服务、谁负责、在哪里运行、出问题找谁”。这一阶段不需要复杂自助操作，但要建立数据同步和责任确认机制。
验收标准：生产服务负责人覆盖率达到约定目标；失效链接和无人认领服务有治理流程。
阶段二：交付一个高频黄金路径
选择边界清楚的应用类型，完成从创建到测试环境上线。不要第一期同时支持所有语言、数据库和云平台。
验收标准：新项目准备时间明显下降；模板生成后可以通过流水线和安全检查；失败后可清理残留资源。
阶段三：接入生产保护
增加审批、策略、配额、SLO、备份、成本和回滚。高风险变更需要双人复核或变更窗口。
验收标准：所有生产变更可追溯；平台自动创建的服务具备基础观测、告警和恢复说明。
阶段四：以产品方式运营
平台团队需要产品负责人、路线图、用户支持和版本管理。通过用户访谈和数据决定后续能力，而不是只按平台团队偏好开发。
六、安全与治理边界
- 默认最小权限，禁止门户后端共享一个永久管理员账号；
- 密钥只保存在专用 Secret/KMS 中，日志和任务输出必须脱敏；
- 高风险操作应显示目标环境、影响范围、停止条件和回退步骤；
- 模板、镜像和依赖应锁定版本并经过供应链检查；
- 平台操作需要关联用户身份、审批记录和执行结果；
- 平台自身也要有 SLO、备份、容灾和应急访问方案；
- 自助不等于免审批，审批也不应沦为不看内容的一键通过。
七、如何衡量平台是否有效
建议同时观察交付、可靠性和体验：
| 维度 | 示例指标 |
|---|---|
| 交付效率 | 新服务创建耗时、环境等待时间、部署频率、变更前置时间 |
| 交付质量 | 变更失败率、自动回滚率、模板缺陷率 |
| 平台采用 | 黄金路径使用率、自助完成率、绕过平台比例 |
| 运行质量 | 默认监控覆盖率、服务所有权覆盖率、SLO覆盖率 |
| 用户体验 | 任务成功率、文档查找时间、满意度、支持请求数量 |
| 成本治理 | 闲置资源发现率、标签完整率、单位服务成本 |
不要只统计登录人数和按钮点击量。真正的结果是用户能否更快、更安全地完成工作。
八、常见失败方式
- 先买工具再找问题：导致平台功能很多，却没有稳定用户。
- 把所有系统嵌入一个门户：入口统一了，流程仍然割裂。
- 强制所有团队使用唯一模板：忽略业务差异，用户转而绕过平台。
- 没有服务所有者：目录数据无人维护，几个月后失去可信度。
- 只做创建、不做回收：快速产生大量无人使用的资源。
- 平台团队替所有人操作：平台变成新的工单中心，没有实现自助。
- 没有版本与兼容策略：模板升级破坏旧项目，用户不敢更新。
九、最小落地清单
- [ ] 明确首批用户和三个高频任务；
- [ ] 建立服务唯一标识和所有权字段；
- [ ] 选择一个应用类型制作黄金路径；
- [ ] 所有自动化支持预览、审计和失败处理；
- [ ] 接入身份、最小权限和密钥管理；
- [ ] 自动加入基础日志、指标、告警和 Runbook；
- [ ] 定义平台自身 SLO 和支持渠道；
- [ ] 记录交付时间、成功率和用户反馈；
- [ ] 每季度清理不再使用的模板、插件和资源。
十、示例：把“创建测试服务”做成黄金路径
假设团队每月新增多个 Java 服务，过去需要研发分别联系代码仓库、Kubernetes、数据库和监控管理员。平台可以把流程拆成以下步骤：
- 用户填写服务名称、业务、负责人、数据级别和预计流量；
- 平台校验命名、负责人和成本中心，展示将创建的资源；
- 生成带健康检查、结构化日志、单元测试和依赖锁文件的仓库；
- 创建最小权限流水线，构建镜像并生成SBOM；
- 通过IaC申请测试命名空间、配额和数据库账号；
- 通过GitOps提交部署清单，初始只发布到测试环境；
- 自动注册服务目录、仪表盘、基础告警和Runbook；
- 返回任务结果、失败步骤和清理入口。
验收时不能只看资源是否创建，还要让一名未参与开发的用户独立完成流程，并测试重复提交、权限不足、数据库申请失败、GitOps同步失败和整体清理。平台应保留每个子任务的状态，允许从安全步骤重试，不能让用户在多个系统中手工清理半成品。
第一期可以不支持生产环境和所有语言。等测试服务路径稳定后，再增加生产审批、成本预算、SLO、备份等级和渐进发布。这样能够用真实使用反馈推动平台演进，而不是在没有用户前建设大量假设功能。
十一、参考资料
平台工程最终交付的不是一个门户，而是一套被团队愿意使用、默认安全、持续改进的工作方式。先把一条常用路径做好，再逐步扩展，比一次性建设“大而全平台”更容易成功。