给自动化写一份运行手册:出问题时,你需要的是它而不是日志
日志解决「发生了什么」,运行手册解决「现在该怎么办」。
这两件事经常被混为一谈。结果是脚本挂掉之后,你手里有一堆日志,却不知道第一步该敲什么命令。
一、什么情况下需要 runbook
不是所有脚本都要。判断标准很简单:
这个脚本挂了,会不会有人在三更半夜需要处理它?
- 一次性脚本、临时验证:不需要
- 每天定时跑、失败会影响别人:需要
- 涉及写操作、失败可能留下脏数据:必须有
运行手册的本质,是把「我知道该怎么做」变成「谁看了都能做」。
二、一份够用的 runbook 长什么样
不用写成长篇文档,五节就够:
1. 它是干什么的
三句话说清:做什么、什么时候跑、失败了影响谁。
# 每日任务自动化
每天 09:00 运行,完成签到、浏览、DevSpace 体验、发布文章。
失败影响:当天积分拿不到,不涉及数据写入,可安全重跑。
最后一句「可安全重跑」比什么都重要——它决定了出事时你敢不敢直接重跑。
2. 前置条件
- Chrome 以 --remote-debugging-port=9222 运行,且已登录
- session_cookies.json 存在且未过期
- 本机可访问 devdata.huaweicloud.com
前置条件写清楚,能过滤掉一半的「莫名其妙失败」。
3. 怎么启动
一条命令,可以直接复制。
python watch_login.py
不要写成「先进入目录,然后运行脚本,注意参数」这种散文。命令就是命令。
4. 怎么确认它成功了
成功的标志:
- 终端出现 "LOGIN OK"
- 最后一行是 "MISSIONS done N/14"
- grow_state.json 的修改时间是刚才
「怎么确认成功」是最容易漏的一节。 没有它,跑完你也不知道成没成。
5. 出问题怎么办
这一节用表格,按症状查:
| 症状 | 可能原因 | 处置 |
|---|---|---|
| 403 not login | 会话过期 | 重新登录,跑一次 watch_login 抓 Cookie |
| Connection refused | Chrome 没开调试端口 | 用指定参数重启 Chrome |
| 卡在 waiting for login | 页面没加载完 / 未登录 | 手动在浏览器里确认登录态 |
| 积分没到账 | 平台批量结算延迟 | 等 30 分钟再看,别重复跑 |
表格的价值在于查,不在于读。出事的时候人是慌的,没耐心看段落。
三、写 runbook 的时机
我的习惯是:第一次踩坑解决之后立刻写。
因为那时候你还记得症状长什么样、第一反应想到什么、最后怎么解决的。过一周再补,就只剩「好像是 Cookie 的问题」这种没法用的信息。
写的时候把自己当读者:如果我现在什么都不记得,看到这条能不能照做?
四、和日志、告警的分工
三者各管一段:
- 告警:出事了,叫醒你
- 日志:出什么事了,在哪一步
- runbook:现在敲什么命令
缺任何一个,处理时间都会翻倍。
最常见的组合缺失是「有日志没手册」:你知道它在第 5 步 403 了,然后开始翻代码、翻历史提交,花二十分钟才想起来「哦,要重新登录」。
如果手册上有一行「403 not login → 重跑 watch_login」,这件事就是十秒。
五、一个反直觉的建议
runbook 要写给「不是你的人」看。
哪怕是个人项目。因为三个月后的你,跟一个陌生人差不多——你不记得当时为什么这么设计,也不记得那个报错是什么意思。
写的时候少用「那个」「之前说的」,多写具体名词和完整命令。这不是给别人看的礼貌,是给未来的自己留的台阶。
六、最后
自动化的成熟度,不看它跑得多顺,看它挂得多好处理。
跑得顺的时候,日志和手册都用不上;一旦出问题,这两样东西决定了你是十分钟解决,还是折腾一晚上。
花半小时写一份 runbook,换的是以后每一次出事时的从容。
- 点赞
- 收藏
- 关注作者
评论(0)