研发平台运维手册要围绕平台自身的稳定运行来写：先界定平台边界与责任分工，再按日常巡检、变更发布、故障处置、备份恢复、账号权限、容量与版本六类场景，逐项写清触发条件、操作步骤、输入输出、负责人和完成标志，最后补齐值班表、联系链、记录模板与评审机制。手册覆盖管理平台自身的运行维护，业务流水线的交付流程另行归属。
要点总览（TL;DR）
- 手册边界以平台组件清单为准：应用服务、数据库、中间件、网关、存储、监控与日志纳入，业务流水线设计与发布策略编排另行归属。
- 主体按日常巡检、变更发布、故障处置、备份恢复、账号权限、容量与版本六类场景搭骨架，每章统一写触发条件、操作步骤、输入、输出、负责人、完成标志。
- 单条操作补齐前置输入、执行动作、产出结果、完成判定四要素，命令与界面操作分开写，敏感信息用占位符，异常分支单独交代。
- 编写由平台运维负责人牵头、组件负责人分章供稿，技术负责人与安全审计角色评审，值班人员执行并记录偏离，手册Owner负责持续维护。
- 交付前按范围、可执行、责任、演练、维护五类检查逐项核对，全部通过再标记生效；生效后把平台变更单与章节更新任务关联，保持文档与环境同步。
先划清手册边界：写平台自身运行，不写业务流水线
编写手册的第一步是确定覆盖对象。研发平台通常由多个组件构成，运维手册只写这些组件自身的运行维护，不写基于平台开展的研发交付活动。范围界定不清，手册会越写越散，最后变成一本什么都有、什么都用不上的资料汇编。
建议以组件清单作为界定工具，逐项列出平台包含的应用服务、数据库、中间件、网关、存储、监控与日志系统。清单中的每一项都对应手册中的巡检、变更、故障、备份条目；清单之外的组件不进入本手册。清单同时标注每个组件的负责人，为后续分章供稿做准备。
排除项要写进手册前言，让读者一眼知道边界在哪里。常见的排除内容包括：业务流水线的设计与编排、发布策略与灰度规则制定、通用操作系统与网络运维教程。这些内容各有归属文档，写进运维手册会造成职责混淆。排除项不是永久禁止，而是说明本手册不承担这部分内容的维护责任。
读者角色同样需要在开篇列明。平台运维人员关注操作细节与故障处置；值班人员关注巡检项与升级路径；研发自助操作者关注账号申请、权限变更等自助流程；审批与审计角色关注变更记录、权限回收与留痕要求。角色不同，阅读路径不同，手册目录可以按角色给出推荐阅读章节。
最后确定版本信息：手册版本号、生效日期、评审周期。版本号建议与平台重大变更节奏挂钩，评审周期按季度或半年设定，并在手册首页固定展示。这一页内容可以整理成《手册范围与读者说明》，作为整本手册的第一章。
手册主体结构：六类运维场景的章节骨架
范围确定后，按六类场景搭建章节骨架。每章统一使用六个字段：触发条件、操作步骤、输入、输出、负责人、完成标志。字段统一的好处是编写时有模板可循，执行时能逐项核对，评审时也容易发现缺项。
| 场景章节 | 核心内容 | 关键字段示例 |
|---|---|---|
| 日常巡检 | 巡检项、频率、判定阈值、异常上报路径 | 触发条件：每日 9:00 定时巡检；完成标志：巡检记录填写完毕且异常项已上报 |
| 变更与发布 | 变更申请、评审、窗口期、回滚条件 | 触发条件：平台组件版本更新或配置调整；完成标志：变更记录归档、回滚预案确认 |
| 故障处置 | 分级标准、响应时限、升级路径、复盘要求 | 触发条件：监控告警或用户报告；完成标志：故障关闭并完成复盘记录 |
| 备份与恢复 | 备份对象、周期、保留策略、恢复演练频率 | 触发条件：按备份周期执行；完成标志：备份成功校验、演练记录归档 |
| 账号与权限 | 开通、变更、回收流程与审批人 | 触发条件：入职、转岗、离职或权限申请；完成标志：审批完成、操作留痕 |
| 容量与版本 | 容量水位监控、版本升级与兼容性确认 | 触发条件：水位超过阈值或新版本发布；完成标志：扩容完成或升级验证通过 |
每章开头写一段场景说明，交代这类运维活动解决什么问题、由谁主导。章节内部按字段顺序展开，字段缺失的条目视为未完成。六类场景之外的内容，例如安全事件响应、供应商管理，如果平台运行确实涉及，可以作为附录补充，不强行塞进六章骨架。
目录草案完成后，先交给各组件负责人确认覆盖是否完整，再进入条目编写。目录阶段的返工成本最低，等到条目写完再调整结构，工作量会成倍增加。
每个操作步骤怎么写：输入、动作、输出与完成标志
手册最常见的质量问题是写成口号，例如“加强监控、及时处理异常”。这类句子无法指导操作，也无法判断是否完成。改写的方法是给每条操作补齐四要素：前置输入、执行动作、产出结果、完成判定。
- 前置输入：执行这条操作前需要具备什么，例如登录权限、待检查的组件地址、上一次的巡检记录。
- 执行动作：具体做什么，命令与界面操作分开描述。命令写完整可复制，界面操作写清菜单路径与关键字段。
- 产出结果：操作完成后留下什么，例如巡检记录、变更单、告警截图、恢复验证结果。
- 完成判定：用什么标准判断这条操作已经完成，例如“所有巡检项状态为正常”或“回滚后核心接口响应恢复正常”。
敏感信息处理要单独约定。手册中出现的密码、密钥、令牌一律使用占位符，例如 <数据库管理员密码>，真实值存放在密码管理工具中，手册只写获取途径。命令示例中的内网地址、账号同样做脱敏处理。
异常分支与正常路径同等重要。每条操作后面补充失败现象、判断依据、替代动作、上报对象。只写顺利情况的手册，在真正出问题时往往用不上。
以下是一条巡检条目的示范写法：
巡检项：应用服务健康检查。前置输入：平台运维账号、应用服务健康检查地址。执行动作：访问健康检查接口，记录返回状态码与响应时间；在监控面板核对近一小时错误率曲线。产出结果：巡检记录中填写状态码、响应时间、错误率三项数据。完成判定：状态码正常且错误率低于设定阈值记为通过；任一项异常，按上报路径提交工单并注明异常现象。负责人：当班值班人员。
以下是一条故障处置条目的示范写法：
故障场景：数据库连接数耗尽。前置输入：数据库监控告警、当前连接数查询权限。执行动作：查询当前活跃连接与来源，确认是否存在异常连接堆积；按预案终止异常会话或临时调高连接上限；观察业务恢复情况。产出结果：故障工单中记录连接数变化、处理动作与恢复时间。完成判定：连接数回落至阈值以下且业务接口恢复正常，工单关闭并进入复盘。异常分支：调整后连接数仍持续上涨，立即升级至数据库负责人，同时评估是否切换备用节点。负责人：当班值班人员，升级对象为数据库负责人。
角色与交付物：谁写、谁审、谁执行、谁签字
手册无人维护，通常是因为编写时没有指定责任人。建议在编写启动阶段就确定四类责任，并用职责矩阵固定下来。
| 角色 | 职责 | 交付物 |
|---|---|---|
| 平台运维负责人 | 牵头编写，统筹目录与进度，担任手册 Owner | 手册目录、编写计划、最终版本 |
| 各组件负责人 | 按分章供稿，提供巡检项、操作步骤与阈值 | 所负责章节的条目初稿 |
| 技术负责人 | 评审操作步骤的技术准确性 | 评审意见与确认记录 |
| 安全与审计角色 | 确认账号权限、审批留痕与合规条目 | 权限与合规条目确认意见 |
| 值班人员 | 按手册执行日常操作，偏离时记录原因 | 巡检记录、故障工单、偏离说明 |
执行责任需要特别说明偏离处理。值班人员遇到手册未覆盖的情况，可以按经验处置，但必须在工单中记录偏离原因与处置过程，事后反馈给手册 Owner 判断是否需要补充条目。偏离记录是手册迭代的重要输入。
维护责任落在手册 Owner 身上。需要明确哪些事件触发手册更新：平台组件增减、重大版本升级、故障复盘产生新处置要求、评审发现条目失效。触发条件写进手册维护章节，避免更新依赖个人记忆。
配套附件：值班表、联系链、记录模板与演练计划
正文之外，四类附件决定手册能否在日常运转中用起来。附件与正文分开维护，更新频率不同，但都要在手册中给出获取位置。
值班表写明班次划分、每班覆盖时段、交接内容与交接确认方式。交接内容至少包括未关闭的故障工单、待执行的变更、巡检异常项。交接确认建议采用书面或系统内确认，避免口头交接遗漏。
联系链分内部与外部两条线。内部线写升级路径：一线值班、二线组件负责人、三线技术负责人，每级写清响应时限与联系方式。外部线写厂商支持入口、服务级别约定与升级联系人。联系链随人员变动更新，更新责任归手册 Owner。
记录模板至少四类：巡检记录、变更记录、故障工单、恢复演练记录。模板字段与正文条目的四要素对应，保证记录能回溯到具体手册条目。模板可以放在文档系统中作为固定表单，减少每次手工整理。
演练计划写明恢复演练与故障演练的频率、参与角色、验收口径。恢复演练验证备份可用性，故障演练验证处置流程与升级路径。验收口径要可判断，例如“备份数据恢复后核心数据校验一致”“故障演练从告警到升级完成在约定时限内”。演练结果回写手册，发现的问题转化为条目修订任务。
完成检查：手册交付前的核对清单
手册写完不等于可用。交付前按五类检查逐项核对，全部通过再标记生效。
- 范围检查：覆盖组件清单是否完整，排除项是否写明，读者角色是否列全。
- 可执行检查：每条操作是否具备输入、动作、输出、完成标志；命令与界面操作是否分开；敏感信息是否使用占位符；异常分支是否覆盖。
- 责任检查：每个场景是否都有明确负责人与升级对象；偏离处理是否有记录要求。
- 演练检查：恢复演练与故障演练是否已排期，验收口径是否可判断。
- 维护检查：版本号、生效日期、评审周期是否落实；更新触发条件是否写明；手册 Owner 是否指定。
核对清单建议做成可勾选表格，每项标注核对人与核对日期。存在未通过项时，手册状态保持“评审中”，不进入生效状态。清单本身也作为手册附件保留，下一轮评审时对照检查是否有回退。
手册落地后的维护：把文档接入日常协作流程
手册生效后进入持续维护阶段。维护的核心是让平台变更与文档更新保持同步，避免手册描述与实际环境脱节。
具体做法是把平台变更单与手册章节更新任务关联起来。变更申请时勾选受影响的手册章节，变更完成后自动生成或手动创建章节更新任务，由对应组件负责人修订条目，手册 Owner 审核后发布新版本。变更单与手册版本之间保留关联关系，事后可以追溯某次变更对应哪一版手册。
文档状态建议按草稿、评审中、已生效、待修订四个状态流转。草稿供编写使用，评审中供技术负责人与安全审计角色确认，已生效为值班执行依据，待修订表示平台已变化但条目尚未更新。状态流转配合定期评审，每轮评审记录参与人、评审结论与遗留问题，历史版本保留可查。
巡检记录与故障工单应能回溯到对应手册条目。工单中引用条目编号，复盘时可以直接定位到需要修订的章节。这样手册的每次更新都有实际运行记录作为依据，而不是凭印象修改。
在文档承载上，ONES Wiki 可用于集中管理操作说明、项目规范与复盘记录等需要长期沉淀的内容，并可与项目、任务等研发管理场景结合，使文档和平台变更工作保持关联。将手册章节、变更任务与评审记录放在同一协作环境中，有助于落实上述状态流转与版本追溯的管理动作。手册的具体巡检项、备份策略与恢复操作，仍需结合企业实际部署环境编写。
常见问题
平台组件清单还没整理完，手册可以先动笔吗？
可以先写不依赖清单的部分，例如手册前言、读者角色说明、版本与评审周期，以及六类场景的章节骨架和字段模板。巡检项、备份对象、容量阈值这些条目依赖组件清单，建议等清单确认后再逐项填写。
如果平台组件较多、清单整理周期较长，也可以按组件分批推进：先覆盖核心应用服务与数据库，再补中间件、网关、存储、监控与日志。分批编写时在手册中标注各章节的覆盖状态，避免读者误以为已全部完成。
值班人员遇到手册没写到的情况，怎么处理才不破坏手册的权威性？
允许按经验先行处置，前提是把偏离记录下来。工单中写清遇到的现象、手册对应条目、实际采取的动作和结果，处置结束后反馈给手册Owner。
手册Owner判断是否需要补充或修订条目，修订后进入评审与生效流程。这样处理既保证故障不被延误，也让手册通过实际运行逐步完善。偏离记录本身可以作为下一轮评审的输入材料。
恢复演练多久做一次，验收标准怎么写才可判断？
演练频率结合备份周期和业务对恢复时间的要求确定，在演练计划中写明并保持稳定执行。验收标准要落到可核对的结果上，例如备份数据恢复后核心数据校验一致、恢复耗时在约定范围内、参与角色按联系链完成升级。
演练结束后把发现的问题转化为条目修订任务，回写到备份恢复章节。只排期不验收，演练容易流于形式。
手册用文档工具承载时，怎么保证变更后条目及时更新？
关键是把变更与文档更新做成同一条流程：变更申请时标注受影响的手册章节，变更完成后生成章节更新任务，由组件负责人修订、手册Owner审核后发布新版本。变更单与手册版本保留关联，事后可以追溯某次变更对应哪一版手册。
文档状态按草稿、评审中、已生效、待修订流转，配合定期评审记录参与人与结论。ONES Wiki 可用于集中管理操作说明、项目规范与复盘记录等需要长期沉淀的内容，并可与项目、任务等研发管理场景结合，使文档和平台变更工作保持关联。具体巡检项、备份策略与恢复操作仍需结合企业实际部署环境编写。
手册评审通过后，平台发生小范围配置调整，需要整本重新评审吗？
按影响范围决定。只涉及个别章节的配置调整，由对应组件负责人修订条目，手册Owner审核后更新版本号并记录变更说明即可；涉及权限模型、备份策略、升级路径等跨章节内容的调整，建议组织技术负责人与安全审计角色复核相关章节。
无论哪种情况，评审周期内的定期评审照常执行，核对清单也对照检查一遍，确认没有条目因这次调整而失效。
