NetworkTool/docs/09-使用说明与故障处理.md

使用说明与故障处理

1. 适用范围

本文面向现场使用人员，用于说明如何通过 Windows 客户端连接 Ubuntu 24 设备，并配置 Linux 网口参数。

适用前提：

1. Linux 设备运行 Ubuntu 24。
2. Linux 网络由 netplan 管理。
3. Linux 端已在准备直连 Windows 的网卡上提前配置 169.254.x.x/16 地址，例如 169.254.100.2/16。
4. Windows 电脑通过网线直接连接到这块 Linux 网卡，能访问设备的 169.254.x.x 维护地址。
5. 设备端 Server 已部署并运行。

默认通信参数：

项目	默认值
设备维护 IP	169.254.100.2/16
Windows 维护网段	169.254.x.x/16
HTTP 端口	48888
UDP 发现端口	50000
默认管理密码	hvAC2026#%

2. 使用前准备

2.1 硬件连接

1. 用网线将 Windows 电脑有线网口直接连接到 Linux 端已配置 169.254.x.x/16 的网卡。
2. 确认 Windows 网口和设备网口有链路灯。
3. 如果经过交换机连接，确认交换机端口正常。

2.2 直连维护地址

Linux 端需要提前在准备直连 Windows 的网卡上配置 169.254.x.x/16 地址。默认建议使用：

项目	值
Linux 维护 IP	169.254.100.2
子网掩码	255.255.0.0
默认网关	留空
DNS	留空

Windows 客户端会从当前选中的网卡 IP 发起 UDP 发现和 HTTP 连接。该网卡必须有可用 IPv4，并且需要能访问设备返回的 169.254.x.x 维护地址。

Windows 网卡地址可以由系统自动生成链路本地地址，也可以手工配置。手工配置不是必需步骤，只在自动地址不可用或排查连接问题时使用。

可选手工配置 Windows 有线网卡：

项目	值
IP 地址	169.254.100.1
子网掩码	255.255.0.0
默认网关	留空
DNS	留空

2.3 启动 Linux Server

在 Ubuntu 设备上启动 Server：

sudo /home/x/nettool-server

如需后台运行，可使用：

sudo nohup /home/x/nettool-server >/home/x/nettool-server-run.log 2>&1 < /dev/null &

注意事项：

1. 必须使用 sudo 启动，否则无法写入 netplan、执行 netplan apply、重启或关机。
2. 启动参数都是可选项，不填写时使用默认值。
3. --ip 可选，用于指定维护地址；填写时必须是 169.254.0.0/16 范围内的 IPv4 地址。
4. --port 可选，用于指定 HTTP 端口，默认 48888。
5. --password 可选，用于指定管理密码，默认 hvAC2026#%。
6. 如果启动时修改了 --password，Windows 客户端连接时必须填写相同密码。
7. 如果启动时指定了 --ip，该地址需要已存在于 Linux 网口上，否则客户端无法通过该地址连接 Server。

3. 正常操作流程

3.1 打开 Windows 客户端

运行 NetTool.Client.exe。

主窗口标题栏会显示客户端版本号，例如：

NetTool 2026.05.15.1134

该版本号用于确认现场使用的客户端是否为最新版本。

3.2 选择本机网卡

在主窗口“本机网卡”下拉框中选择与 Linux 维护网卡直连的 Windows 有线网卡。

说明：

1. 默认勾选“仅显示可用网卡”。
2. 可用网卡要求已连接网线并且存在 IPv4 地址。
3. 如果列表为空，可取消“仅显示可用网卡”，或点击“刷新”。

3.3 搜索设备

选择网卡后，客户端会自动搜索设备。

也可以点击“重新搜索设备”手动重新搜索。

搜索成功后，设备列表会显示：

1. IP。
2. 主机名。
3. MAC 地址。

3.4 连接设备

在“发现设备（双击连接）”列表中双击目标设备 IP。

客户端会要求输入管理密码。默认密码为：

hvAC2026#%

