# NetPilot 网络调试工具 NetPilot 是一个基于 Python Tkinter 的 Windows 网络调试工具，面向桌面网络排障、网卡配置、局域网设备发现、DNS 对比诊断和连通性测试等场景。 应用采用左侧功能导航、中间功能工作区、右侧公共输出控制台的布局。所有功能页的执行日志、诊断过程、错误提示和摘要都会统一输出到右侧控制台，便于在不同工具之间切换时保留排障上下文。 ## 当前功能 当前界面保留以下功能页： - 网卡配置 - DNS 诊断 - 设备发现 - Ping 探测 - 端口扫描 - 路由追踪 `IP 冲突检测` 和 `环网检测` 功能页已从主界面移除。 ## 功能说明 ### 网卡配置 用于查看本机网卡信息，并对常见 IPv4 / DNS 配置进行调整。 主要能力： - 读取本机启用和禁用的网卡。 - 显示网卡描述、MAC 地址、连接状态、IPv4 地址、子网掩码、默认网关、DNS 等信息。 - 支持启用网卡、禁用网卡。 - 支持 DHCP 自动获取。 - 支持写入静态 IPv4、子网掩码、默认网关、首选 DNS、备用 DNS。 - 支持重新读取网卡信息。 - 支持网卡配置模板保存、套用和删除。 权限说明： 修改网卡状态、IP、网关、DNS、DHCP 等配置通常需要以管理员权限运行程序。 ### DNS 诊断 用于比较本机 DNS 与常用公共 DNS 的解析结果、耗时和异常原因。它能判断“DNS 是否能解析成功”，但不等同于判断目标主机一定能 Ping 通。 主要能力： - 只读取活动网卡用于 DNS 诊断。 - 自动读取当前网卡 DNS。 - 支持手动填写 DNS 服务器。 - 支持自动补全常用 DNS。 - 支持多个域名批量测试。 - 支持 A、AAAA、CNAME、MX、TXT、NS 等记录类型。 - 支持设置重复次数和超时时间。 - 对不同 DNS 服务器的解析结果、耗时、失败原因进行对比。 - 诊断结果以表格展示。 - 支持复制诊断摘要。 - 支持导出 CSV。 - 支持“修复异常”，可将指定网卡 DNS 设置为常用 DNS 并刷新 DNS 缓存。 注意事项： - 域名 A 记录能解析成功，只代表 DNS 返回了 IP。 - Ping 不通可能是目标服务器禁 Ping、防火墙拦截、路由不可达、运营商策略、目标只开放 TCP/HTTPS、不响应 ICMP 等原因。 - DNS 诊断负责解析层排查，连通性需要结合 Ping 探测、端口扫描、路由追踪继续判断。 ### 设备发现 用于按所选网卡的配置网段发现局域网内在线或 ARP 可见设备。 主要能力： - 按当前网卡 IPv4 和子网掩码自动生成扫描范围。 - 通过 Ping 探活发现在线设备。 - 结合 ARP 信息补充 MAC 地址和 ARP 可见设备。 - 展示 IP、MAC、厂商、来源网卡、延迟、发现方式和备注。 - 支持刷新网卡、自动范围、开始发现、停止发现。 - 支持复制设备清单。 - 支持导出 CSV。 当前扫描边界： - 只按所选网卡的配置网段扫描。 - 不跨网段扫描。 - 不使用邻居表扩展跨网段目标。 - 不解析主机名。 - 目标设备如果禁用 ICMP Echo，可能无法通过 Ping 发现，但如果本机 ARP 表中可见，仍可能以 ARP 可见方式显示。 #### 厂商识别和 OUI 数据库 设备发现里的“厂商”列基于 MAC 地址前缀匹配 OUI 厂商库。 加载优先级： 1. `%LOCALAPPDATA%\NetPilot\oui_vendors.json` 2. 程序内置的 `assets/oui_vendors_seed.json` 3. 代码内的小型兜底表 更新策略： - 程序启动后会在后台检查 OUI 缓存是否过期。 - 默认缓存超过 7 天后尝试联网更新。 - 更新成功后写入 `%LOCALAPPDATA%\NetPilot\oui_vendors.json`。 - 更新失败不会阻塞扫描，只会在右侧输出控制台提示。 识别规则： - 优先匹配 36 bit 前缀。 - 其次匹配 28 bit 前缀。 - 最后匹配 24 bit 前缀。 - 本地管理地址或随机 MAC 会显示为“随机/本地管理地址”。 - 没有命中的 MAC 显示为“未知”。 ### Ping 探测 用于检查一个或多个目标的 ICMP 连通性和延迟质量。 主要能力： - 支持单目标 Ping。 - 支持批量 Ping。 - 批量目标支持 CIDR、IP 范围和多行列表。 - 支持指定次数、持续探测、间隔、超时、包大小、TTL、禁止分片。 - 支持选择本地源 IP。 - 实时输出探测过程。 - 统计丢包率、平均延迟、抖动和质量状态。 - 支持导入目标。 - 支持导出 CSV。 注意事项： Ping 依赖 ICMP。目标设备禁 Ping 时，Ping 失败不一定代表 TCP 服务不可用。 ### 端口扫描 用于检查 TCP 端口连通性，适合判断服务是否开放。 主要能力： - 支持单主机单端口测试。 - 支持端口列表、端口范围和常用端口预设。 - 支持批量主机扫描。 - 批量目标支持 CIDR、IP 范围和多行列表。 - 支持并发数、超时、仅显示开放端口。 - 支持服务名识别。 - 支持可选 Banner 探测。 - 结果表格展示主机、解析 IP、端口、服务、状态、耗时、错误等信息。 - 支持复制开放端口。 - 支持导出 CSV。 注意事项： 端口扫描只判断 TCP 连接层结果。服务协议是否正常，还需要结合业务客户端或协议工具进一步确认。 ### 路由追踪 用于查看到目标地址的逐跳路径和延迟情况。 主要能力： - 支持 IPv4 / IPv6。 - 支持单次追踪、指定次数追踪和持续追踪。 - 支持最大跳数、单跳超时、高延迟阈值等参数。 - 展示每一跳 IP、探测耗时、平均延迟、抖动和状态。 - 保留原始命令输出。 - 对超时、高延迟、波动等情况生成诊断摘要。 - 支持复制摘要。 - 支持导出 CSV。 注意事项： 部分路由节点会屏蔽 ICMP 或限制 TTL Exceeded 响应，因此某些跳点超时不一定代表链路中断。应重点关注最后目标是否可达，以及连续多跳异常的位置。 ## 界面布局 - 左侧：功能导航区。 - 中间：当前功能页的参数、操作按钮和结果列表。 - 右侧：公共输出控制台，所有功能页共用。 - 底部：状态栏，显示当前状态、本机名、操作系统和权限状态。 公共输出控制台用于查看执行过程、错误提示、更新信息和诊断摘要。点击“清空”可以清除当前控制台内容。 ## 运行环境 建议环境： - 操作系统：Windows 10 / Windows 11 - Python：Python 3.10 或更高版本 - UI 框架：Tkinter - 系统依赖：PowerShell、Windows 网络相关命令 项目主要调用 Windows 系统命令获取网络信息，例如： - `Get-NetAdapter` - `Get-NetIPConfiguration` - `netsh` - `ipconfig` - `arp` - `ping` - `tracert` ## 权限说明 普通权限可以运行大部分只读诊断功能。 以下操作建议使用管理员权限： - 启用网卡 - 禁用网卡 - 修改 IP 地址 - 修改子网掩码 - 修改默认网关 - 修改 DNS - 切换 DHCP - 执行 DNS 修复 如果按钮不可用或操作失败，优先确认程序是否以管理员身份运行。 ## 源码运行 在项目根目录执行： ```powershell python main.py ``` 如果需要管理员权限，可以打开管理员 PowerShell 后执行： ```powershell cd E:\Git\Network-tools python main.py ``` ## 打包 项目提供 Windows 打包脚本： ```powershell .\打包.bat ``` 打包完成后，输出文件位于： ```text dist\NetworkTool.exe ``` 打包脚本会将 OUI 离线厂商库一并打入程序： ```text assets\oui_vendors_seed.json ``` 这样即使目标电脑没有互联网，设备发现功能也可以使用内置 OUI 种子库识别常见厂商。 ## 目录结构 ```text Network-tools ├─ assets │ └─ oui_vendors_seed.json # 内置 OUI 厂商种子库 ├─ core │ ├─ Function # 网络检测和配置业务逻辑 │ └─ ui # Tkinter 界面、主题和功能页 ├─ main.py # 程序入口 ├─ 打包.bat # PyInstaller 打包脚本 ├─ NetworkTool.spec # PyInstaller 配置 └─ README.md ``` ## 本地文件 程序运行过程中可能产生以下本地文件： - `%LOCALAPPDATA%\NetPilot\oui_vendors.json`：联网更新后的 OUI 厂商缓存。 - `network_profiles.json`：网卡配置模板，保存位置为程序运行目录。 - CSV 导出文件：由用户在导出时选择保存路径。 程序不会主动上传网络检测结果。诊断、缓存和导出均在本机完成。 ## 常见问题 ### 为什么修改网卡配置失败？ 请确认程序以管理员权限运行。Windows 对网卡启用/禁用、IP 配置、DNS 配置等操作有权限限制。 ### 为什么 DNS 能解析成功，但 Ping 不通？ DNS 解析成功只说明域名能转换成 IP。Ping 依赖 ICMP，目标服务器可能禁用了 ICMP，或者链路中有防火墙、运营商策略、路由策略阻止 ICMP。 排查建议： - 用 DNS 诊断确认解析结果是否正常。 - 用 Ping 探测确认 ICMP 是否可达。 - 用端口扫描测试目标业务端口，例如 80、443、3389、502 等。 - 用路由追踪查看路径中是否存在连续超时或高延迟跳点。 ### 为什么设备发现扫不到某些设备？ 常见原因包括： - 目标设备禁用了 ICMP Echo 响应。 - 目标设备不在当前网卡配置网段内。 - 本机防火墙或安全软件限制了探测行为。 - 交换机、VLAN、无线隔离或终端防火墙阻止了局域网发现。 - 目标设备未产生可见 ARP 信息。 - 当前选择的网卡不是实际通信所用网卡。 当前设备发现只按所选网卡的配置网段扫描，不跨网段，也不解析主机名。 ### 为什么厂商显示“未知”？ 可能原因： - MAC 地址为空。 - MAC 地址是随机地址或本地管理地址。 - OUI 厂商库中没有该前缀。 - 本地缓存损坏且离线种子库未正确打包。 - 设备使用了虚拟网卡、代理网关或桥接设备暴露的 MAC。 可以查看右侧输出控制台，确认是否出现 OUI 厂商库加载或更新提示。 ### 为什么部分手机显示“随机/本地管理地址”？ 很多手机系统会默认开启随机 MAC 或私有 Wi-Fi 地址。此时 MAC 前缀不是厂商真实注册地址，无法通过 OUI 准确识别手机品牌。 ### 为什么 DNS 诊断的网卡数量和系统里看到的不一样？ DNS 诊断只使用活动网卡。禁用网卡、隐藏适配器、隧道网卡、部分虚拟网卡即使能在系统里看到，也可能不会进入 DNS 诊断列表。 ### 为什么部分按钮是灰色不可用？ 按钮状态会根据当前任务状态、网卡状态和输入内容变化。例如任务运行中会禁用开始按钮；未选择有效网卡、缺少目标、当前状态不支持某项操作时，也会禁用对应按钮。 ### 导出的 CSV 用 Excel 打开乱码怎么办？ 建议使用 Excel 的“数据 -> 自文本/CSV”导入方式，并选择 UTF-8 编码。也可以先用支持 UTF-8 的编辑器检查文件内容。 ## 开发说明 界面层主要位于 `core/ui`： - `ui_main.py`：主窗口布局、侧边栏、公共输出控制台、页面切换。 - `theme.py`：全局颜色、字体、ttk 样式。 - `components.py`：公共 Page、Console、字段、按钮等组件。 - `tab_network.py`：网卡配置页。 - `tab_dns.py`：DNS 诊断页。 - `tab_device_discovery.py`：设备发现页。 - `tab_ping.py`：Ping 探测页。 - `tab_telnet.py`：端口扫描页。 - `tab_tracert.py`：路由追踪页。 业务逻辑主要位于 `core/Function`： - `network_fun.py`：网卡读取、启用、禁用和配置写入。 - `dns_diag_fun.py`：DNS 解析诊断、摘要和导出。 - `device_discovery_fun.py`：设备发现、ARP 补充、结果整理和导出。 - `oui_lookup.py`：OUI 厂商库加载、查询和联网更新。 - `ping_fun.py`：Ping 探测。 - `telnet_fun.py`：TCP 连通性和端口扫描。 - `tracert_fun.py`：路由追踪。 开发时建议先执行编译检查： ```powershell python -m compileall main.py core ``` 再启动界面进行手动验证： ```powershell python main.py ``` ## 验证重点 改动功能后建议重点验证： - 主界面是否能正常启动。 - 左侧导航是否只显示当前保留的功能页。 - 公共输出控制台是否能接收各页面日志。 - 网卡配置是否能正确读取启用和禁用网卡。 - DNS 诊断是否只列出活动网卡。 - 设备发现是否能根据所选网卡生成正确扫描范围。 - OUI 厂商库是否能加载缓存或离线种子库。 - 各结果列表是否无横向滚动条，且关键列内容可见。 - 打包后的 `dist\NetworkTool.exe` 是否能在无网络环境下启动并读取内置 OUI 种子库。