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

> 用 Healthchecks.io（可托管，也可自托管）监控 cron 任务。任务失败、卡住或悄悄停止运行时，手机立即收到推送通知。介绍带 /start 和退出码的 Ping URL、能应对网络故障的 curl 参数、runitor，以及把告警发送到 Pocket Alert 的两种方式，另附一个不需要额外服务的小型包装脚本。

*27.10.2026*

<!-- source: https://pocketalert.app/zh/blog/cron-job-monitoring-healthchecks -->

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

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

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

## 准备工作

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

## 死人开关

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

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

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

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

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

Ping URL 有几种形式：

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>请求</th><th>含义</th></tr></thead>
<tbody>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;</code></th><td>成功。任务已完成。</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/start</code></th><td>任务已开始。Healthchecks 随后会在宽限时间内等待一次成功信号，并记录本次运行的耗时。</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/fail</code></th><td>任务失败。检查项立即变为离线。</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/&lt;0-255&gt;</code></th><td>退出状态。<code>0</code> 表示成功，其他值表示失败。</td></tr>
</tbody>
</table>
</div>

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

## 接入 cron 任务

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

```bash
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](https://github.com/bdd/runitor) 是一个小型 Go 二进制程序，它包装任务命令并负责发送 Ping：运行前发送 `/start`，运行后发送退出状态，并把命令输出的最后 10,000 字节附加到 Ping 中。

```bash
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 中的那一行因此变短：

```bash
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`。请求头每行一个：

```text
Content-Type: application/json
Token: YOUR_API_KEY
```

请求体：

```json
{
  "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 和请求头相同，请求体则更安静：

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

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

```json
{
  "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 中填入你自己的域名。[操作按钮](/features/action-buttons) 是付费功能；在免费套餐上会被移除，消息本身仍照常投递。

### 方式二：带模板的 Pocket Alert Webhook

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

在 Pocket Alert 控制台中打开 [Webhooks](/webhooks)，创建一个名为 `Healthchecks` 的 Webhook，并设置消息模板：

```text
%name% is %status% since %time%
%log%
```

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

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

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

恢复：

```json
{"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`：

```bash
#!/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 中：

```bash
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](/tools/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 任务告警](/use-cases/cron-job-alerts) 页面介绍了如何从任务本身发送推送，[备份告警](/use-cases/backup-alerts) 介绍了备份工具的相关内容，[Proxmox 指南](/blog/proxmox-alerts) 则涵盖了虚拟化主机上的备份。

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