systemd watchdog 监测服务心跳的配置方法

我第一次给常驻服务补心跳保护时，遇到的误区是：进程还在，就以为服务健康。实际上线程可能死锁、事件循环可能卡住，systemd 看到的 PID 却仍然存活。服务级 watchdog 的正确做法，是在 unit 中设置 WatchdogSec=，再由主进程完成关键工作后定期发送 WATCHDOG=1。一旦两次通知间隔超过阈值，systemd 会把服务判为 watchdog 失败；配合 Restart=on-watchdog，才形成“检测假死并恢复”的闭环。

本文依据的官方说明地址是 https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html 与 https://www.freedesktop.org/software/systemd/man/latest/sd_watchdog_enabled.html。先给结论：心跳建议按 systemd 下发超时时间的一半发送，并且只能在服务确实还能推进工作时发送，不能让一个无条件定时器替业务线程报平安。

先分清 unit、主进程和通知套接字的职责

WatchdogSec= 启用的是 systemd 与服务之间的协议。服务启动完成后，管理器开始计时，并通过环境变量 WATCHDOG_USEC 把微秒级超时值交给进程；WATCHDOG_PID 则用于限定预期发送者。主进程通过 systemd 的通知套接字发送 WATCHDOG=1，管理器收到后重置计时器。

这里最关键的根因判断是：watchdog 检测的不是“进程是否存在”，而是“服务是否仍能在期限内证明自己有进展”。因此，我会把心跳放在主事件循环完成一次健康检查、成功处理队列或刷新关键状态之后，而不是另起一个永远能醒来的线程盲目发送。后者会让业务线程已经卡死的服务继续显示健康。

unit 文件这样配置

下面是一份可作为起点的 unit。Type=notify 便于服务用 READY=1 明确报告初始化完成；真正启用 watchdog 的仍是 WatchdogSec=，不要把两者混为一谈。

# /etc/systemd/system/example.service
[Unit]
# 服务说明以及需要先完成的网络目标
Description=Example heartbeat service
After=network-online.target

[Service]
# 主进程会通过 sd_notify 报告 READY 和 WATCHDOG
Type=notify
ExecStart=/usr/local/bin/example-service
# 30 秒未收到心跳就判为 watchdog 失败
WatchdogSec=30s
# 只在 watchdog 失败时自动重启
Restart=on-watchdog
# 避免连续失败时立即形成快速重启风暴
RestartSec=5s
# 明确只接受主进程的通知
NotifyAccess=main

[Install]
# 随常规多用户目标启动
WantedBy=multi-user.target

超时后，服务会进入 failed 状态，systemd 默认使用 SIGABRT 终止它，也可通过 WatchdogSignal= 调整信号。随后是否重启由 Restart= 决定；如果只想覆盖 watchdog，on-watchdog 比宽泛的 on-failure 更容易解释。

主循环按下发时间的一半发送心跳

程序不要把 30 秒硬编码两遍。sd_watchdog_enabled() 会判断管理器是否要求当前进程发送心跳，并返回 WATCHDOG_USEC。以下 C 代码保留了最重要的契约：仅在一轮业务工作成功后发送心跳。

#include 
#include 
#include 

int main(void) {
    uint64_t watchdog_usec = 0;
    /* 返回值大于 0 表示当前进程需要发送 watchdog 心跳。 */
    int enabled = sd_watchdog_enabled(0, &watchdog_usec);

    /* 初始化成功后报告 READY；失败分支应直接退出并让 systemd 记录结果。 */
    sd_notify(0, "READY=1");

    for (;;) {
        /* 这里代表一轮真实业务工作；只有成功推进状态才允许报心跳。 */
        int work_ok = do_one_round_of_work();
        if (work_ok  0) {
            /* 使用超时时间的一半，给调度抖动和短暂阻塞留下余量。 */
            sd_notify(0, "WATCHDOG=1");
            usleep(watchdog_usec / 2);
        } else {
            /* 未启用 watchdog 时也避免空转。 */
            sleep(1);
        }
    }
}

真实项目中还应使用单调时钟安排下一次发送，避免每轮处理耗时叠加后逐渐漂移。如果业务工作可能持续很久，就把“仍有进展”的判断设计成可观测检查，而不是在工作开始前先报心跳。

重载后先检查属性，再看失败结果

修改 unit 后，我会先重载并读取 systemd 实际采用的属性，而不是只检查文件内容。

# 让 systemd 重新读取 unit，并启动最新配置
sudo systemctl daemon-reload
sudo systemctl restart example.service

# 查看 watchdog 是否生效，以及当前服务状态和最近一次心跳时间
systemctl show example.service \
  -p ActiveState -p SubState -p Result \
  -p WatchdogUSec -p WatchdogTimestampMonotonic

# 从本次启动开始查看服务日志和 watchdog 失败线索
journalctl -u example.service -b --no-pager

如果 WatchdogUSec=0，优先检查 unit 是否重载、配置是否落在 [Service] 段，以及当前启动的是否是同名模板实例。若超时后看到 Result=watchdog 但没有重启，再检查 Restart= 和启动限速。StartLimitIntervalSec=、StartLimitBurst= 会阻止持续故障无限重启，这是保护机制，不是 watchdog 失效。

两个最容易踩的边界

第一，设置 WatchdogSec= 而未显式配置 NotifyAccess= 时，systemd 会把通知访问范围隐式设为 main。如果由辅助进程发送心跳，它的通知可能不被接受；即使放宽到 NotifyAccess=all，短命辅助进程的通知归属也可能难以确认。更稳妥的设计仍是让主进程发送。

第二，WatchdogSec= 是服务级软件 watchdog；systemd-system.conf 中的 RuntimeWatchdogSec= 面向硬件 watchdog，用于监督系统管理器乃至整台机器。两者解决的问题不同，不要为了服务假死直接去改硬件 watchdog。

常见问题

只写 WatchdogSec，服务会自动发心跳吗？

不会。它只让 systemd 开始等待通知，服务仍需通过 sd_notify 或等价接口主动发送 WATCHDOG=1。

心跳间隔必须恰好是超时的一半吗？

一半是官方接口说明中的推荐值，目的是为调度延迟留余量。程序应读取 WATCHDOG_USEC 计算，而不是复制 unit 里的固定秒数。

为什么进程没退出，systemd 仍然重启了服务？

因为 watchdog 监测的是通知期限。主进程仍在但没有按时发送有效心跳时，systemd 会按 watchdog 失败处理并执行配置的重启策略。