返回博客

使用 Healthchecks.io 监控 cron 任务:任务失败或未运行时,手机收到推送通知

使用 Healthchecks.io 监控 cron 任务:任务失败或未运行时,手机收到推送通知

一个 cron 任务可能以两种方式出问题。一种是运行了但失败了:pg_dump 连不上数据库,或者磁盘满了。另一种是根本没有运行:crontab 里的那一行被删了,服务器重装时漏掉了它,或者 cron 守护进程已经挂了。第一种至少会留下错误记录。第二种什么都不会留下,直到你需要昨晚的备份时才发现它没有跑。

如果告警只等任务主动报告“我失败了”,那么任务根本没启动时,它永远不会收到任何消息。要抓住这种情况,需要反过来设置:任务每次结束时都汇报一次,而报告没有按时到达时,由另一个系统发出警报。

本文用开源的 cron 监控工具 Healthchecks.io 实现这套机制,并通过 Pocket Alert 把告警发送到你的手机。失败时提醒要醒目,恢复时提醒要安静。下面的所有内容都在自托管的 Healthchecks v5.0.3 Docker 镜像上测试过,在托管服务上的效果相同。

准备工作

  • 一个 healthchecks.io 账户(免费的 Hobbyist 套餐可监控 20 个任务),或者使用 healthchecks/healthchecks Docker 镜像部署你自己的实例。
  • 你的 iPhone 或 Android 手机上安装 Pocket Alert 应用,并在 API 密钥 页面获取一个 API 密钥。开始使用免费套餐就够了。
  • 运行 cron 任务的机器上安装 curl。

死人开关

Healthchecks 把这种机制称为心跳监控,是一种死人开关。每个任务对应一个检查项,它有唯一的 Ping URL,任务结束时请求这个 URL。如果下一次请求没有按时到达,检查项就会变为离线,告警随之发出。

决定“按时”的是两项设置:

  • 周期:你期望多久收到一次 Ping,例如每小时或每天。
  • 宽限时间:超过预期时间后,Healthchecks 再等待多久才判定为离线。建议设置得比任务的平均耗时更长,并留出一些余量。

对于 cron 任务,应选择 Cron 调度类型,然后粘贴 crontab 中的表达式,并设置服务器的时区。这样 Healthchecks 就会按照一天中的具体时刻期望 Ping,而不只是按固定间隔。cron 表达式编辑器 会解释每个表达式的含义。

在我们的测试中,调度为 */2 * * * *、宽限时间为一分钟的检查项在 16:09:13 收到了 Ping。16:10 没有任何 Ping,检查项在 16:11:00 变为离线,恰好晚了一个宽限周期。

Ping URL 有几种形式:

请求含义
https://hc-ping.com/<uuid>成功。任务已完成。
https://hc-ping.com/<uuid>/start任务已开始。Healthchecks 随后会在宽限时间内等待一次成功信号,并记录本次运行的耗时。
https://hc-ping.com/<uuid>/fail任务失败。检查项立即变为离线。
https://hc-ping.com/<uuid>/<0-255>退出状态。0 表示成功,其他值表示失败。

在自托管实例上,基础地址换成你自己的域名加上 /ping/,例如 https://hc.example.com/ping/<uuid>。

接入 cron 任务

创建一个检查项,复制它的 Ping URL,然后修改 crontab 中的那一行。我们在 Debian 13 上通过 cron 守护进程运行了以下配置:

PING=https://hc-ping.com/your-check-uuid
15 3 * * * curl -fsS -m 10 --retry 5 -o /dev/null $PING/start; /usr/local/bin/backup.sh; curl -fsS -m 10 --retry 5 -o /dev/null $PING/$?

PING= 是 crontab 的变量,shell 会在执行命令时将其展开。这一行完成三件事:

  • 发送 /start,这样任务卡住时,宽限时间一过检查项就会离线。在我们的测试中,只发送 /start 而没有后续信号,检查项恰好在一个宽限周期后变为离线。
  • 运行任务本身。
  • 发送 $?,即任务的退出状态。正常完成时发送 /0,失败时发送 /2 或脚本返回的其他值,检查项会立即离线。