连接成功后会打开“设备信息与网口配置”窗口。

3.5 查看设备与网口配置

设备详情窗口会自动读取设备信息和所有 Linux 网口配置。

窗口标题栏会显示：

1. 设备主机名。
2. 设备维护 IP。
3. Server 版本号。

每个网口区域会显示：

1. 逻辑标识，例如 LAN1、LAN2。
2. Linux 真实接口名，例如 eno1、enp1s0。
3. 链路状态。
4. 当前 IP、网关、路由和 DNS 配置。

说明：

1. LAN1、LAN2 只是界面逻辑标识。
2. 实际写入 Linux 的是 eno1、enp1s0 等真实接口名。
3. 修改前应确认目标网口，避免误改当前管理连接所在的真实接口。

3.6 修改网口配置

每个网口都可以单独设置以下内容：

1. 是否启用 DHCP 自动获取 IPv4 配置。
2. 静态 IP 地址和子网掩码。
3. 默认网关。
4. 自定义路由。
5. DNS 地址。

静态配置时，可通过“+ 添加 IP”“+ 添加路由”“+ 添加 DNS”增加多行配置，也可以删除已有行。

使用建议：

1. 业务网口通常配置静态 IP。
2. 不需要默认网关的网口不要启用默认网关。
3. 当前规则不允许多个网口同时配置默认网关。
4. 当前管理连接所在接口应保留 169.254.100.2/16，避免失去管理通道。

3.7 校验配置

修改完成后点击“校验”。

校验通过后，界面会提示可以保存配置。

校验失败时，按提示修改输入内容后重新点击“校验”。

常见校验规则：

1. 静态模式下至少需要一个 IP 地址。
2. IP、网关、DNS 必须是合法 IPv4。
3. 子网掩码必须合法。
4. 静态 IP 不能是所在网段的网络地址或广播地址。
5. 默认网关必须与对应网口 IP 在同一网段。
6. 单个接口最多只能有一条默认路由。
7. 所有网口中最多只能配置一个默认网关。

3.8 保存配置

校验通过后点击“保存配置”。

客户端会弹出确认窗口，显示将要保存的配置。确认无误后继续。

保存过程：

1. Server 备份当前 netplan 配置。
2. Server 写入新的 netplan 配置。
3. Server 执行 netplan apply。
4. 客户端等待任务完成。
5. 保存成功后 Server 保留新配置。
6. 失败时 Server 自动回滚到之前配置。

保存期间不要关闭客户端窗口，也不要断开网线。

3.9 重新获取配置

如需重新读取设备当前配置，点击“重新获取”。

如果当前有未保存修改，客户端会提示确认。继续后，未保存修改会被远端当前配置覆盖。

3.10 重启或关闭设备

设备详情窗口底部提供高级操作：

1. “重启设备”。
2. “关闭设备”。

执行后设备可能立即断开连接。

注意：这些操作要求 Server 以 sudo 启动。

4. 常见报错与处理方法

