心跳

心跳能发现发送链接发现不了的问题：没有启动的备份、卡住的后台进程、掉线的主机。你的服务按计划调用它的心跳链接，调用本身不会产生提醒。超过你允许的时间没有调用时，频道会收到一条提醒；恢复调用后，这条提醒会自动标记为已解决。

创建心跳

在应用中打开频道的发送链接，在发送链接下方找到心跳，选择创建心跳，然后设置：

• 名称：提醒中对这个任务的称呼，例如 夜间备份。
• 预期间隔：任务多久报到一次。
• 更多选项中：宽限时间（提醒前额外等待的时间）、提醒的标题、正文、级别和是否需要确认，以及恢复时是否通知。

创建后复制心跳链接，格式如下：

https://<api-host>/v1/heartbeat/<token>

这个链接只能上报心跳，不能发送提醒。但拿到它的人可以让心跳一直保持正常，所以仍请妥善保管。

要求端到端加密的频道不支持心跳，因为提醒由服务器生成，服务器无法加密。

上报心跳

GET、POST、HEAD 请求都可以，请求体会被忽略。上报得比需要的更频繁也没有关系。

curl -fsS -m 10 --retry 3 "$HEARTBEAT_URL"

只在任务成功后调用，这样任务失败时心跳也会停止：

30 2 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 "$(cat /etc/gregor-heartbeat-url)" >/dev/null

使用命令行工具时，gregor run -heartbeat "$HEARTBEAT_URL" -- backup.sh 还会在任务失败时立即发送提醒。

什么时候发提醒

上一次心跳之后经过一个预期间隔，下一次心跳就应该到达；再经过宽限时间仍未到达，就会发送提醒。例如每晚运行、宽限 1 小时的任务，会在最后一次成功运行约 25 小时后提醒。

状态	含义
等待首次心跳	已创建，还没有收到心跳。从创建时开始计时，从未报到的任务同样会提醒。
正常	上一次心跳按时到达。
迟到	已超过预期间隔，但还在宽限时间内，暂不提醒。
已超时	已超过宽限时间，已发送一条提醒。
已暂停	恢复之前不会提醒，例如在维护期间。

一次中断只会产生一条提醒。urgent 级别的心跳提醒会按你选择的间隔重复提醒，直到有人确认或任务恢复。中断后的第一次心跳会把提醒标记为已解决，并发送一条简短的恢复通知（可以关闭）。

在哪里查看状态

接收这个频道的所有设备都能看到它的心跳，包括不能修改心跳的订阅者：

• 频道：有心跳的频道会显示心跳数量和最需要关注的状态，例如“5 个心跳 · 1 个已超时”。点开可以看到每个心跳。频道管理者可以在这里，或在频道的操作菜单中创建和编辑心跳。
• 提醒：为某个心跳打开在提醒页显示状态后，接收这个频道的所有设备都会在提醒页顶部显示它，已超时的排在最前。

提醒内容

只有标题和正文是模板。在应用中用变量按钮插入：

变量	示例
{{monitor.name}}	夜间备份
{{channel.name}}	服务器
{{period}}	1d
{{last_heartbeat_ago}}	1d 1h
{{last_heartbeat_at}}	2026-10-26 02:31 +08
{{down_since}}	2026-10-27 03:31 +08
{{outage_duration}}	42m（仅恢复通知）

时间按创建心跳的设备所在时区显示。标题和正文遵循发送限制，并按每个变量可能的最长值计算，因此心跳提醒总能发出。

错误

状态码	错误码	含义
404	invalid_heartbeat_url	链接错误、已重新生成或删除，或频道已停用。
429	rate_limited	来自你的地址的请求过多。