# watchdog

**Repository Path**: smart-code-source/watchdog

## Basic Information

- **Project Name**: watchdog
- **Description**: 本机服务 Watchdog
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-05
- **Last Updated**: 2026-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 本机服务 Watchdog

一个 Bash 常驻脚本，适合安装在每台被监控的 Linux 节点上。它每 30 秒检查服务；连续 3 次失败后调用该服务已有的重启脚本。可监控长期运行的 Java、Python、Shell 等服务，不依赖中心服务器。

想先在本机体验，可运行 [Shell worker 与 Python Web 服务示例](examples/README.md)。

## 配置

依赖 Bash 4.3+、`curl`、`flock`、`timeout`、`pgrep`、`sed` 和常见的基础系统命令。无需 logrotate。复制 [`services.conf.example`](services.conf.example) 到 `/etc/watchdog/services.conf`，每行一个服务：

```text
名称|HTTP健康地址|本机TCP端口|进程关键字|重启脚本绝对路径
orders|http://127.0.0.1:8080/health|8080|orders-service|/opt/orders/bin/service.sh
payments||8081|payments-api.py|/opt/payments/bin/service.sh
jobs|||/opt/jobs/bin/worker.sh|/opt/jobs/bin/service.sh
```

- 至少填一种检测条件。只使用最靠前的已配置条件：HTTP、端口、进程。HTTP 检查失败不会改查端口。
- HTTP 使用 GET，只有 2xx 算健康；连接超时 2 秒，总超时 5 秒。端口检查只连接 `127.0.0.1`，超时 3 秒。进程关键字按字面匹配完整命令行，务必选一个只出现在目标服务命令行里的词。
- 重启脚本须可执行，且接受 `restart` 参数。返回码 0 表示命令执行成功；watchdog 仍会在等待期后重新检查健康状态。重启脚本自行管理详细日志，watchdog 只记录命令和结果。
- 字段不能包含 `|`，不要在字段两侧留空格。配置在启动时读取；修改后重启 watchdog。
- 执行完即退出的定时脚本没有常驻进程可供检查，不适合用这里的进程关键字方式监控。

## 安装和启动

把 `watchdog.sh` 安装到 `/opt/watchdog/watchdog.sh` 并赋予执行权限，创建 `/etc/watchdog/services.conf`。运行用户需要能执行各服务的重启脚本，以及写入 `/var/run/watchdog.lock`、`/var/run/watchdog.pid` 和 `/var/log/watchdog.log` 所在目录。建议用专门的有权管理这些服务的用户；以下示例使用 root。

没有 systemd 的节点，可以在 `/etc/rc.d/rc.local` 中加入：

```sh
nohup /opt/watchdog/watchdog.sh >/dev/null 2>&1 </dev/null &
```

确认 `rc.local` 可执行，并按该发行版的方式启用它。手动启动可运行同一条 `nohup` 命令。脚本有单实例锁，重复启动会报错退出。

使用 systemd 的节点，将 [`watchdog.service`](watchdog.service) 安装到 `/etc/systemd/system/watchdog.service`，然后运行：

```sh
systemctl daemon-reload
systemctl enable --now watchdog.service
systemctl status watchdog.service
```

两种启动方式只选一种。`watchdog.service` 中的脚本路径可按实际安装位置修改。watchdog 自己写日志；systemd 的标准输出只用于捕获意外的启动错误。

## 停止、日志与维护

- systemd：`systemctl stop watchdog.service`；查看日志：`tail -F /var/log/watchdog.log`。
- rc.local：确认 `cat /var/run/watchdog.pid` 对应 watchdog 进程后，执行 `kill "$(cat /var/run/watchdog.pid)"`；查看日志：`tail -F /var/log/watchdog.log`。
- 日志记录启动、停止、健康恢复、每次检测失败的原因和重启结果。默认单文件最多 10 MiB，保留当前文件及最多 9 份历史文件（`watchdog.log.1` 至 `.9`），总量约 100 MiB；不压缩。每次写入前轮转，不依赖 logrotate。
- 计划停机前先停止 watchdog，或从配置中移除该服务并重启 watchdog。人工停止的受监控服务会被视为故障并自动重启。

启动后等待 2 分钟才开始检测，给开机中的服务留出时间。重启脚本在后台执行，最长运行 60 秒；执行期间只暂停该服务的检查，其他服务继续检查。脚本结束后，该服务再等待 2 分钟；两次重启至少间隔 5 分钟。停止 watchdog 时，仍在执行的重启脚本也会被终止。

可用环境变量 `WATCHDOG_LOG_FILE`、`WATCHDOG_LOG_MAX_BYTES`、`WATCHDOG_LOG_FILES` 调整日志路径、单文件字节数和包含当前文件在内的总文件数。例如 `WATCHDOG_LOG_MAX_BYTES=10485760 WATCHDOG_LOG_FILES=10 /opt/watchdog/watchdog.sh`。路径所在目录需预先创建且可写；systemd 部署可在单元文件的 `[Service]` 段使用 `Environment=` 设置。

## 本地验证

运行 `python3 -m unittest discover -s tests -v`。测试通过临时配置、模拟 HTTP/端口/进程和短时间参数运行，不修改系统服务。运行时可用 `WATCHDOG_CONFIG`、`WATCHDOG_LOCK_FILE`、`WATCHDOG_PID_FILE`、`WATCHDOG_INTERVAL`、`WATCHDOG_INITIAL_GRACE`、`WATCHDOG_RESTART_GRACE`、`WATCHDOG_RESTART_COOLDOWN`、`WATCHDOG_FAILURE_LIMIT`、`WATCHDOG_RESTART_TIMEOUT` 环境变量覆盖默认值。