现象或提示	可能原因	处理方法
本机网卡列表为空	没有可用有线网卡；默认只显示可用网卡；网卡无 IPv4	点击“刷新”；取消“仅显示可用网卡”；检查 Windows 网卡是否启用并配置 IPv4
当前网卡未检测到链路，请检查网线连接	网线未连接；选错网卡；设备或交换机端口未连接	检查网线、网口灯和所选网卡；更换网线或端口后点击“刷新”
当前网卡没有可用 IPv4，无法搜索设备	Windows 网卡没有 IPv4 地址	给该网卡配置 169.254.100.1/16，或检查 Windows 网络设置
未发现 169.254 开头的设备 IP	Server 未运行；Windows 选错网卡；设备维护地址不对；UDP 被防火墙拦截	确认选择与 Linux 维护网卡直连的 Windows 网卡；检查 Linux Server；检查设备是否有 169.254.100.2/16；临时关闭防火墙验证
双击设备后连接失败	HTTP 端口不通；Server 未监听；密码错误；本机路由不正确	检查 48888 端口；确认密码；确认 Windows 使用当前网卡访问设备维护 IP
密码错误	客户端输入密码与 Server 启动参数不一致	确认 Server 的 --password 参数，重新输入密码
HTTP 健康检查返回状态码 401	缺少密码或密码错误	重新输入正确密码
HTTP 健康检查返回状态码 403	权限不足或 Server 拒绝执行对应操作	对配置保存、重启、关机类操作，确认 Server 使用 sudo 启动
设备已连接，但暂时无法读取 Linux 网口列表	Server 执行系统命令失败；系统权限不足；Linux 网络状态异常	确认 Server 以 sudo 启动；查看 Server 日志；在 Linux 上执行 ip addr 检查网口
读取全部网口配置失败	Server 不支持批量读取接口；HTTP 连接失败；读取网口列表失败	确认 Server 已更新并运行；检查端口和网络连接；查看 Server 日志
读取目标网口配置失败	批量读取中该接口读取 netplan 失败；Server 内部错误	点击“重新获取”；查看 Server 日志和 /etc/netplan 文件
网口配置不能为空	客户端没有读取到任何可提交的网口配置	点击“重新获取”；确认 Server 可读取 Linux 网口列表
IP 地址不能为空	静态模式下没有填写 IP	填写 IP 地址，或勾选 DHCP
子网掩码格式不正确	子网掩码不是合法掩码	使用 255.255.255.0、255.255.0.0 等合法掩码
网关格式不正确	默认网关或路由网关不是合法 IPv4	修正网关地址，或不需要网关时取消启用
DNS 格式不正确	DNS 地址不是合法 IPv4	修正 DNS 地址，或删除该 DNS 行
配置校验失败：目标接口不存在	提交的接口名不是当前 Linux 真实接口名	点击“重新获取”，使用界面显示的真实接口名
配置校验失败：网关与目标接口 IP 不在同一子网	网关地址填写到了其他网段	修改网关，使其与目标 IP 在同一网段；不需要网关时留空
多个网口同时配置默认网关	当前规则最多允许一个默认网关	只保留一个默认网关，其余网口取消默认网关或改为自定义路由
提交配置任务失败：Server 未以 root 身份运行	Server 没有 root 权限	使用 sudo 重新启动 Server
应用 netplan 失败，已自动回滚	新配置导致 netplan apply 失败	查看错误信息和 Server 日志，修正 IP、网关、路由或 netplan 文件后重试
配置保存失败，已自动回滚	保存后确认失败；连接中断；Server 判定配置不可保留	重新连接设备，检查配置后重新保存
任务轮询超时	保存任务耗时过长；网络短暂中断；Server 无响应	等待后点击“重新获取”；检查 Server 日志；必要时重新连接
重启或关闭设备失败	Server 未以 root 身份运行；系统命令执行失败	使用 sudo 重新启动 Server；查看 Server 日志

5. 现场排查命令

5.1 Linux 检查 Server 进程

ps -ef | grep nettool-server

5.2 Linux 检查端口监听

ss -ltnp | grep 48888
ss -lunp | grep 50000

期望 HTTP 监听中能看到 48888。

5.3 Linux 检查网口地址和路由

ip addr
ip route

确认当前管理连接所在接口存在 169.254.100.2/16。

5.4 Linux 检查 netplan 文件

ls -l /etc/netplan
sudo cat /etc/netplan/*.yaml

5.5 Linux 查看 Server 日志

如果使用本文中的后台启动命令：

tail -n 100 /home/x/nettool-server-run.log

5.6 Windows 测试 HTTP 健康检查

在 PowerShell 中执行：

curl.exe -H "X-Admin-Password: hvAC2026#%" http://169.254.100.2:48888/api/health

正常返回示例：

{
  "code": 0,
  "message": "成功",
  "data": {
    "status": "运行中",
    "server_version": "2026.05.15.1134"
  }
}

5.7 Windows 检查本机 IP

ipconfig

确认连接设备的有线网卡有 169.254.x.x 地址。