NetWatch diagnose CLI 实战：run 有界诊断、coverage 审计与 episode 重放的完整运维姿势

NetWatch diagnose CLI 实战：run 有界诊断、coverage 审计与 episode 重放的完整运维姿势

【免费下载链接】netwatchReal-time network diagnostics in your terminal. One command, zero config, instant visibility.项目地址: https://gitcode.com/gh_mirrors/netwatc/netwatch

NetWatch 是一个运行在终端里的实时网络诊断工具，一条命令、零配置即可获得网络连接的全景视图。除了交互式 TUI，它的netwatch diagnose子命令系列是运维人员的隐藏武器：有界诊断（run）、规则覆盖审计（coverage）和事件重放（episodes/replay），让你把"现在网络有没有问题"变成一条可写进脚本、可回归验证的确定性结论。

一、run 有界诊断：一条命令给出可脚本化的结论

交互式 TUI 回答的是"我现在网络哪里有问题"，而diagnose run回答的是"给我 X 秒时间，告诉我结论"——它按预算采样、跑完规则引擎、打印结果并立即退出，退出码就是接口：

netwatch diagnose run --budget 30s netwatch diagnose run --target api --budget 2m --format json

"无发现"（0）和"没证据"（2）被刻意区分开，这是整个设计里最值得记住的一点：一次什么都没采到的运行不能证明主机健康，如果脚本把"安静"当成健康，就会把一条死掉的链路报告为正常。--target模式下只有该目标自己的探测算数——另一个目标探测成功，不能证明这个目标没问题。

预算接受30s、2m或裸秒数，合法区间为 5s–10m：短于一个探测间隔采不到证据，长于 10 分钟就是会话而不是单次诊断。--format json输出包含规则集大小、采样窗口、覆盖度对象和全部 issue，支持工程师能看到"到底评估了什么"，而不是面对一个空列表瞎猜。

实现细节（退出码判定逻辑）见 src/diagnose/run.rs，--target名称来自config.toml的[[diagnose_targets]]配置。

二、coverage 审计：先弄清哪些诊断规则真的可用

规则引擎再强，如果输入缺失，结论就不成立。diagnose coverage是一条只读、有时限的活体审计：默认采样 10 秒（1–120s 可调），读取现有网络基线但绝不写入，并诚实地报告"不完整"和"仍在途"的输入：

netwatch diagnose coverage --json --seconds 30 > coverage.json netwatch diagnose coverage --json --seconds 65 # 等满 1 分钟 TCP 计数器窗口 netwatch diagnose coverage --json --test ipv6.broken netwatch diagnose coverage --doc # 重新生成规则覆盖文档

每条规则会被标记为 12 种状态之一：ready（就绪）、learning（学习基线中）、not configured、no subjects、not applicable、awaiting test、permission denied、collector failed、stale、not implemented等。例如：

• 一次成功的 TCP 抓取但没有已建立连接 →no subjects（不是"没抓到"，而是"没有对象"）；
• 重传检查需要完整的 1 分钟计数器观测，生命周期累计值不能当速率用；
• ipv6.broken、captive.portal、pmtu.blackhole三条规则需要--test触发三轮独立实验（不加--test的审计绝不开实验，--test时默认窗口为 90 秒）。

--json输出的是本地审计文件（含接口与配置/错误细节），注意它与事件导出是两回事：分享事件录制要走 src/diagnose/export.rs 的脱敏流程。

状态判定与"下一步动作"建议的生成逻辑在 src/diagnose/coverage.rs，--doc生成的规则覆盖文档即 docs/diagnostic-coverage.md——有测试保证它与规则目录永不漂移。

三、episode 重放：事件录制变成回归测试

当引擎开启某个主要问题时，NetWatch 会把**问题前 10 分钟（pre-roll）到最后一个问题关闭后再 10 分钟（post-roll）**的输入帧录成一个 episode，最长 2 小时；另有一天的"安静网络采样"（15 分钟）作为误报率的分母。录制是纯本地的，默认保留 90 天 / 300 MB。

netwatch diagnose episodes # 列出本地事件库 netwatch diagnose replay /path/to/episode.json.gz netwatch diagnose export --since 7d --dry-run

replay的妙处在于：它把录制的输入喂给一个全新的引擎，逐帧对比开出的 issue——录制的本质就是它自己所产生的"回归测试"。如果重放结果与录制不一致，命令直接以错误退出（replay diverged from the recording），这让你可以放心升级版本而不怕诊断结论悄悄漂移。tests/diagnose/corpus/ 里就固定了一个录制集和它必须持续产出的结论清单，作为钉死的验收基线。

隐私友好的导出

export把每个 IP、主机名替换为 keyed 哈希 token（ip4-private:…这类前缀保留地址类别，因为"DNS 在局域网里"本身就是诊断信息），丢弃进程名、自由文本备注和产物路径，原子写入只读权限的压缩包——是假名化而非匿名化，密钥留在本机，任何人拿着包都无法还原身份，也没有任何上传动作。

开启自动录制只需在~/.config/netwatch/config.toml加一行diagnose_record_episodes = true，完整配置示例（目标、探针、实验端点）见 docs/DIAGNOSE.md。

四、运维组合拳：从排障到回归

1. 日常巡检/告警钩子：netwatch diagnose run --budget 2m --format json，按退出码分支——1 是"有事"，2 是"别装没事"；
2. 环境体检：换网络、换内核、容器化部署后先跑diagnose coverage --json，确认关键规则处于 ready 而不是 permission denied；
3. 故障复盘：出问题时的 episode 用replay反复验证；要上报就用export --dry-run先预览脱敏范围。

关键源码与文档速查

• CLI 参数路由与帮助文本：src/cli.rs
• 有界诊断与退出码契约：src/diagnose/run.rs
• 覆盖度状态机：src/diagnose/coverage.rs
• 事件录制与重放：src/diagnose/episode.rs
• 假名化导出：src/diagnose/export.rs
• 官方诊断手册：docs/DIAGNOSE.md · 规则覆盖目录：docs/diagnostic-coverage.md

一句话总结：run 给你一个可以if的判断，coverage 告诉你引擎的眼睛还开了几只，episode 让每次排障都变成下一次的回归测试——这就是终端网络诊断工具从"看一眼"到"管起来"的完整闭环。

【免费下载链接】netwatchReal-time network diagnostics in your terminal. One command, zero config, instant visibility.项目地址: https://gitcode.com/gh_mirrors/netwatc/netwatch