Healthchecks Shell 脚本接入实战：用 curl 为 cron 与后台任务加上 Ping 监控

• 后端
• 任务调度

本指南以 healthchecks 官方文档 templates/docs/bash.md 为核心，讲解如何在任意 Shell 脚本中通过一条 curl 命令接入 healthchecks（开源 cron 任务与后台进程监控服务，基于 Python & Django 实现），完成成功/失败信号的主动上报、命令输出日志的上传，以及基于 slug 的自动注册（auto provisioning）。读完本文，你可以在 5 分钟内为自己的备份、证书续期、数据库导出等脚本加上带重试、超时与失败语义的监控能力，并理解这些行为在服务端源码中的落地方式。

一、原理速览：一个 HTTP 请求就是一个监控信号

healthchecks 的接入方式非常简单：每个检查（Check）都有一个专属的 ping URL。脚本在关键节点对该 URL 发起 HTTP 请求（GET / HEAD / POST 均可，见 Pinging API 文档），healthchecks 服务端收到请求后记录一次 ping，并据此判断任务是否按时完成。

ping URL 的构造规则在 hc/api/urls.py 中一目了然：

• 按 UUID 标识：PING_ENDPOINT<uuid>，以及/start、/fail、/log、/<exit-status>等后缀；
• 按 slug 标识：PING_ENDPOINT<ping-key>/<slug>，同样支持上述后缀。

其中PING_ENDPOINT是部署时的基础端点。在 hc/settings.py 中可以看到它的默认值由SITE_ROOT推导：

SITE_NAME = os.getenv("SITE_NAME", "Mychecks") PING_ENDPOINT = os.getenv("PING_ENDPOINT", SITE_ROOT + "/ping/") PING_BODY_LIMIT = envint("PING_BODY_LIMIT", "10000")

也就是说，自托管部署时可以通过SITE_NAME、SITE_ROOT、PING_ENDPOINT等环境变量定制站点名与端点地址。在 Web 界面中，每个检查的详情页会直接展示可复制的 ping URL（官方文档中的PING_URL、PING_ENDPOINT、SITE_NAME等占位符由 hc/front/management/commands/pygmentize.py 在渲染文档时替换为真实值），脚本里只需要把PING_URL换成你自己的 URL 即可。

二、最小接入：在脚本里发一条 curl

curl 和 wget 是最常用的两个命令行 HTTP 客户端，healthchecks 官方在 templates/docs/bash.md 中给出了两种等价写法：

# Sends an HTTP GET request with curl: curl -m 10 --retry 5 PING_URL # Silent version (no stdout/stderr output unless curl hits an error): curl -fsS -m 10 --retry 5 -o /dev/null PING_URL

第一行最简：向PING_URL发起一次 GET 请求，表示"任务成功完成"（对持续运行型任务则代表"进程仍存活且健康"）。第二行是生产环境推荐写法——把 curl 的进度条和正常输出全部静默掉，只在出错时才暴露信息，避免污染脚本自身的 stdout/stderr 输出管道。

三、逐参数拆解：每个 curl 选项的含义

官方文档对上述参数逐一给出了说明，整理如下：

-m <seconds>请求允许的最大耗时（秒）。配合--retry使用时，每次重试都会重置计时器——也就是说单次尝试最多花费这么多秒，而不是整轮重试累计。

--retry <num>遇到瞬时错误时最多重试的次数。默认情况下 curl 会采用递增的退避间隔（1s、2s、4s、8s……），也可以用--retry-delay覆盖。curl 判定的"瞬时错误"包括：超时，以及 HTTP 状态码 408、429、500、502、503、504。

-f, --fail让 curl 把非 200 响应视为错误。不加该参数时，即使服务端返回 4xx/5xx，curl 仍以退出码 0 结束，脚本的$?会误判为成功——这是隐蔽的监控失效来源。

-s, --silent静默模式。隐藏进度条，但同时也会隐藏错误信息。

