# 故障排查

> 按安装、服务、审批、连通性和卸载阶段定位问题，并查询 E1xxx 错误码。

来源: https://www.widewired.com.cn/page/docs/troubleshooting

## 收集基础状态

先选择正确网络并查看[总览](https://www.widewired.com.cn/page/docs/overview)。近期变更对照「洞察 → 日志」，历史连接问题对照「洞察 → 传输」。

Linux 或 Windows 设备在本机运行：

```
wwnet
```

记录整张表-`status`、`network address`、各行 `peers`-以及完整错误提示和 `E1xxx` 错误码。连通性问题需要在链路两端分别收集。

已有错误码时，可直接查看本页末尾的[错误码对照](#错误码对照)。

macOS 和移动设备改为收集应用版本、连接状态、网络编号及设备信息；这些应用不提供桌面命令行。

## 安装失败

| 提示 | 处理 |
| --- | --- |
| 需要 root 或管理员权限 | Linux 使用 `sudo`；Windows 使用管理员 PowerShell |
| 网络编号格式错误或不存在 | 从控制台「配置 → 设备」重新复制完整命令 |
| 缺少 `curl` | 安装 `curl` 后重试 |
| 签名或校验失败 | 不要绕过校验；更换网络后重试，持续失败时联系支持 |

## 后台服务未运行

`E1002` 对应 `status` 为 `background service not running`。检查服务：

```
systemctl status wwnet            # Linux (systemd)
/etc/init.d/wwnet status          # OpenWrt
Get-Service wwnet                 # Windows
```

服务不存在通常表示安装未完成，应重新执行安装命令。Linux 日志使用 `journalctl -u wwnet -n 100 --no-pager`，OpenWrt 使用 `logread | grep wwnet`。

`E1003` 表示服务正在初始化。等待数秒后重试，不要反复重启。

## 设备停留在待审批

`status` 为 `awaiting approval` 是注册后的正常状态。在控制台「配置 → 设备」批准设备后再测试通信。

若设备未出现在列表中，说明注册尚未完成；回到设备查看 `wwnet` 输出和错误码。

## 两台设备无法互通

按以下顺序检查：

1. 两端 `status` 均为 `connected`，且已在控制台批准。
2. 测试目标使用对端的 `network address`，而不是本地 LAN 地址。
3. 虚拟网络地址段（Overlay CIDR）不与任一端本地 LAN 或子网路由目标重叠。
4. 目标主机防火墙允许来自虚拟网卡的 ICMP 或实际业务端口。
5. `wwnet` 中该对端的 `peers` 行显示健康路径。
6. 控制台「配置 → 链路」没有禁用所有可用路径。

`ping` 被主机策略禁用时，应改用实际业务端口验证，不要只凭 ICMP 判断链路不可用。

## 使用中继而非直连

直连因对称型 NAT，或防火墙阻断所允许的 UDP、TLS 协议而失败时，系统会回落到网内设备转发或全球专线传输。这是正常选路，不影响端到端加密。

若业务要求直连，检查两端 NAT 类型、允许的直连协议和主机防火墙；路径详情见[链路](https://www.widewired.com.cn/page/docs/paths)。

## 全球专线传输未生效

在「总览」的拓扑中选中该链路，右侧面板的「路径策略」下会显示全球专线传输不可用的原因；非计划的不可用也会出现在「洞察 → 告警」。按显示原因处理：

- **Credit 状态初始化中**：等待同步，不要充值。
- **Credit 余额不足**：充值到账后自动恢复。
- **当前没有可用全球专线传输节点**：等待恢复，期间使用免费路径；持续异常时联系支持。
- **账号已关闭、Credit 状态冲突**及其他原因：联系支持。

链路已关闭全球专线传输或当前不在工作时段内时，它不参与选路：在「配置 → 链路」确认该链路的全球专线传输为「开启」，并核对工作时段、时区和当前时间。

## 切换网络时冲突

`E1042` 表示当前安装实例已经属于其他网络。先执行：

```
wwnet leave
```

完成后再运行新网络的安装命令。

## 离开或卸载未完成

`E1060` 对应 `status` 为 `needs attention`，表示路由、防火墙或虚拟网卡尚未完全还原。执行：

```
wwnet uninstall
```

该命令不依赖后台服务，可重复执行。报告成功前不要手工删除程序目录或恢复数据。

## Windows 安全提示

首次下载或运行时，Windows 或企业终端防护可能要求确认。按组织策略完成管理员放行。若安装器报告签名或 SHA-256 校验失败，不要绕过。

## 错误码对照

终端错误末尾包含稳定错误码，例如：

```
wwnet: this command needs administrator/root privileges (E1001)
```

### 本机可处理

| 错误码 | 含义 | 处理 |
| --- | --- | --- |
| `E1001` | 权限不足 | Linux 使用 `sudo`；Windows 使用管理员 PowerShell |
| `E1002` | 后台服务未运行 | 启动服务；Linux 可执行 `sudo systemctl start wwnet` |
| `E1004` | 命令或参数错误 | 运行 `wwnet help` 查看用法 |
| `E1040` | 网络不存在 | 从「配置 → 设备」重新复制命令，并确认网络未删除 |
| `E1041` | 当前状态不允许该操作 | 等待正在进行的加入或清理完成后重试 |
| `E1042` | 设备已加入其他网络 | 先运行 `wwnet leave`，再加入新网络 |
| `E1050` | 请求被服务端拒绝 | 从「配置 → 设备」重新复制完整命令后重试；持续失败时带上 `wwnet` 输出联系支持 |

### 等待或检查网络

| 错误码 | 含义 | 处理 |
| --- | --- | --- |
| `E1003` | 后台服务尚未就绪 | 等待数秒后重试，不要重启服务 |
| `E1030` | 无法连接网连网络服务端 | 检查公网、代理、DNS 和出站 ACL |
| `E1031` | 请求频率受限 | 等待后重试，避免循环调用；注册新设备时出现，先在控制台批准或删除已有的待审批设备 |

### 检查控制台

| 错误码 | 含义 | 处理 |
| --- | --- | --- |
| `E1010` | 设备身份不再被接受 | 确认账号、网络和设备仍存在，再按终端显示的恢复步骤处理 |

### 联系支持

| 错误码 | 含义 | 处理 |
| --- | --- | --- |
| `E1020` | 无法验证服务端响应 | 更换网络后重试；持续失败时联系支持，不要忽略或绕过 |
| `E1060` | 离开或卸载未完成 | 重复执行 `wwnet uninstall`；持续失败时联系支持 |
| `E1000` | 未分类错误 | 带上 `wwnet` 输出联系支持 |

## 仍未解决

联系支持时提供错误码、发生时间、系统版本和两端的 `wwnet` 输出，见[获取支持](https://www.widewired.com.cn/page/docs/support)。