深色模式
Runbook 应急手册
摘要：Runbook 与 SOP 的区别在于：SOP 面向计划内操作，Runbook 面向故障现场。本文给出 Runbook 的卡片式结构、按告警索引的组织方式，以及防止手册腐化的检查机制。
适用环境
bash
mkdir -p runbooks && cd runbooks
# Runbook 应与告警规则同源，annotation 中带链接
grep -rn 'runbook' /etc/prometheus/rules/*.yml | head1
2
3
2
3
操作步骤
第 1 步：区分 Runbook 与 SOP
bash
cat > diff.md <<'EOF'
| 维度 | SOP | Runbook |
| --- | --- | --- |
| 触发 | 计划内 | 突发告警 |
| 读者 | 执行者 | 值班人（可能不熟悉） |
| 重点 | 步骤完整 | 先止损，再定位 |
| 结构 | 线性 | 分支判断 |
EOF1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
第 2 步：卡片式模板
bash
cat > template.md <<'EOF'
# <现象名称>
> 触发：<告警名> 影响面：<谁受影响>
## 30 秒判断
- 是否刚有发布？`kubectl -n prod rollout history deploy/x`
- 是否单实例还是全量？
- 是否有降级开关可用？
## 止损动作（按优先级）
1. <最快恢复手段，附命令>
2. <次选>
## 定位线索
- 日志：<命令>
- 指标：<PromQL>
- 依赖：<检查项>
## 升级条件
- <N 分钟内未恢复 -> 通知谁>
EOF1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
第 3 步：止损优先，根因后置
bash
# Runbook 的第一段永远是可立即执行的止损动作
cat > pay-timeout.md <<'EOF'
# pay 调用超时导致下单失败
## 止损
1. 回滚最近一次发布：
kubectl -n prod rollout undo deploy/pay
2. 若非发布引起，扩容：
kubectl -n prod scale deploy/pay --replicas=10
EOF1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
DANGER
止损动作中的回滚、重启、切流都会影响线上流量。Runbook 必须写明前置确认条件（如"确认变更时间在故障起点之前"），避免盲目回滚。
第 4 步：与告警一一对应
yaml
annotations:
summary: 'pay P99 超时'
runbook_url: 'https://<docs-host>/ops/runbooks/pay-timeout.md'1
2
3
2
3
bash
# 检查：每条 critical 告警是否都有 Runbook
for a in $(grep -hoE 'alert: .+' /etc/prometheus/rules/*.yml | awk '{print $2}' | sort -u); do
ls runbooks/ | grep -qi "$a" || echo "缺 Runbook: $a"
done1
2
3
4
2
3
4
第 5 步：定期失效检查
bash
# 每季度检查：命令是否仍可 dry-run 通过、链接是否可达
cat > check-runbooks.sh <<'EOF'
#!/usr/bin/env bash
for f in runbooks/*.md; do
n=$(grep -c 'kubectl' "$f")
u=$(grep -oE 'https?://[^ )]+' "$f" | head -1)
code=$(curl -sS -o /dev/null -w '%{http_code}' --max-time 5 "$u" 2>/dev/null || echo 000)
echo "$f 命令数=$n 首链接=$code"
done
EOF
chmod +x check-runbooks.sh && ./check-runbooks.sh1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
验证
bash
# 1. 每篇 Runbook 都有止损段
grep -l '## 止损' runbooks/*.md | wc -l
# 2. 每条 critical 告警都有对应手册
grep -c 'alert:' /etc/prometheus/rules/*.yml | awk -F: '{s+=$2} END{print "告警总数:",s}'
ls runbooks/*.md | wc -l
# 3. 链接可访问
./check-runbooks.sh | grep -c '200'1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
常见坑
Runbook 写成排查思路长文
事故现场没人读长文。第一段必须是可立即执行的止损命令，细节放后面。
只覆盖已知故障
真正致命的是没见过的故障。定期从历史事故补 Runbook，覆盖 TOP 故障模式。
手册中的命令缺少命名空间与环境标识
值班人在错误环境执行会放大故障。所有命令强制带 -n <ns> 并标注环境。