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

一个 cron 任务可能以两种方式出问题。一种是运行了但失败了:pg_dump 连不上数据库,或者磁盘满了。另一种是根本没有运行:crontab 里的那一行被删了,服务器重装时漏掉了它,或者 cron 守护进程已经挂了。第一种至少会留下错误记录。第二种什么都不会留下,直到你需要昨晚的备份时才发现它没有跑。
如果告警只等任务主动报告“我失败了”,那么任务根本没启动时,它永远不会收到任何消息。要抓住这种情况,需要反过来设置:任务每次结束时都汇报一次,而报告没有按时到达时,由另一个系统发出警报。
本文用开源的 cron 监控工具 Healthchecks.io 实现这套机制,并通过 Pocket Alert 把告警发送到你的手机。失败时提醒要醒目,恢复时提醒要安静。下面的所有内容都在自托管的 Healthchecks v5.0.3 Docker 镜像上测试过,在托管服务上的效果相同。
准备工作
- 一个 healthchecks.io 账户(免费的 Hobbyist 套餐可监控 20 个任务),或者使用
healthchecks/healthchecksDocker 镜像部署你自己的实例。 - 你的 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 集成,让那个悄悄停止运行的任务来把你叫醒。