企业官网建设流程全解析

NetWatch doctor命令教程：只读体检报告+JSON能力矩阵，一键排查权限与抓包环境

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

NetWatch 是一款在终端里运行的实时网络诊断工具，而它的doctor子命令是排查抓包环境最快的"体检入口"：一条命令、零配置，就能输出一份只读体检报告和可解析的JSON 能力矩阵，帮你一键确认抓包库、网卡、沙箱权限到底哪里出了问题。本教程面向新手，带你 3 步跑通netwatch doctor。

为什么先跑一次 doctor？

NetWatch 依赖 libpcap / Npcap 等抓包后端，不同系统（Linux、macOS、Windows）的权限差异很大。在启动交互界面之前先跑一次体检，可以提前发现：

• 抓包库是否就位：Linux/macOS 检查 libpcap 链接状态，Windows 在初始化 Npcap 之前先检查标准 DLL 安装路径；
• 配置文件是否健康：缺失或格式错误的配置会被明确报告，但不会回显损坏内容与端点凭据；
• 远程/指标功能开关：只检测环境变量是否存在，不启动监听、不发出任何网络请求。

doctor的核心承诺是纯只读——它不启动采集器、不发送探测、不联系任何端点、不检查或恢复日志、不创建状态目录、也绝不修改你的配置。可以放心在 CI 或生产机器上运行。

三步上手：doctor 命令速查

从源码编译的项目中，可以用cargo run -- doctor --json等效执行。普通文本输出按 80 列终端换行、不依赖颜色，适合贴进工单。

体检报告怎么读：六种能力状态

JSON 报告中每个能力（capability）包含id、state、reason、detail和可选的next_check字段。reason是机器可读码，detail是给人类看的解释，next_check直接告诉你下一步该跑什么命令。状态共 6 种：

常见能力项包括config（配置）、interface（抓包网卡）、capture_library（抓包库）、remote/metrics（远程与指标开关）、resolver（DNS 修复权限）。一个重要的设计原则：某功能被启用，不代表其后端真的可用——以doctor报告的状态为准。

JSON 能力矩阵：字段说明

netwatch doctor --json的输出遵循版本化契约，顶层字段包括：

• schema_version: 1：契约版本，便于脚本做兼容判断；
• scope：static（纯静态体检）或capture_check（含抓包实测）；
• platform/interface：平台与选定网卡；
• capabilities：能力矩阵数组；
• protections：沙箱保护详情（Landlock ABI、丢弃/保留的能力等）；
• network_restricted：网络受限标志；
• attribution_coverage：在 doctor 报告中恒为null，只有运行时快照才包含实测覆盖。

{ "schema_version": 1, "scope": "static", "platform": "linux", "capabilities": [ { "id": "config", "state": "ready", "reason": "defaults", "detail": "No saved configuration; defaults shown" } ] }

一个实用的退出码契约：体检完成即正常退出（exit 0），即使某些能力不可用——脚本只需解析 JSON 中的state自行判定，而非法参数或致命错误才会以非零码退出。这让doctor天然适合接入 CI 做环境准入检查。

进阶：--check-capture 的 5 秒限时抓包测试

--check-capture会真正走一遍抓包路径：选定网卡（配置的、自动选择的，或用--interface指定），按已配置的 BPF 过滤器打开并配置抓包，然后立即关闭、不读取任何数据包。

需要注意它的边界：

• 父进程给检查子进程5 秒超时，超时即强杀清理；
• 它可能临时启用混杂模式，需要抓包权限；
• 它只证明这个隔离检查进程的沙箱执行情况，不代表实时 worker 的强制效果，也不代表能收到数据包或进程归因正常；
• 全程不发起探测、不产生云调用。

静态体检 ≠ 网络健康

最后澄清一个常见误区：doctor是某一时刻的环境观察，不是健康裁决。抓包后端就绪、探测完成，都不等于网络本身健康；静态配置永远不会替代运行时的真实观察。NetWatch 的实时 Settings 视图与启动流程使用同一套能力模型，但附加了真实抓包、进程归因、探测完成度等运行时观察——想看持续状态，请进 TUI 按,打开 Settings（截图所示），doctor报告则负责启动前的一次性把关。

相关文档与源码

• 官方文档：docs/doctor.md —— 输出契约与验证范围的完整说明
• 能力矩阵：docs/CAPABILITIES.md —— 三大平台能力对照表与限制
• 能力模型实现：src/runtime/capabilities.rs
• 命令解析入口：src/cli.rs

掌握netwatch doctor，你就有了一张随取随用的权限与抓包环境诊断卡：新手用它快速定位"为什么抓不到包"，运维用它把环境检查写进自动化流水线。

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