给自动化写一份运行手册:出问题时,你需要的是它而不是日志

举报
yd_219023509 发表于 2026/11/13 10:28:21 2026/11/13
【摘要】 日志说发生了什么,运行手册说现在该干什么。这篇给出一份够用的 runbook 结构:它是做什么的、前置条件、怎么启动、怎么确认成功、出问题怎么查,以及一张按症状查的故障表。

日志解决「发生了什么」,运行手册解决「现在该怎么办」。

这两件事经常被混为一谈。结果是脚本挂掉之后,你手里有一堆日志,却不知道第一步该敲什么命令。

一、什么情况下需要 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,换的是以后每一次出事时的从容。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。