NetworkHealth — 本地网络健康监测工具

English | 简体中文

一个用 Go 编写的轻量 CLI 工具，持续监测本机网络连通性。不仅检测直连是否正常， 还支持检测本地代理（Clash/V2Ray）的节点是否健康——断网或代理故障时自动记录时间， 恢复时记录中断时长，持续运行直到手动停止（Ctrl+C）。

• 双维度检测：直连 TCP 探测公网 DNS 节点 + 经代理访问境外端点，两路独立判断
• 自动发现代理：读取系统代理注册表 / 环境变量 / 端口扫描，自动识别 Clash/V2Ray（含非默认端口）
• 智能诊断：综合双维度状态，区分「整体断网」与「代理节点故障」
• 持久日志：关键事件写入文件并按大小自动轮转，控制台实时输出状态
• 日志级别过滤：-log-level 可按需筛选写入文件的事件类型（全部 / 仅断网与恢复 / 不写文件）
• 自定义 DNS：支持指定 DNS 服务器解析目标主机名（-dns），不影响系统或代理的 DNS
• 零外部依赖：仅使用 Go 标准库，HTTP 代理与 SOCKS5 原生支持

综合直连与代理两个维度交叉判断，本工具能准确区分以下场景（仅做直连检测时会在代理故障时漏报）：

¹ TUN 模式下若 Clash 崩溃，流量回落到物理网卡，国内直连仍可达。

下载预编译二进制（推荐，无需安装 Go）：从 Releases 下载对应平台的压缩包（Windows / macOS 为 .zip，Linux 为 .tar.gz），解压后得到可执行文件。

或从源码构建（需安装 Go 1.26+）：

go install github.com/rnb3ds/networkhealth@latest   # go install（自动放入 PATH）

# 或从源码编译到当前目录
go build -o networkhealth .          # macOS / Linux
go build -o networkhealth.exe .      # Windows

# 运行（自动探测代理）
./networkhealth         # macOS / Linux
.\networkhealth.exe     # Windows（PowerShell 需带 .\ 前缀）

启动后持续检测网络状态，按 Ctrl+C 停止。

检测参数

日志参数

其他

-dns 仅影响本工具对主机名的解析，不修改系统或 Clash 的 DNS 设置。

直连探测（-timeout）与代理探测（-proxy-timeout）使用各自独立的超时。 代理默认 8s 比直连 3s 更长，因为代理请求需经过额外跳转。两个维度并发检测， 每轮耗时为两者超时的最大值而非之和。

代理自动探测（-proxy auto）依次尝试：① 系统代理注册表（读取实际端口）→ ② 代理环境变量 → ③ 常见端口扫描（7890/7891/1080 等）。TUN 模式且未开启系统代理时， 需用 -proxy http://127.0.0.1:<端口> 显式指定。

以下示例以 networkhealth 代指可执行文件名，实际执行时：

• macOS / Linux：./networkhealth
• Windows：networkhealth.exe（PowerShell 中需写 .\networkhealth.exe）

networkhealth                                    # 自动探测代理
networkhealth -proxy off                         # 仅直连检测
networkhealth -proxy http://127.0.0.1:7890       # 指定 Clash HTTP 代理
networkhealth -proxy socks5://127.0.0.1:7891     # 指定 SOCKS5 代理
networkhealth -interval 5s -timeout 2s           # 更快检测（每 5 秒，直连超时 2 秒）
networkhealth -proxy-timeout 10s                 # 放宽代理探测超时（默认 8s）
networkhealth -dns 8.8.8.8                       # 自定义 DNS
networkhealth -log-level outage                  # 日志仅记录断网/恢复事件
networkhealth -max-log-mb 50                     # 日志上限 50MB 后轮转
networkhealth -quiet                             # 后台运行（脱离终端，关闭窗口不停止）
networkhealth -version                           # 查看版本信息

-quiet 模式下程序脱离终端后台运行——关闭 cmd / PowerShell / 终端窗口不会停止进程。 启动时会输出后台进程的 PID 与停止方式：

NetworkHealth dev 已转入后台运行（PID 12345），日志: logs/network_health.log
停止方式: taskkill /PID 12345 /F

后台进程将持续运行，直到手动终止或系统重启（重启后不会自动恢复）。

查找与停止后台进程：

-quiet 模式下控制台无输出，所有检测结果写入日志文件（默认 logs/network_health.log）。

如需开机自动后台运行，可将程序注册为系统服务： Windows「任务计划程序」（触发器选「启动时」，操作指向 networkhealth.exe -quiet）、 Linux systemd unit、macOS launchd plist——均以无窗口方式启动。

-log-level 控制哪些事件写入日志文件（控制台输出不受影响，始终实时显示）：

outage 模式下，日志文件精确记录每次断网的完整生命周期——断网时间、重连时间、中断时长， 不夹杂周期性的「直连正常」心跳行，便于事后排查故障时段。

控制台实时输出：

19:47:58 ● 直连OK 1ms   │ ● 代理OK 221ms
19:48:28 ● 直连OK 2ms   │ ○ 代理断            ← 代理故障
19:48:28 [WARN] ⚠️ 代理节点故障：本机直连正常，但经代理无法访问外网（代理 http://127.0.0.1:7890，断网时间 2026-08-01 19:48:28）
19:48:32 [WARN] ⚠️ 代理仍故障，已持续 4s（断网时间 2026-08-01 19:48:28，直连正常）
19:50:01 [INFO] ✓ 代理已恢复！断网时间 2026-08-01 19:48:28，重连时间 2026-08-01 19:50:01（中断 1m33s，… 延迟 198ms）

日志文件（关键事件，带完整时间戳）：

2026/08/01 19:47:58.101682 [INFO] 网络健康监测已启动（检测间隔 10s；日志级别 all；直连目标 5 个；代理 http://127.0.0.1:7890，目标 3 个）
2026/08/01 19:48:28.429099 [WARN] ⚠️ 代理节点故障：本机直连正常，但经代理无法访问外网（代理 http://127.0.0.1:7890，断网时间 2026-08-01 19:48:28）
2026/08/01 19:48:32.491759 [WARN] ⚠️ 代理仍故障，已持续 4s（断网时间 2026-08-01 19:48:28，直连正常）
2026/08/01 19:50:01.712304 [INFO] ✓ 代理已恢复！断网时间 2026-08-01 19:48:28，重连时间 2026-08-01 19:50:01（中断 1m33s，… 延迟 198ms）

NetworkHealth/
├── main.go                        # CLI 入口与参数解析
├── internal/
│   ├── checker/                   # 直连 TCP 探测 + 代理 HTTP 探测 + 自动发现
│   ├── logger/                    # 文件 + 控制台双路日志（含轮转）
│   └── monitor/                   # 检测循环与双维度状态机
├── .github/workflows/             # CI（三平台）+ 自动发布
└── .goreleaser.yml                # 交叉编译 6 平台 + 打包

MIT 许可证 - 详见 LICENSE 文件。

如果本项目对你有帮助，请给一个 Star! ⭐