深色模式
值班手册 Runbook
摘要：Runbook 的价值在于凌晨三点被人打开时，不需要思考就能执行。本文给出固定的七段式模板、命令块的写法规范，以及用脚本检查手册中命令是否仍有效的做法。
适用环境
bash
mkdir -p runbooks && cd runbooks
# 建议统一为 Markdown，便于检索与版本管理
ls -1 *.md | head1
2
3
2
3
操作步骤
第 1 步：套用七段式模板
bash
cat > pay-latency.md <<'EOF'
# pay 接口延迟升高
> 一句话：pay 服务 P99 > 1s 持续 5 分钟
## 影响
- 用户：下单页卡顿
- 关联：order 服务超时重试增加
## 先看什么
1. 监控大盘：<面板地址>
2. 关键指标：http_request_duration_seconds_bucket{job="pay"}
## 止损动作（按顺序）
- [ ] 确认是否为发布引起：`kubectl rollout history deploy/pay`
- [ ] 若是，回滚：见下方命令
- [ ] 若否，扩容：`kubectl scale deploy/pay --replicas=10`
## 根因线索
- 慢查询：`kubectl exec -it deploy/pay -- sh -c 'cat /var/log/app/slow.log | tail -50'`
- 依赖下游：检查 redis/mysql 延迟
## 升级条件
- 15 分钟内未恢复 → 通知 pay 负责人
## 事后
- 记录时间线，开复盘单
EOF1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
第 2 步：命令块要"能复制就能跑"
bash
# 好：完整、带命名空间、带输出说明
kubectl -n prod rollout undo deploy/pay
# 坏：省略参数、依赖读者记忆
kubectl rollout undo deploy/pay1
2
3
4
5
2
3
4
5
第 3 步：危险命令单独标注
bash
# 以下会中断流量，仅在确认止损必要时执行
kubectl -n prod scale deploy/pay --replicas=01
2
2
DANGER
scale --replicas=0、删库、drop 表类操作必须在 Runbook 中单独加危险标记，并写明前置确认条件与回滚方式。
第 4 步：把 Runbook 挂到告警上
yaml
annotations:
summary: 'pay P99 延迟过高'
runbook_url: 'https://<docs-host>/ops/oncall/runbooks/pay-latency.md'1
2
3
2
3
第 5 步：定期检查手册是否失效
bash
# 提取手册中的 kubectl 命令做 dry-run 校验
grep -oE 'kubectl[^`]+' pay-latency.md | while read -r c; do
echo "--- $c"; eval "${c/ kubectl/ kubectl --dry-run=client}" 2>&1 | tail -1
done1
2
3
4
2
3
4
验证
bash
# 1. 每篇手册都有"影响 / 先看什么 / 止损动作 / 升级条件"四节
for f in *.md; do
miss=""
for s in '## 影响' '## 先看什么' '## 止损动作' '## 升级条件'; do
grep -q "$s" "$f" || miss="$miss $s"
done
[ -z "$miss" ] && echo "$f OK" || echo "$f 缺失:$miss"
done
# 2. 告警中的 runbook_url 可访问
curl -sS -o /dev/null -w '%{http_code}\n' "$(grep -m1 runbook_url pay-latency.md | sed 's/.*: //')"1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
常见坑
只写"检查一下 XX"
没有具体命令和判读标准的步骤等于没写。每一步都要给出命令 + 期望输出 + 异常时的分支。
手册写完从不更新
服务改了端口、换了命名空间，手册就变成误导。把手册与代码同仓存放，随变更一起评审。
手册里的命令未加命名空间
值班人容易在错误的命名空间执行，把预发当生产或反之。所有命令强制带 -n <ns>。