-S, --show-error与-s搭配使用，重新启用错误信息的输出。二者合写为-fsS，正是官方示例的用法。

-o /dev/null把 curl 的 stdout 重定向到/dev/null（错误信息仍走 stderr）。由于 ping 响应体通常是 "OK" 这样无意义的短字符串，丢弃它不会丢失任何诊断信息。

如果脚本环境没有 curl，wget 也可作为替代（如wget --spider -q PING_URL），但官方示例与参数说明以 curl 为标准。

四、主动上报失败：/fail与/{exit-status}

healthchecks 的默认语义是"超时未 ping 即判失败"。但很多场景下我们希望主动、立即上报失败，从而把告警延迟从"超时等待"缩短到"出错瞬间"。做法很简单：在任意 ping URL 上追加/fail或/{exit-status}。

• /fail：直接发送失败信号；
• /{exit-status}：追加任务的退出码。退出码为 0 视为成功，非 0 一律视为失败。退出码必须是 0–255 之间的整数。

官方示例用/usr/bin/certbot renew演示了通过$?读取退出码并拼接到 URL 的完整写法：

#!/bin/sh # Payload here: /usr/bin/certbot renew # Ping SITE_NAME curl -m 10 --retry 5 PING_URL/$?

服务端如何解释这段 URL？看 hc/api/urls.py 中的路由定义：path("<int:exitstatus>", views.ping)捕获退出码；再看 hc/api/views.py 中的ping()视图：

if exitstatus is not None and exitstatus > 255: return HttpResponseBadRequest("invalid url format") ... if exitstatus is not None and exitstatus > 0: action = "fail"

即：退出码超过 255 会返回 400 "invalid url format"（与文档中描述的 0–255 整数约束完全对应），非 0 退出码被映射为fail动作，0 则保持成功。该逻辑对 UUID 与 slug 两种寻址方式同样生效。

管道陷阱：别忘了set -o pipefail

脚本里经常出现command1 | command2 | command3的管道写法。Bash/Sh 的默认规则是：管道的退出码等于最右侧命令的退出码。这意味着即使左侧命令失败，只要右侧命令成功，$?依然是 0，脚本会误报成功。

官方示例用数据库备份场景展示了这一点：

#!/bin/sh set -o pipefail pg_dump somedb | gpg --encrypt --recipient alice@example.org --output somedb.sql.gpg # Without pipefail, if pg_dump command fails, but gpg succeeds, $? will be 0, # and the script will report success. # With pipefail, if pg_dump fails, the script will report the exit code returned by pg_dump. curl -m 10 --retry 5 PING_URL/$?

开启set -o pipefail后，只要管道中任何一个环节失败，$?就会取到首个失败命令的退出码，PING_URL/$?上报的自然是失败信号。建议把set -o pipefail与set -euo pipefail一起放在脚本头部，配合本文的 ping 上报，形成"任一步骤出错立即上报失败"的健壮监控闭环。

五、把命令输出作为日志上报：HTTP POST +--data-raw

如果希望故障排查时有更多上下文，可以在 ping 时附带诊断信息。做法是改用HTTP POST，把命令输出放进请求体：

#!/bin/sh m=$(/usr/bin/certbot renew 2>&1) curl -fsS -m 10 --retry 5 --data-raw "$m" PING_URL

要点在于：2>&1把 stderr 并入 stdout，$(...)捕获全部输出，--data-raw "$m"原样作为 POST 请求体发送。服务端的行为由 hc/api/views.py 中的这行代码决定：

body = request.body[: settings.PING_BODY_LIMIT]

即：只要请求体是合法的 UTF-8 字符串，healthchecks 就接受并存储请求体的前PING_BODY_LIMIT字节（默认 10000 字节，可用环境变量调整，见 hc/settings.py）；其余部分会被截断丢弃。响应头中的Ping-Body-Limit: <n>会告知客户端服务端实际愿意存储的字节数，方便客户端据此裁剪后续请求体（详见 hc/api/views.py 的实现）。