curl 参数保证 Ping 本身不会引发额外问题:

  • -m 10 将每次请求限制在 10 秒内。卡住的 /start 不能拖住任务。
  • --retry 5 对超时以及 408、429、500、502、503、504 响应进行重试,且延迟逐步增加。偶尔丢一个包不应该把你吵醒。
  • -fsS 让 curl 在 HTTP 出错时失败,并且除非出错否则保持安静,这样 cron 就不会把 curl 的进度条通过邮件发给你。
  • -o /dev/null 丢弃响应体,响应内容只是 OK。

如果任务是类似 pg_dump | gzip > dump.gz 的管道,它的退出状态取的是 gzip 的状态,而不是 pg_dump 的。应该把它放进脚本中,并在 bash 中使用 set -o pipefail,这样 dump 失败时就不会报告成功。

或者交给 runitor

runitor 是一个小型 Go 二进制程序,它包装任务命令并负责发送 Ping:运行前发送 /start,运行后发送退出状态,并把命令输出的最后 10,000 字节附加到 Ping 中。

curl -fsSL -o /usr/local/bin/runitor https://github.com/bdd/runitor/releases/download/v1.4.1-build.6/runitor-v1.4.1-build.6-linux-amd64
chmod +x /usr/local/bin/runitor

crontab 中的那一行因此变短:

15 3 * * * CHECK_UUID=your-check-uuid /usr/local/bin/runitor -- /usr/local/bin/backup.sh

如果使用自托管实例,再添加 HC_API_URL=https://hc.example.com/ping。我们在 cron 下这样运行了 runitor v1.4.1:备份失败后,检查项以退出状态 2 变为离线,告警中也带上了错误输出。

把告警发送到 Pocket Alert

Healthchecks 通过其通用的 Webhook 集成连接 Pocket Alert。进入 Integrations,找到 Webhook,点击 Add Integration。表单分为两部分,“检查项离线时执行”和“检查项恢复时执行”,每部分都有各自的 URL、方法、请求体和请求头。这种拆分让“离线”醒目,“恢复”安静。

两部分都支持占位符:$NAME、$NAME_JSON、$STATUS、$NOW、$CODE、$SLUG、$TAGS、$EXITSTATUS、$BODY、$BODY_JSON、$JSON 以及其他几个。对于 JSON 请求体,要注意区别:$NAME 是原样粘贴的,所以名为 Nightly "db" backup 的检查项会破坏 JSON;而 $NAME_JSON 是完整的 JSON 字符串,包括引号。$BODY 和 $BODY_JSON 也是同样的关系。

方式一:直接调用 API

在离线部分,选择 POST,URL 填写 https://api.pocketalert.app/v1/messages。请求头每行一个:

Content-Type: application/json
Token: YOUR_API_KEY

请求体:

{
  "title": $NAME_JSON,
  "message": "DOWN since $NOW. Exit status of the last ping: $EXITSTATUS",
  "level": "high",
  "actions": [{"type": "view", "label": "Open check", "value": "https://healthchecks.io/checks/$CODE/details/"}]
}

在恢复部分,方法、URL 和请求头相同,请求体则更安静:

{
  "title": $NAME_JSON,
  "message": "Back up at $NOW",
  "level": "low"
}

点击 Save Integration。新集成会附加到项目中所有现有检查项上。下面是我们的测试检查项失败时 Healthchecks 发送的内容:

{
  "title": "Nightly \"db\" backup",
  "message": "DOWN since 2026-10-31T16:15:01+00:00. Exit status of the last ping: 2",
  "level": "high",
  "actions": [{"type": "view", "label": "Open check", "value": "https://healthchecks.io/checks/a4b72803-3a50-4b81-b33f-88dd2200ffc2/details/"}]
}

