# 设备

> 安装软件、处理平台差异、审批和管理设备，并使用 wwnet 命令行。

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

## 设备状态

设备列表位于控制台「配置 → 设备」。

| 列 | 含义 |
| --- | --- |
| 设备 | 主机名，以及已设置的别名 |
| 在线状态 | 当前是否在线 |
| 审批状态 | 待审批、已批准、已阻断 |
| 虚拟地址 | 该设备在当前网络中的虚拟网络 IP（Overlay IP） |
| 公网地址 | 设备当前使用的公网出口地址 |

行尾的「更多设置」打开设备详情，其中显示设备上报的静态设备信息，包括系统、内核、架构、CPU 型号、内存及交换分区容量、网卡和磁盘容量；不展示 CPU、内存、磁盘或网络的实时使用率。设备尚未完成首次上报时，这些字段为空。

## 安装软件

### 桌面和服务器

| 系统 | 架构 | 服务管理器 | 安装位置 |
| --- | --- | --- | --- |
| Linux | x86-64、ARM64 | systemd；OpenWrt 使用 procd | `/usr/local/bin`；OpenWrt 为 `/usr/bin` |
| Windows | x86-64、ARM64 | Windows 服务 | `%ProgramFiles%\WideWired` |

### 安装前提

- 管理员权限：Linux 使用 `sudo`，Windows 使用管理员 PowerShell。
- Linux 已安装 `curl`。
- 允许访问发布源和网连网络服务端的出站网络。
- 操作系统支持 TUN 虚拟网卡。

无需公网 IP，也无需开放入站端口。

### 获取安装命令

进入控制台「配置 → 设备」，在“它如何工作”中选择安装平台。页面会按平台生成已包含站点域名和当前网络编号的命令；iPhone 和 macOS 提供 App Store 链接，Android 提供安装包，HarmonyOS 提供应用市场入口；这些平台使用应用链接或二维码，不使用命令。

Linux：

```
curl -fsSL https://<你的站点 API 域名>/wwnet/install/join/<网络编号>.sh | sudo sh
```

Windows（管理员 PowerShell）：

```
# 在管理员 PowerShell 中执行
iex (irm "https://<你的站点 API 域名>/wwnet/install/join/<网络编号>.ps1")
```

尖括号仅用于说明格式。实际操作时直接复制控制台生成的完整命令，不要手工替换。

安装器会选择当前平台对应的版本，验证下载内容，安装后台服务，并用网络编号注册设备。完成后，设备状态进入**待审批**。

### Linux

支持 x86-64（`x86_64`、`amd64`）和 ARM64（`aarch64`、`arm64`）。OpenWrt 需要 procd 服务管理器，其他 Linux 发行版需要 systemd。

安装前确认内核提供 `/dev/net/tun`；OpenWrt 还需确认 `/usr` 所在分区有足够安装空间。

检查 systemd 服务和日志：

```
systemctl status wwnet
journalctl -u wwnet -n 100 --no-pager
```

OpenWrt：

```
/etc/init.d/wwnet status
logread | grep wwnet
```

### iPhone、Android 与 HarmonyOS

进入「配置 → 设备」，在“它如何工作”中选择对应平台。iPhone 从 App Store 安装，Android 使用页面提供的安装包，HarmonyOS 使用应用市场入口。安装后：

1. 输入控制台中当前网络的 12 位编号。
2. 发起连接，按系统提示授予 VPN 权限。
3. 在「配置 → 设备」核对新设备身份并批准。
4. 确认应用显示已连接，再测试访问对端的虚拟网络地址。

移动设备不作为转发出口或站点路由设备，也不运行自动化脚本；网内设备转发默认关闭，可在设备详情中开启。

### macOS