从源码结构看，较大的请求体还有一层优化：在 hc/api/models.py 的Check.ping()方法中，超过 100 字节且配置了S3_BUCKET时，请求体会写入对象存储（ping.object_size = len(body)），否则直接存入数据库的body_raw字段——日志不会挤爆数据库行。更多关于日志大小限制、只保留最后 N 字节等技巧，可继续阅读 attaching_logs.md。

六、自动注册：?create=1让脚本第一次运行就创建检查

healthchecks 支持自动创建（auto provisioning）：当请求指向一个尚不存在的 slug 时，服务端会顺手把它创建出来。官方在 autoprovisioning.md 中说明：启用该能力只需在slug 风格的 ping URL 末尾追加?create=1。

官方示例用系统主机名作为 slug，实现"首次运行即注册"：

#!/bin/bash PING_KEY=fixme-your-ping-key-here # Use system's hostname as check's slug SLUG=$(hostname) # Construct a ping URL and append "?create=1" at the end: URL=PING_ENDPOINT$PING_KEY/$SLUG?create=1 # Send a ping: curl -m 10 --retry 5 $URL

服务端的判定逻辑在 hc/api/views.py 的ping_by_slug()中：

1. 先按(slug, project__ping_key)查现有检查：
   • 不存在且 URL 带create=1→ 创建检查（名称与 slug 均取该 slug），并自动关联项目下全部通知渠道（check.assign_all_channels()），响应 201 "Created"；
   • 存在→ 正常记录 ping，响应 200 "OK"；
   • slug 重复（匹配到多个检查）→ 返回 409 "ambiguous slug"，本次请求被忽略；
   • slug 含大写字符（slug != slug.lower()）→ 返回 400 "invalid url format"（slug 只允许a-z、0-9、下划线和连字符）。

该能力尤其适合动态基础设施：把 Ping Key 分发给各监控客户端，每个客户端用自身主机名等标识作 slug，就能在发送首个 ping 时"边用边注册"，无需预先在 Web 界面建好全部检查。

需要留意自动创建检查的默认配置（来自 autoprovisioning.md）：

目前无法通过 ping URL 指定自定义周期、宽限期等参数；如需调整，只能去 Web 界面或通过 Management API（见 api.md）修改。此外，自动创建允许临时超出账户检查数上限最多 2 倍（免费账户上限 20 个，付费账户 100 或 1000 个），相关上限判断同样实现在 hc/api/views.py 中。

七、从源码看一次 ping 的完整旅程

为了对上述行为有更底层的把握，最后沿着 hc/api/models.py 的Check.ping()梳理服务端记录一次 ping 的关键步骤（均处于数据库事务中）：

1. 加锁：select_for_update()锁定当前检查行，规避 MariaDB 下并发 ping 的死锁风险；
2. 处理 start 信号：记录last_start与last_start_rid，供后续计算执行时长；
3. 处理成功/失败信号：更新last_ping；若携带的rid（run ID，客户端自行指定的 UUID）与 start 时的rid匹配，则算出last_duration；状态变化时通过create_flip()记录翻转事件；
4. 更新调度状态：重算alert_after（下次应触发告警的时间点），n_pings自增；
5. 落库 Ping 记录：保存远端地址、协议、HTTP 方法、User-Agent（超 200 字符截断）、请求体（超 100 字节且配 S3 时转存对象存储）、rid与exitstatus；
6. 定期清理：每收到 100 次 ping 触发一次prune()，按账户的ping_log_limit清理过期 ping 与通知记录。

由此可以确认一个事实：/{exit-status}、rid、create=1等能力不是简单的 URL 转发，而是完整落库的监控语义——这也是 healthchecks 在"脚本化监控"上保持简洁接口与扎实实现的原因。配套可继续阅读 http_api.md 了解 start / fail / log / exit-status 各端点及rid参数的完整规范，以及 configuring_checks.md 了解检查周期、宽限期与告警语义的配置方式。

• 后端
• 任务调度