定时任务静默罢工？一条命令给整个 cron 舰队做体检

周一早上，你打开电脑，发现昨晚的定时任务根本没跑——而它已经这样静默三天了。hermes cron list 里任务明明还在，hermes cron status 也没报错，但就是没有任何输出、没有任何消息、没有任何日志告诉你哪里出了问题。这种“静默罢工”比报错更可怕：任务“看起来正常”，实际上早已死亡。8 月 31 日合入的新命令 hermes cron doctor 就是为这个场景准备的：一条只读命令，把整个 cron 舰队从头到尾体检一遍，发现任何问题就明确告诉你，并用退出码让你可以写进脚本自动告警。

为什么“看起来正常”却什么都没跑

这个命令诞生于真实的运维事故：一个跑着 60 个定时任务的生产环境里，有一个任务因为内容过滤失败已经死了 5 天，还有两个看门狗任务在静默地不触发——而现有的任何单一界面（list、status、incidents）都没法一眼看出问题。任务还在列表里，所以“看起来正常”；但 next_run_at 早就过期了，只是没人去核对。

这就是 cron 类系统的通病：调度器不主动报错，除非你去查“它本该什么时候跑、实际跑了没有”。

hermes cron doctor：一次体检，七个检查项

hermes cron doctor 是 hermes cron 家族的新子命令（hermes cron [list|create|edit|pause|resume|run|remove|status|runs|doctor|tick]）。它是只读的——不会修改任何任务配置，只是逐条检查每个启用的任务，然后报告发现。对照源码（hermes_cli/cron.py 的 _cron_doctor_issues_for_job），它检查这些项：

  • 上次运行是否失败：任务记录的 last_status 不是 ok 时，报告具体的 last_error；
  • 上次投递是否失败：报告 last_delivery_error，比如消息平台没送达；
  • 启用的任务没有 next_run_at：活跃任务却排不出下次运行时间，本身就是病；
  • next_run_at 已逾期：带 15 分钟的调度器宽限期，逾期会提示“next_run_at is Xm/h overdue — job is not firing (is the scheduler running?)”，这就是“任务静默不触发”的信号；
  • no-agent 任务缺脚本：纯脚本任务（no_agent: true）却没有配置 script；
  • 脚本健康问题：脚本本身的状态检查（比如文件不存在）；
  • 工作目录失效：任务的 workdir 在磁盘上不存在。

任何一个任务命中其中一项，都会被列出来——而这正是“在列表里躺着但实际已死”的任务唯一会留下的痕迹。

输出长什么样

没有问题时，输出非常清爽：

✓ Cron doctor found no issues
  Checked 12 active job(s).

发现问题时，它会按任务列出所有问题，并以退出码 1 结束：

Cron doctor found 3 issue(s) across 2 job(s):

  cron_daily_report
    - last run failed: content filter rejected output
    - next_run_at is 26.4h overdue — job is not firing (is the scheduler running?)
  nightly_backup
    - workdir not found: /data/backups

Next: fix the listed job config, then run `hermes cron doctor` again.

用起来：退出码才是重点

体检结果要能进自动化才有意义。命令的退出码设计得很干脆：0 = 全部健康，1 = 有需要处理的问题。这意味着你可以直接把它挂进自己的监控脚本：

# 每天早上一键体检，有问题就发告警
if ! hermes cron doctor; then
  hermes send -t telegram "cron 舰队有任务出问题了，快去查！"
fi

或者在需要的时候手动跑一下，当作日常巡检：hermes cron doctor。命令是只读的，随时可以放心执行。

何时能用上

PR #99479 于 2026 年 8 月 31 日合入，目前只在 main 分支，v0.20.6（8 月 27 日发布）还没有这个子命令。想立即用就更新到最新 main，或者等下一个版本发布。用法本身在官方文档的 cron 章节（website/docs/user-guide/features/cron.md）和 CLI 参考里都有记录。

定时任务的价值在于“没人盯着也能可靠运行”，而可靠的起点是知道它真的在跑。hermes cron doctor 把这个“知道”变成了一条命令。想搭建更完整的定时任务体系，可以看看我们的 cron 自动化完全指南 和 cron 监控与前置检查；如果任务总在半夜悄悄失败，网关心跳与看门狗调优 也值得一读。命令参考见 hermes cron 页面。