macOS 使用 [App Store](https://apps.apple.com/cn/app/id6814312050) 中的 WideWired 应用，与 iOS 为同一应用页，需要 macOS 12 或更高版本，Apple Silicon 与 Intel 芯片的 Mac 均可。安装应用后：

1. 输入控制台显示的 12 位网络编号。
2. 选择连接，并在首次使用时允许 macOS 添加 VPN 配置。
3. 返回控制台「配置 → 设备」批准新设备。

应用通过 App Store 更新，macOS 上不提供 `wwnet` 命令行。Mac 可以执行对它生效的转发规则，网内设备转发默认开启，可在设备详情中关闭；与移动设备相同，不会作为站点路由设备或转发出口，不运行设备自动化脚本。

### Windows

普通 PowerShell 会触发 Windows 提权提示，确认后脚本以管理员身份继续；也可先以管理员身份启动 PowerShell。

Windows 或企业终端防护可能在首次下载或运行时要求放行。安装器会验证发布清单签名和程序 SHA-256；任一校验失败都会中止，不要通过关闭校验或使用来源不明的程序绕过。

检查 Windows 服务：

```
Get-Service wwnet
```

终端软件会创建虚拟网卡，可在「网络连接」中查看。该网卡不需要手工配置，应保持启用；卸载时自动清理。

## 管理设备

### 批准设备

新注册设备处于**待审批**，不能与其他设备通信。在「配置 → 设备」核对主机名和平台后执行批准。状态变为**已批准**后，系统生成到其他设备的链路。

网络编号不是认证凭据，因此审批是设备获得网络访问权限的必要步骤。

### 编辑设备

在设备行尾的「更多设置」中就地修改：

- **别名**：只影响控制台显示。
- **虚拟地址**：必须位于当前虚拟网络地址段（Overlay CIDR）内，并在网络内唯一；下一轮配置同步后生效。
- **传输协议**：控制直连使用的传输方式。

修改虚拟网络 IP 后，同步更新引用旧地址的脚本、防火墙规则和监控配置。

### 转发设置

设备详情不提供转发设置入口；此前已保存的设备排除网段继续生效，其中的目的始终使用本机系统路由。

转发规则在「配置 → 转发」中统一维护，每条规则选择生效的设备；需要让部分目的不经出口时，在规则的目的网段中选择「仅排除指定网段」。配置方法见[转发](https://www.widewired.com.cn/page/docs/forward)。

### 阻断与放行

阻断后，设备记录和配置仍会保留，已有连接可能需要短暂时间才能停止。放行后恢复为已批准状态。阻断不会卸载设备上的终端软件或移动应用。

### 网内设备转发

开启「网内设备转发」后，该设备可以在其他两台设备无法直连时转发其流量。网内设备转发使用自有设备和带宽，不产生全球专线传输费用。

所有平台都可开关：Linux、Windows 和 macOS 默认开启，iPhone、Android 和 HarmonyOS 默认关闭。设备是否会被实际选中，取决于网络可达性。对带宽受限或按流量计费的设备，建议关闭该开关。

### 离线告警

设备详情的“离线告警”默认关闭。需要离线提醒时，可在“网内设备转发”下将其开启；关闭后不再生成离线告警，当前离线告警立即结束，设备在线状态仍如实显示。

### 删除设备

控制台删除会使设备退出网络。Linux 和 Windows 客户端收到删除通知后会还原网络配置并卸载；macOS 和移动 App 会退出网络，但不会删除 App。离线设备需要恢复联网才能接收通知。若 Linux 或 Windows 设备无法自动完成清理，在该设备执行：

```
wwnet uninstall
```

## 命令行参考

网络与策略配置在控制台完成；Linux 和 Windows 上的 `wwnet` 负责设备注册、状态查询、更新、离开网络和卸载；macOS 与移动设备在应用内完成这些操作。

| 命令 | 作用 |
| --- | --- |
| `wwnet` | 显示状态表：网络、虚拟网络 IP，以及每个对端各一行 |
| `wwnet join <网络编号>` | 使用控制台提供的 12 位编号加入网络 |
| `wwnet leave` | 离开当前网络、还原网络配置并移除后台服务 |
| `wwnet uninstall` | 完整清理本机安装，不依赖后台服务运行 |
| `wwnet update` | 请求检查更新 |
| `wwnet version` | 显示当前版本 |
| `wwnet help` | 显示命令用法 |

`join`、`leave`、`update` 和 `uninstall` 需要管理员权限。`leave` 不接受网络编号，因为一个安装实例同时只属于一个网络。

### 状态与路径

直接运行 `wwnet` 查看设备和对端状态。命令行输出使用英文。

| 字段 | 含义 |
| --- | --- |
| `console` | 本机对应的控制台地址，可直接在浏览器打开 |
| `version` | 已安装的客户端版本 |
| `status` | 连接状态，取值见下表 |
| `device name` | 本机主机名 |
| `device id` | 设备编号，与控制台一致 |
| `network name` | 网络名称，与控制台一致 |
| `network id` | 12 位网络编号 |
| `network address` | 本机在该网络内的地址 |
| `peers` | 每个对端一行：`<名称> (<虚拟网络 IP>) - <路径类型>, <状态>` |

取不到的值统一显示为 `unknown`。路径类型为直连（`direct`）、网内设备转发（`peer relay`）
和全球专线传输（`cloud relay`）；状态为 `healthy`、`needs attention`、`checking`。

| `status` | 含义 |
| --- | --- |
| `connected` | 已连接，可与网络内其他设备通信 |
| `awaiting approval` | 注册完成，等待控制台审批 |
| `connecting` | 正在获取或应用配置 |
| `disconnecting` | 正在退出并还原本机配置 |
| `uninstalling` | 正在卸载；以管理员权限运行 `wwnet uninstall` 完成清理 |
| `paused by an administrator` | 管理员已在控制台暂停该设备 |
| `needs attention` | 连接已停止工作，或上一次离开、卸载未完成；表格会多出 `reason` 行给出原因 |
| `not joined to a network` | 已安装但未加入网络 |
| `background service not running` | 后台服务未运行 |

需要用户处理的状态会把下一步写在表里：等待审批时给出 `approve at`，被暂停或需要处理时给出
`what to do`。此外表格会就地增加行：连接停止工作时增加 `reason`；上一次离开或卸载未还原
完成时，增加 `stage`、`code`、`reason` 和 `what to do`。

### 更新

自动检查更新遵循「管理 → 属性」中的自动更新策略和维护窗口，选择「关闭」时停用常规自动检查。

Linux 和 Windows 设备收到高于当前版本的平台最低版本要求时，会立即尝试自动升级，不受「关闭」和维护窗口限制，期间服务可能短暂重启。

需要立即发起检查时，以管理员权限运行以下命令；手动检查不受该策略和窗口限制：

```
wwnet update
```

`Update check requested.` 表示已接受检查请求，不代表安装已经完成。符合升级条件的新版本会在后台下载和安装，期间服务可能短暂重启。更新会检查来源、签名和完整性；新版本未通过健康检查时，会自动回滚。

等待更新后，运行 `wwnet version` 核对已安装版本，再运行 `wwnet` 确认连接已恢复。

### 离开网络

```
wwnet leave
```

该命令会断开网络，还原由终端软件修改的路由、DNS、防火墙和虚拟网卡，删除本机设备身份，并卸载后台服务。切换网络时，先完成 `leave`，再执行新网络生成的安装命令；直接加入其他网络会返回 `E1042`。

### 卸载

```
wwnet uninstall
```

`uninstall` 停止服务、还原网络配置，并在还原成功后删除程序和本地数据。它不依赖后台服务，适用于服务无法启动或上次清理未完成的情况。

网络配置未完全还原时，终端返回 `E1060`，状态显示 `needs attention`。重复执行 `wwnet uninstall`；成功前不要手工删除程序目录或恢复数据。

### 诊断

崩溃报告和错误日志不会自动上传。需要协助时，提供 `wwnet` 输出、错误码和发生时间，参阅[获取支持](https://www.widewired.com.cn/page/docs/support)。

### 退出码

| 退出码 | 含义 |
| --- | --- |
| `0` | 成功 |
| `1` | 操作失败，读取错误提示 |
| `2` | 命令或参数错误 |
| `4` | 缺少管理员权限 |

## 故障速查

| 现象 | 检查与处理 |
| --- | --- |
| 安装命令立即失败 | 确认管理员权限、平台架构、`curl` 和出站网络，再从「配置 → 设备」复制完整命令 |
| 签名或 SHA-256 校验失败 | 不要绕过校验；更换网络后重试，持续失败时联系支持 |
| Linux 找不到 `/dev/net/tun` | 加载 TUN 模块或改用包含 TUN 支持的内核或主机环境 |
| App Store 提示该 Mac 不兼容 | macOS 应用需要 macOS 12 或更高版本；Apple Silicon 与 Intel 芯片的 Mac 均可 |
| Windows 终端防护拦截 | 由管理员按组织策略放行，不要使用未校验的替代程序 |
| `status` 为 `awaiting approval` | 在控制台批准该设备；这是注册后的正常状态 |
| 已批准但仍离线 | 检查 `wwnet` 的 `peers` 行、后台服务和设备列表的在线状态 |
| 修改虚拟地址后访问失败 | 等待配置同步，并确认新地址未冲突且调用方已更新 |
| `status` 为 `background service not running` | 检查对应平台的服务状态和日志；对应错误码 `E1002` |
| `status` 为 `connecting` | 等待配置同步；若返回 `E1003`，不要反复重启服务 |
| `needs attention` | 按 `reason` 和错误码处理；只有离开或卸载未完成（`E1060`）时，才重复执行 `wwnet uninstall` |

完整错误码见[故障排查](https://www.widewired.com.cn/page/docs/troubleshooting)。