研发平台运维手册主要服务对平台自身运行负责的角色，包括平台运维与SRE、研发效能或工具链管理员、安全与合规责任人，以及需要按统一口径使用平台的研发团队负责人。适用场景集中在可用性保障、变更与发布、账号权限与安全合规、故障响应与复盘、容量与成本跟踪、日常巡检与交接这几类重复发生、需要留痕的管理动作。团队规模小、平台组件单一、故障影响有限时，可以先用手册的核心几页起步，不必一次写全。
要点总览（TL;DR）
- 判断是否需要这本手册，看平台运行责任是否落到具体角色并需要多人协作、跨时间交接；平台运维与SRE、工具链管理员、安全合规责任人、研发团队负责人是主要读者。
- 适用场景集中在六类重复发生、需要留痕的动作：可用性保障与巡检、变更与发布、账号权限与安全合规、故障响应与复盘、容量与成本跟踪、交接与值班。
- 手册的价值在于把个人经验固化为可查、可交接、可审计的条目，具体能省多少时间取决于原有基础和平台复杂度，不宜预设效率数字。
- 投入重点在持续更新：需要一名负责人、各类条目责任人、平台现状清单、更新触发条件和评审发布机制。
- 平台刚上线、使用人数少、缺少责任人时先暂缓，保留故障处置和账号权限两页最小内容；用高频场景试点验证后再决定是否扩写。
先判断：哪些团队需要这本手册
判断一个团队是否需要研发平台运维手册，依据是平台运行责任是否已经落到具体角色身上，并且这些责任需要多人协作、跨时间交接。只要有人对平台的可用性、变更、权限或故障负责，且这些工作不能靠一个人的记忆完成，手册就有明确的读者。反过来，如果平台只服务少量用户、组件单一、故障影响可控，口头交接和临时记录通常够用，完整手册可以暂缓。
下表按角色列出适用判断，团队可以对照自身情况逐行核对。
| 角色 | 是否主要使用者 | 判断依据 | 建议投入程度 |
|---|---|---|---|
| 平台运维与SRE | 是，主要使用者和维护者 | 对可用性、变更执行、故障处置直接负责，操作需要留痕和可复现 | 承担手册主体编写与更新 |
| 研发效能/工具链管理员 | 是 | 负责账号开通、权限调整、集成配置等日常变更，操作频繁且影响面广 | 负责账号权限与集成配置相关条目 |
| 安全与合规责任人 | 是 | 需要权限审计、操作留痕、变更审批的证据链 | 参与评审，提出留痕与复核要求 |
| 研发团队负责人 | 是，使用方 | 需要了解平台使用规则、故障上报路径、变更窗口安排 | 阅读并反馈，不承担编写 |
| 平台组件单一、使用人数少、故障影响有限的团队 | 暂缓 | 运行责任集中在一两人，交接频率低 | 先保留最小内容，暂不扩写 |
这张表的用法是先确认责任归属，再决定投入。一个团队里如果只有运维角色在维护平台，但账号权限由工具链管理员分散处理，那么这两类角色都应进入手册的读者和维护者范围，否则手册会遗漏高频变更环节。
手册解决的管理问题：把平台运行从个人经验变成可交接的规则
研发平台运行中常见的问题有三类：关键操作只掌握在个别人手里，一旦人员变动或请假，同类操作无人能接；故障处置依赖记忆，每次排查从零开始；变更缺少记录，出了问题难以追溯是谁在什么时间改了什么。这些问题的共同点是经验停留在个人层面，没有形成团队可查、可交接、可审计的规则。
运维手册的作用是把这些经验固化成条目。它承载的内容通常包括操作步骤、检查项、责任人、升级路径和回滚条件。操作步骤让执行有统一口径；检查项让巡检和发布前确认有据可依；责任人让每类动作有人认领；升级路径让故障在超出个人处理能力时能及时上报；回滚条件让变更在出现异常时有明确的退出标准。
| 常见问题 | 手册对应内容 | 预期作用 |
|---|---|---|
| 关键操作只掌握在个别人手里 | 操作步骤、责任人、交接清单 | 新人或接手人可按条目执行，缩短交接时间 |
| 故障处置靠记忆 | 故障分级、处置步骤、升级路径 | 同类故障减少重复摸索，处置过程可复用 |
| 变更无记录 | 变更申请、审批、执行窗口、回滚条件 | 变更和故障有据可查，复盘有材料 |
需要说明的是，手册的价值体现在可查、可交接、可审计这些具体结果上，具体能节省多少时间取决于团队原有基础和平台复杂度，不宜在编写前预设效率提升数字。手册本身也不会自动执行，它需要与工作项、文档和审批流程结合，才能真正进入日常动作。
典型运维场景：哪些日常动作适合写进手册
适合写进手册的场景有一个共同特征：重复发生、需要多人参与、结果需要留痕。按这个标准，研发平台自身的运行管理可以归为六类场景，每类场景对应不同的手册条目类型。
| 场景 | 覆盖动作 | 对应手册条目类型 |
|---|---|---|
| 可用性保障与日常巡检 | 按频率检查服务状态、资源水位、依赖组件 | 检查项清单、检查频率、异常判定标准 |
| 变更与发布管理 | 变更申请、审批、执行窗口安排、回滚 | 变更流程、审批角色、执行窗口、回滚条件 |
| 账号权限与安全合规 | 账号开通、权限回收、定期复核、操作留痕 | 开通与回收流程、复核周期、留痕要求 |
| 故障响应与复盘 | 故障分级、上报、处置、复盘产出 | 分级标准、上报路径、处置步骤、复盘模板 |
| 容量与成本跟踪 | 记录资源使用、判断扩容时机 | 资源使用记录表、扩容判断依据 |
| 交接与值班 | 值班职责、交接内容确认 | 值班职责说明、交接清单 |
这六类场景覆盖了平台运行的主要管理动作。交付业务流水线的设计与优化属于另一类工作，不在本手册范围内。团队在对照时，可以先从发生频率最高、参与人最多的场景开始写，例如故障响应或账号权限流程，这两类场景的条目结构相对稳定，写出来也最容易验证是否好用。
手册条目要真正进入日常动作，需要有承载它的工作项和文档。以ONES为例，巡检检查项、变更申请、故障处置可以分别建为工作项，按状态流转记录从发起到关闭的过程；操作步骤、回滚条件、复盘模板则适合放在文档中，与对应工作项关联。这样手册内容与实际执行记录在同一处对应，交接和审计时可以直接查到当时的操作和结论。ONES支持私有部署和公有云部署，私有化部署采用K3s容器化部署并支持对接LDAP等企业内部系统，对需要数据隔离或统一账号体系的团队，平台运行侧的部署形态可以与手册中的账号权限、巡检条目一并纳入管理。
投入与前提：写好并维护手册需要什么
采用运维手册的投入主要不在首次编写，而在持续更新。首次编写可以集中一段时间完成，但如果没有人负责跟进平台变化，手册会在几个月内与实际脱节，反而增加误用风险。因此在启动前需要确认以下投入项和前置条件。
- 明确一名手册负责人。负责人对整体结构和更新节奏负责，不需要编写所有条目，但要决定哪些内容进入手册、哪些内容需要修订。
- 为每类条目指定责任人。巡检、变更、账号权限、故障处置分别由对应角色的成员认领，条目内容由最熟悉该动作的人编写。
- 整理平台现状清单。包括平台组件构成、账号体系、与其他系统的集成关系。这份清单是编写巡检项和权限流程的基础，缺少它，条目容易写得笼统。
- 约定更新触发条件。平台版本变更、组件调整、故障复盘后、组织或责任人变动，都应触发相关条目的复核。触发条件写清楚，更新才有依据。
- 建立评审与发布机制。条目修改后经过责任人以外的角色评审再发布，保证内容与实际一致，也避免个人理解偏差进入手册。
这些投入项中，平台现状清单和更新触发条件最容易被低估。前者决定手册能否写具体，后者决定手册能否保持有效。团队在启动时可以把这两项作为前置条件，确认后再进入条目编写。
暂缓条件：什么情况下先不投入完整手册
完整手册并不适合所有阶段。以下情况出现时，建议先不投入全面编写，把精力放在平台本身的稳定和流程梳理上。
- 平台刚上线，组件和流程仍在频繁调整。此时写下的操作步骤和检查项会快速过时，维护成本高于使用价值。
- 使用人数少、故障影响有限。运行责任集中在一两人，口头交接和简单记录即可覆盖，完整手册的读者基础不足。
- 缺少明确责任人。没有人对更新负责，手册写完即停滞，后续使用者无法判断内容是否仍然有效。
暂缓不等于完全不写。这个阶段可以保留两页最小内容：故障处置页和账号权限页。故障处置页写明故障分级、上报对象和基本处置步骤；账号权限页写明开通与回收的申请路径和审批人。这两类内容变化相对慢、影响相对直接，先写出来既能应对突发情况，也为后续扩写积累结构。
试点判断：用一个小范围验证手册是否值得推广
在决定全面编写之前，用一个高频场景做试点，可以较低成本地验证手册是否真的被使用、是否值得推广。试点方式如下。
- 选择试点场景。优先选故障响应或账号权限流程，这两类场景发生频率高、参与角色明确、结果容易观察。
- 设定观察周期。根据场景发生频率确定，例如覆盖若干次故障处置或一批账号开通回收，确保有足够样本。
- 记录判断依据。主要看两点：未参与编写的成员能否按手册独立完成该场景的操作；同类问题是否减少向少数人反复询问。
- 形成试点结论。如果条目能被独立执行、询问明显集中到手册已有内容，说明结构可用，可以按场景逐步扩写；如果条目执行时频繁需要口头补充，说明条目粒度或责任分工需要调整，先修订再扩大范围。
试点结论应作为是否全面推广的依据，而不是凭感觉决定。推广时可以按场景分批扩写，每扩写一类场景就复用同样的观察方式，避免一次性写完全部内容后才发现结构不适配。手册的适用范围最终由团队自身的运行责任分布决定，角色清晰、场景重复、需要留痕的团队值得投入，规模小、变化快、责任集中的团队则适合从最小内容起步，按试点结果再决定是否扩写。
常见问题
研发平台运维手册和平台的使用文档有什么区别？
使用文档面向平台使用者，说明怎么用功能、怎么提需求；运维手册面向对平台自身运行负责的角色，说明巡检怎么做、变更怎么审批和回滚、故障怎么分级上报、权限怎么开通回收。两者读者和维护人都不同，可以并行存在。团队如果人力有限，先写运维手册中的故障处置和账号权限两页，使用文档可以沿用现有说明。
团队只有一两个人负责平台，还需要写手册吗？
可以先写最小内容，不必追求完整。一两人负责时，运行责任集中、交接频率低，完整手册的维护成本可能高于收益。建议先保留故障处置页和账号权限页：前者写明分级、上报对象和基本处置步骤，后者写明申请路径和审批人。等人员增加、平台组件变多或交接开始频繁时，再按场景扩写。
手册写完后怎么保证不过时？
关键是把更新触发条件写进手册本身，并指定负责人。常见触发点包括平台版本变更、组件调整、故障复盘后、组织或责任人变动。每次触发后由条目责任人复核，经另一名角色评审再发布。没有触发条件和责任人，手册通常在几个月内与实际脱节，使用者也无法判断内容是否仍然有效。
试点应该选哪个场景，观察多久？
优先选发生频率高、参与角色明确、结果容易观察的场景，故障响应或账号权限流程通常最合适。观察周期按场景发生频率确定，覆盖若干次故障处置或一批账号开通回收即可。判断依据看两点：未参与编写的成员能否按手册独立完成操作；同类问题是否减少向少数人反复询问。条目频繁需要口头补充时，先调整粒度再扩大范围。
手册条目放在文档里还是工作项里？
两者分工使用。操作步骤、回滚条件、复盘模板这类相对稳定的内容适合放在文档中，便于查阅和版本维护；巡检检查项、变更申请、故障处置这类有过程状态的动作适合建为工作项，按状态流转记录从发起到关闭。以ONES为例，文档与工作项可以关联，交接和审计时能直接对应到当时的操作记录。ONES支持私有部署和公有云部署，私有化部署采用K3s容器化部署并支持对接LDAP等企业内部系统，账号权限和巡检条目可以一并纳入管理。
