# 使用说明与故障处理

## 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：

```bash
sudo /home/x/nettool-server
```

如需后台运行，可使用：

```bash
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`。

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

```text
NetTool 2026.05.15.1134
```

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

### 3.2 选择本机网卡

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

说明：

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

### 3.3 搜索设备

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

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

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

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

### 3.4 连接设备

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

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

```text
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. 所有网口中最多只能配置一个默认网关。
8. 自定义路由目标必须填写目标网段地址（网络号），例如 `192.168.50.0/24` 合法，`192.168.50.0/16` 应写为 `192.168.0.0/16`。

### 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 进程

```bash
ps -ef | grep nettool-server
```

### 5.2 Linux 检查端口监听

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

期望 HTTP 监听中能看到 `48888`。

### 5.3 Linux 检查网口地址和路由

```bash
ip addr
ip route
```

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

### 5.4 Linux 检查 netplan 文件

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

### 5.5 Linux 查看 Server 日志

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

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

### 5.6 Windows 测试 HTTP 健康检查

在 PowerShell 中执行：

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

正常返回示例：

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

### 5.7 Windows 检查本机 IP

```powershell
ipconfig
```

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