386 lines
13 KiB
Markdown
386 lines
13 KiB
Markdown
# 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 种子库。
|