关于这个请求体的几点说明:

  • high 表示需要及时处理。 它会穿透专注模式和定时摘要。在付费套餐上,可以改为 critical,这样备份任务失效时,即使静音开关打开或处于勿扰模式,你也会被唤醒。免费套餐接受 critical,但会按 high 投递。
  • 恢复使用 low。 “Back up” 会静默进入消息列表。你需要知道这件事,但不必在凌晨三点被打扰。
  • $EXITSTATUS 用来区分失败和缺失。 它是告警发出前最后一次 Ping 的退出状态。2 表示任务运行了并返回了 2。离线时如果是 0,说明上一次运行成功了,但下一次一直没有出现。-1 表示最后一次 Ping 没有携带退出状态,例如普通的成功 URL、/fail 或 /start。
  • 按钮 会在 Healthchecks 中打开该检查项。自托管实例需要在 URL 中填入你自己的域名。操作按钮 是付费功能;在免费套餐上会被移除,消息本身仍照常投递。

方式二:带模板的 Pocket Alert Webhook

第二种方式是把一份小型 JSON 文档发送到 Pocket Alert 的 Webhook,由它来格式化推送内容。优点是可以包含任务的输出。

在 Pocket Alert 控制台中打开 Webhooks,创建一个名为 Healthchecks 的 Webhook,并设置消息模板:

%name% is %status% since %time%
%log%

不要选择 Default priority,因为请求体自带级别。复制 Webhook URL,形如 https://p4a.me/wh/abc123xyz。这个 URL 本身就是密钥,请像对待密码一样保管。

在 Healthchecks 中创建 Webhook 集成,两部分都使用 POST 方法,URL 填入上面的地址,请求头设置为 Content-Type: application/json,请求体如下。离线:

{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "high"}

恢复:

{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "low"}

$BODY_JSON 是最后一次 Ping 的请求体,runitor 就是把任务输出放在这里。在我们的测试中,经过 runitor 包装的备份失败后,推送内容如下:

Webhook Healthchecks
DB backup (runitor) is down since 2026-10-31T16:15:02+00:00
dumping appdb
pg_dump: error: connection to server on socket failed: No such file or directory

[runitor] exit status 2

Pocket Alert 会读取传入负载顶层的 level 字段,因此 high 和 low 的效果与方式一相同。如果不使用 runitor,$BODY_JSON 为空字符串,第二行就是空白。API 方式做不到这一点:它的 $BODY_JSON 是完整的 JSON 字符串,因此只能作为整个 message,而 Ping 没有请求体时,这条消息为空,API 会拒绝请求。

另外两点区别:推送标题始终是 Webhook <name>,所以检查项名称需要放进消息内容里;Webhook 的按钮通过 Webhooks API 的 actions 字段设置,而不是控制台表单。

测试一下

在 Healthchecks 的 Integrations 页面,每个集成旁边都有一个 Test! 按钮。它会为名为 TEST 的检查项发送一条“离线”通知,并以 high 级别的推送到达。然后运行一个以退出码 1 结束的任务,看看真实告警是否到达。

不用 Healthchecks:失败时推送的包装脚本

如果你不想再引入一个服务,可以用一个简短的包装脚本覆盖最常见的情况,即任务以错误码退出。将其保存为 /usr/local/bin/cron-alert:

#!/bin/sh
# Usage: cron-alert <job name> <command> [args...]
name="$1"
shift

log=$(mktemp)
"$@" >"$log" 2>&1
status=$?

if [ "$status" -ne 0 ]; then
  curl -fsS -m 10 --retry 3 --retry-max-time 30 -o /dev/null \
    -H "Token: $POCKETALERT_API_KEY" \
    --form-string "title=Cron failed: $name on $(hostname)" \
    --form-string "message=Exit status $status. $(tail -c 2000 "$log")" \
    --form-string "level=high" \
    "${POCKETALERT_API_URL:-https://api.pocketalert.app/v1/messages}"
fi

cat "$log"
rm -f "$log"
exit "$status"

然后在 crontab 中:

POCKETALERT_API_KEY=your-api-key
15 3 * * * /usr/local/bin/cron-alert "nightly backup" /usr/local/bin/backup.sh

