手册写得很全，八十页，目录清晰。凌晨两点告警响了，值班的人打开搜索框敲关键词，翻了十分钟没找到对应现象，于是回到命令行凭记忆操作。
手册的失效从来不是"没写"，是在故障那一刻不可用：找不到、看不懂、不敢执行、或者执行了不知道对不对。可操作性不是文档质量属性，是故障时刻的行为属性。
1. 手册要回答四个问题
| 问题 | 对应内容 | 缺失的后果 |
|---|---|---|
| 怎么知道坏了 | 告警项与判据、观察窗口 | 靠人报障，发现延迟到分钟级 |
| 怎么确认哪坏了 | 分层检查步骤与判据 | 四处乱试，止血时间不可控 |
| 怎么止血 | 分级处置动作与预期效果 | 只有重启一条路 |
| 谁有权决定 | 停服/回滚/降级的授权 | 决策卡在等领导回复 |
最难写的是第四问：技术上能止血但没人敢签字，等于没有止血方案。判据：值班的人能否不打电话完成前三问，并知道第四问找谁。
2. 三种形态与适用场景
| 形态 | 结构 | 最适合 | 不适合 |
|---|---|---|---|
| 巡检清单 | 有序检查项 + 正常值 | 例行体检、发布后观察 | 复杂故障的分支判断 |
| 故障剧本 | 现象 → 处置步骤 → 验证 | 已知故障、处置固定 | 未见过的新问题 |
| 决策树 | 判据分支 → 动作 | 需要按现象分流 | 时间极紧的抢修 |
三种不是替代关系而是分工：清单管"早发现"，决策树管"分诊"，剧本管"处置"。最常见错误是只有剧本没有分诊——拿到了"连接池耗尽怎么处理"，却不知道当前故障是不是这一种。
3. "凌晨三点可执行"的判据
| 判据 | 检查方式 | 反例 |
|---|---|---|
| 无需上下文 | 只读这一节能否执行 | "参考上次的处理" |
| 无需找人 | 不依赖口头确认 | "问一下谁改过配置" |
| 每步可验证 | 每步都有成功判据 | "观察一段时间" |
| 无隐含前提 | 前置条件写在最前 | 假设已装好某个工具 |
| 单步可中断 | 中途停下不留下半成品 | 连续五条必须一次跑完 |
// 单条处置步骤的合格结构（缺任一项不合格）
前提：需要什么权限、在哪个节点执行
命令：可复制的完整命令，占位符用大写
预期：正常输出的关键片段（不是"无输出即正常"）
异常：不匹配时跳转到哪一节
回滚：这条命令怎么撤销，影响哪些数据
最后一项缺失最危险：用一条不知道后果的命令救火，救完留下更大的问题。
4. 命令要带预期输出
"执行后无异常即正常"是错误期望。值班的人需要的是可对照的片段，否则只能靠猜。
// 服务可用：预期 200
curl -s -o /dev/null -w "%{http_code}\n" http://TARGET:8080/healthz
// 连接池：预期 active 远小于 max，wait 为 0
curl -s http://TARGET:8080/actuator/metrics/hikaricp.connections.active
// 磁盘：预期使用率低于 85%
df -h / | tail -1
| 期望写法 | 问题 |
|---|---|
| "无输出即正常" | 命令写错也无输出 |
| "应为 200" | 没说在哪查、看哪个字段 |
| "看日志确认" | 没给行号或关键字 |
| "正常/异常" | 没给阈值，判断靠经验 |
把预期写成可比对的形式，等于把手册从"经验分享"变成"操作规范"。
5. 危险操作：回滚与影响范围
| 操作类型 | 影响范围 | 必须附带 |
|---|---|---|
| 重启进程 | 在途请求失败 | 当前流量量与重试行为说明 |
| 摘除节点 | 容量下降 | 剩余容量是否够撑过维护窗口 |
| 切主库 | 写入短暂失败 | 切换判据、切回条件与耗时 |
| 回滚版本 | 已产生的数据是否兼容 | 数据结构兼容矩阵 |
| 清缓存 | 后端瞬时压力 | 预热方式与限速参数 |
// 危险操作的记录模板
操作：切主库
影响：写入中断典型量级 5–30 秒；只读请求不受影响
前提：从库延迟 < 阈值；已通知业务方
回滚：切回原主库，耗时同量级；切换期间写入需人工核对
禁止：在批量任务运行窗口内执行
写"禁止条件"常比写"操作步骤"更有价值：事故多发生在错误的时间窗口，而不是错误的命令上。
6. 手册的两处腐化
| 腐化类型 | 表现 | 检测方式 |
|---|---|---|
| 命令过期 | 参数已废弃、接口已改 | 定期按手册实跑一遍 |
| 路径变更 | 目录、服务名、端口变了 | 演练时对照真实环境 |
| 判据失效 | 阈值不再适用 | 与现有告警项比对 |
| 责任人变更 | 授权人已离职 | 每季度核对联系人 |
// 腐化检测的最小动作：把手册跑一遍
// 1) 提取所有可执行命令，逐条在预发执行
// 2) 记录返回码与关键输出，与预期值比对
// 3) 不一致的条目要么改手册，要么改环境
// 4) 每季度一轮，结果计入过期数指标
演练的价值不在"跑通"，而在暴露手册与环境的分歧：跑通只说明这一次对，跑不出来的地方才是知识缺口。
7. 手册与自动化：先后与互相生成
| 顺序 | 做法 | 风险 |
|---|---|---|
| 先手册后脚本 | 处置逻辑先写清，再固化为脚本 | 前期慢半拍 |
| 先脚本后手册 | 有工具但没人知道何时用 | 工具成为黑盒，故障时不敢用 |
| 靠脚本自动生成手册 | 参数与步骤天然同步 | 只能覆盖已自动化的部分 |
| 手册与脚本双维护 | 无 | 两份都过期，且互相矛盾 |
判据：能被自动化的部分先写成人能执行的步骤，再固化。跳过这一步的自动化，故障时会因为"不知道它在干什么"而不敢点。反向生成是最省力的维护方式：脚本的用法与失败判据直接渲染进手册片段，参数变更时同步更新，人只维护未自动化的部分。
// 手册片段自动生成的边界
自动生成：命令、参数、阈值、联系人与有效期
手工维护：判据的业务含义、禁用条件、跨系统影响
机器知道"怎么执行"，不知道"什么情况下不该执行"
8. 可操作性的三个层级
| 层级 | 能力 | 前提 | 典型缺口 |
|---|---|---|---|
| 能看 | 知道指标在哪、怎么看 | 监控与看板可用 | 无 |
| 能判断 | 能根据现象定位层次 | 分层检查顺序清楚 | 判据阈值 |
| 能处置 | 能执行止血并验证 | 处置步骤 + 授权 | 授权与回滚 |
大部分团队自评"能判断"，实际停在"能看"：能打开监控看到曲线升高，但不知道先查哪一层。
判断真实层级的方法不是问，是看最近三次故障的记录：止血是"查文档后执行"还是"先试几个操作"。动作序列最有说服力。
9. 新人上手检验
// 检验设计：让没做过的人按手册执行一次
1) 选一个低风险场景（预发环境、模拟故障、只读检查）
2) 执行者只允许看手册，不允许提问
3) 记录三类卡点：找不到、看不懂、不敢做
4) 按卡点改手册，不改执行者
5) 换另一个没做过的人重跑，直到卡点为零
检验的产出是手册的修订清单，不是"新人能力评估"。需要口头解释才能完成的步骤，都算手册缺陷。
模拟故障要挑真实的：依赖超时、磁盘写满、连接池耗尽这类平时真的会发生的，比人造异常更能暴露手册缺口。
10. 故障期的信息架构
| 阶段 | 先做什么 | 什么时候叫人 |
|---|---|---|
| 发现 | 确认影响面与是否在扩散 | 影响面持续扩大时 |
| 止血 | 执行分级处置，恢复可用 | 首选处置无效时 |
| 定位 | 保留现场，收集证据 | 需要跨系统协同时 |
| 复盘 | 还原时间线，写入手册 | 不适用 |
故障期的信息架构只有一条原则：先恢复服务，再解释原因。顺序颠倒会把短暂故障拖成长故障。
叫人时机要写进手册，并给判据：例如"首选处置 10 分钟内无效，或影响面仍在扩大"。没有判据的"视情况升级"，结果通常是叫得太晚。
11. 度量
| 指标 | 定义 | 典型量级 |
|---|---|---|
| 手册覆盖率 | 有处置路径的告警项占比 | 目标覆盖高优告警全部 |
| 演练执行成功率 | 按手册一次跑通的比例 | 目标 > 90% |
| 平均止血时长 | 从告警到服务可用的中位值 | 按月看趋势而非绝对值 |
| 手册过期条目数 | 与环境不一致的条目 | 目标为 0，每季清零 |
| 新人首次执行卡点数 | 无需提问完成的比例 | 目标 100% |
演练成功率是最有信息量的指标：它同时反映手册质量与环境漂移。文档写得再好，环境改了没人同步，成功率一样会掉。
12. 排错：手册用不起来的五种现场
| 现象 | 原因 | 处理 |
|---|---|---|
| 故障时没人看手册 | 搜索不到、入口太深 | 按告警项直接挂载对应章节 |
| 看了但不敢执行 | 缺回滚与影响范围 | 补回滚步骤与禁止条件 |
| 执行了没效果 | 判据失效或步骤过期 | 演练比对，改手册或改环境 |
| 每次故障都叫人 | 没有分级处置与授权 | 补授权与判据 |
| 手册越写越厚没人维护 | 无 owner、无过期指标 | 定 owner，按季度清零过期条目 |
第一条最普遍：手册在 wiki、告警在监控，两者不互通。把手册入口挂到告警通知上，比写一篇更全的文档有效。
13. 边界：正式手册运维是过度投入的情形
| 场景 | 判断 | 做法 |
|---|---|---|
| 系统极简（单进程单依赖） | 故障模式少 | 一页检查清单足够 |
| 故障模式少于三种 | 不需要决策树 | 三种剧本即可 |
| 已全自动化处置 | 人只需确认 | 手册只留判据与升级路径 |
| 服务已进入下线期 | 投入无法回收 | 只保留降级动作 |
| 故障可容忍停机 | 时间不敏感 | 靠常规排障，不写剧本 |
反向的边界：值班轮换频繁、跨时区、涉及数据一致性判断的系统，手册是必需品——因为值班的人不可能是最熟悉系统的人，而这类故障的处置顺序错了会放大损失。
14. 自测
- 手册要回答的四个问题里，哪个最常被漏掉，后果是什么？
- 巡检清单、故障剧本、决策树各自负责哪一段？
- "凌晨三点可执行"的判据里，哪一条缺失时最危险？
- 为什么"执行后无异常即正常"是错误期望？
- 手册演练的真正目的，是证明能用还是别的什么？
- 什么情况下自动化应该排在手册之后，而不是替代手册？