docs: 新增使用说明与故障处理文档

补充 Windows 客户端连接 Ubuntu 设备的操作指南及常见问题排查方案。

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

@@ -0,0 +1,318 @@
+# 使用说明与故障处理
+
+## 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` |
+| 默认管理密码 | `Dt123$` |
+
+## 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/networktool-server
+```
+
+如需后台运行，可使用：
+
+```bash
+sudo nohup /home/x/networktool-server >/home/x/networktool-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` 可选，用于指定管理密码，默认 `Dt123$`。
+6. 如果启动时修改了 `--password`，Windows 客户端连接时必须填写相同密码。
+7. 如果启动时指定了 `--ip`，该地址需要已存在于 Linux 网口上，否则客户端无法通过该地址连接 Server。
+
+## 3. 正常操作流程
+
+### 3.1 打开 Windows 客户端
+
+运行 `NetworkTool.Client.exe`。
+
+主窗口标题栏会显示客户端版本号，例如：
+
+```text
+NetworkTool 2026.05.13.1700
+```
+
+该版本号用于确认现场使用的客户端是否为最新版本。
+
+### 3.2 选择本机网卡
+
+在主窗口“本机网卡”下拉框中选择与 Linux 维护网卡直连的 Windows 有线网卡。
+
+说明：
+
+1. 默认勾选“仅显示可用网卡”。
+2. 可用网卡要求已连接网线并且存在 IPv4 地址。
+3. 如果列表为空，可取消“仅显示可用网卡”，或点击“刷新”。
+
+### 3.3 搜索设备
+
+选择网卡后，客户端会自动搜索设备。
+
+也可以点击“重新搜索设备”手动重新搜索。
+
+搜索成功后，设备列表会显示：
+
+1. IP。
+2. 主机名。
+3. MAC 地址。
+
+### 3.4 连接设备
+
+在“发现设备（双击连接）”列表中双击目标设备 IP。
+
+客户端会要求输入管理密码。默认密码为：
+
+```text
+Dt123$
+```
+
+连接成功后会打开“设备信息与网口配置”窗口。
+
+### 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. 单个接口最多只能有一条默认路由。
+6. 所有网口中最多只能配置一个默认网关。
+
+### 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` 检查网口 |
+| 读取目标网口配置失败 | 接口不存在；读取 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 networktool-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/networktool-server-run.log
+```
+
+### 5.6 Windows 测试 HTTP 健康检查
+
+在 PowerShell 中执行：
+
+```powershell
+curl.exe -H "X-Admin-Password: Dt123$" http://169.254.100.2:48888/api/health
+```
+
+正常返回示例：
+
+```json
+{
+  "code": 0,
+  "message": "成功",
+  "data": {
+    "status": "运行中",
+    "server_version": "2026.05.13.1700"
+  }
+}
+```
+
+### 5.7 Windows 检查本机 IP
+
+```powershell
+ipconfig
+```
+
+确认连接设备的有线网卡有 `169.254.x.x` 地址。