这里有几个刻意的设计选择:

  • 使用 --form-string 而不是 JSON。 API 接受 multipart 表单数据,--form-string 会原样发送输出内容,包括引号和换行,无需 jq 或转义。普通的 -F 会把以 @ 或 < 开头的值当作文件。
  • tail -c 2000 保留输出的末尾部分,错误信息通常就在那里。
  • --retry-max-time 30 很重要。超出每日消息上限时,API 返回 429,并附带 Retry-After,其值为距离 UTC 午夜的秒数,而 curl 的 --retry 会遵守这个值。在我们的测试中,如果不加这个参数,curl 会一直等待 Retry-After: 30000,直到我们手动终止它。加上之后,curl 只尝试一次就放弃。
  • 包装脚本保留退出状态并输出日志内容,因此 cron 日志和 MAILTO 仍然照常工作。

脚本通过了 shellcheck。在 Debian 13 上的 cron 环境中,失败的备份以“Cron failed: nightly backup on”加主机名的标题到达,正文中包含 pg_dump 的错误信息。

需要说清楚这个方案做不到什么。包装脚本只有在 cron 运行它时才会运行。如果 crontab 那一行被删除、守护进程挂了,或者机器关机了,什么都不会发送,这正是本文开头提到的那种无声故障。一个永远卡住的任务同样不会被发现。针对这些情况,你需要机器之外有一个等待心跳的监控,这正是 Healthchecks 的用途。如果你更喜欢,可以用 Pocket Alert CLI 替代 curl 调用。

诚实的局限

  • Healthchecks 必须保持运行才能发现问题。 在托管服务上,这是它们的工作。如果你把它自托管在运行 cron 任务的同一台机器上,机器宕机时监控也会一起失效。请把它部署在别处。
  • Healthchecks 的请求体模板限制为 1,000 个字符。 对于上面的请求体已经足够,但不适合长篇手写消息。
  • 推送中的长输出会被截断。 推送大约包含消息的前 3 KB,完整文本保存在应用的消息历史中。
  • 每条告警就是一条消息。 如果任务每隔几分钟就在离线和恢复之间反复切换,每次都会发送一条推送,而免费套餐每天只有 50 条消息,很快就会用完。请修复任务本身,或者提高宽限时间。

如果没有收到通知

  • 先点 Test! 按钮。 如果测试能收到,但真实告警收不到,请在检查项页面确认该检查项已启用此集成。
  • 查看 Healthchecks 的 Integrations 页面。 出错的集成会被标记为 Failed,将鼠标悬停其上可以看到最后一次错误,例如 Received status code 401。401 表示 Token 请求头有误。400 通常表示请求体不是合法的 JSON:请检查你是否使用了不带引号的 $NAME_JSON,而不是 "$NAME"。
  • 新建的检查项在收到第一次 Ping 之前不会告警。 在此之前它的状态是“新建”,而不是“离线”。
  • 检查 cron 检查项的时区。 如果检查项总是早一小时或晚一小时,说明服务器时区与检查项中设置的时区不一致。
  • 查看消息列表。 low 推送没有声音,因此恢复通知可能看起来从未到达。

常见问题

应该使用 API 方式还是 Webhook 方式?

API 方式会把检查项名称放在推送标题中,并且不需要在 Pocket Alert 中创建任何内容。Webhook 方式可以包含任务输出,因此如果你使用 runitor,应选择 Webhook。

能只接收“离线”告警吗?

可以。像上面那样为“恢复”使用安静的 low 请求体,或者将“恢复”URL 留空,这样 Healthchecks 在恢复时就不会发送任何内容。

systemd 定时器怎么办?

思路相同。Healthchecks 提供 OnCalendar 调度类型,接受与你的定时器相同的表达式。可以在 /start 中发送 ExecStartPre,也可以用 runitor 包装 ExecStart 命令。

在哪里可以了解更多 cron 告警?

cron 任务告警 页面介绍了如何从任务本身发送推送,备份告警 介绍了备份工具的相关内容,Proxmox 指南 则涵盖了虚拟化主机上的备份。

创建一个免费账户,在 Healthchecks 中添加一个 Webhook 集成,让那个悄悄停止运行的任务来把你叫醒。

分享这篇文章