采集系统半夜出故障，该翻哪一页？Runbook 的工程实践

凌晨两点，告警响了：采集全停。我被叫起来，花了四十分钟才搞明白「怎么安全地重启」——没有文档，全靠翻代码和猜。第二天我写了一份 Runbook。之后再出故障，从被叫醒到处理完不超过十分钟。这篇记录采集系统 Runbook 怎么写。

Runbook 是什么

一句话：写给「半睡半醒的自己」的操作手册。每个已知故障场景一页：出什么症状、怎么确认、按什么步骤处理、怎么验证恢复、搞不定找谁。

它的质量标准不是「写得多全」，而是「凌晨两点照着做不会错」。

每页 Runbook 的结构

场景标题（一句话症状）
├─ 症状：告警什么样、用户能看到什么
├─ 快速确认：一条命令/一个检查确认是这个问题
├─ 处理步骤：编号，每步都是能直接执行的命令
├─ 验证：怎么确认已恢复
└─ 升级路径：X 分钟没解决，找谁

采集系统的常见场景清单

先写这六个，覆盖 90% 的半夜告警：

1. 采集全面失败（探活都不通了）
2. 部分失败率升高（个别端点/地区）
3. 磁盘使用率过高
4. 任务队列堆积
5. 成本/余额异常消耗
6. 数据断档需要补采

示例：磁盘使用率过高这一页

## 场景：磁盘使用率 > 90%

症状：告警 disk_usage>90%；采集日志出现写入失败
确认：df -h /data

处理：
1. 暂停归档任务：systemctl stop collector-archive
2. 清理 90 天前的日志：find /data/logs -mtime +90 -delete
3. 历史快照归档到对象存储：python tools/archive.py --before 90d
4. 仍超 90% 则扩容磁盘（云控制台 + 挂载）

验证：df -h 显示 < 80%；采集任务恢复正常写入
升级：30 分钟未解决 → 呼叫 @运维值班

注意几个细节：确认步骤在第一步（别处理错方向）、全是可直接复制的命令（当场没空理解概念）、验证和升级路径明确（处理的人不需要自己做决策）。

三条写作原则

1. 写命令，不写概念。 「检查磁盘空间」没用，「df -h /data，看 Use% 是否 > 90」才有用。
2. 先止血，后归因。 步骤设计成「先恢复服务」，分析原因放到事后。
3. 每步可验证。 一步做完能立刻知道对不对，而不是全做完才发现方向错了。

放置和联动

• 放在代码仓库的 docs/runbook/，和代码一起版本管理，改代码时顺手改 Runbook
• 告警消息里直接带 Runbook 链接——告警响的时候，人不用再去找文档

# 告警配置示例
- alert: DiskUsageHigh
  expr: disk_usage_percent > 90
  annotations:
    runbook: https://your-repo/docs/runbook/disk-full.md

这一条联动是投入产出比最高的：把「找文档」的几分钟直接省掉。

踩坑记录

坑 1：Runbook 只在一个人脑子里。 那个人休假，系统就没人敢动。写下来，到「照着做就行」的程度。

坑 2：只有概念没有命令。 「重启采集服务」——怎么重启？重启哪个？写「systemctl restart collector，然后 tail -f /data/logs/collector.log 看到 collector started」。

坑 3：写了不更新。 服务改名了、路径换了，Runbook 还写着旧命令，照做直接翻车。把 Runbook 更新写进变更清单：改服务配置 → 检查相关 Runbook。

坑 4：从没演练过。 第一次用它就是真故障现场，边用边发现写错了。定期挑一页演练，或者把这页当新人上手练习。

坑 5：告警不带链接。 告警响了还得手动搜文档。告警配置里带 runbook 链接。

工程清单

1. 六大常见场景先各写一页
2. 结构固定：症状 → 确认 → 处理 → 验证 → 升级
3. 命令可复制、先止血、每步可验证
4. 和代码同仓库版本管理
5. 告警消息带 Runbook 链接
6. 定期演练 + 随变更更新

Runbook 的价值可以一句话概括：把「凌晨两点靠聪明」变成「任何时候靠流程」。系统越无人值守，Runbook 越值钱——毕竟半夜被叫醒的时候，没人愿意当侦探。

排查 API 状态时（比如确认是服务端问题还是本地问题），接口响应里的 status 和 request_id 字段是很好的起点，字段说明见 SerpBase 官方文档。你们的采集系统有 Runbook 吗？半夜出故障一般谁处理？评论区聊聊。