设备
安装软件、处理平台差异、审批和管理设备，并使用 wwnet 命令行。
设备状态
设备列表位于控制台「配置 → 设备」。
| 列 | 含义 |
|---|---|
| 设备 | 主机名 |
| 别名 | 可选的自定义显示名称 |
| 虚拟地址 | 该设备在当前网络中的虚拟网络 IP（Overlay IP） |
| 运行平台 | 操作系统与架构 |
| 审批状态 | 待审批、已批准、已阻断 |
| 在线状态 | 当前是否在线 |
| 最近通信 | 最近一次与服务端同步的时间 |
「详情」显示设备上报的静态设备信息，包括系统、内核、架构、CPU 型号、内存及交换分区容量、网卡和磁盘容量；不展示 CPU、内存、磁盘或网络的实时使用率。设备尚未完成首次上报时，这些字段为空。
安装软件
支持范围
| 系统 | 架构 | 服务管理器 | 安装位置 |
|---|---|---|---|
| Linux | x86-64、ARM64 | systemd；OpenWrt 使用 procd | /usr/local/bin；OpenWrt 为 /usr/bin |
| macOS | 仅 Apple Silicon | launchd | /usr/local/bin |
| Windows | x86-64、ARM64 | Windows 服务 | %ProgramData%\wwnet |
目前不提供 iOS 或 Android 版本。
安装前提
- 管理员权限：Linux 和 macOS 使用
sudo，Windows 使用管理员 PowerShell。 - Linux 和 macOS 已安装
curl。 - 允许访问发布源和网连网络服务端的出站网络。
- 操作系统支持 TUN 虚拟网卡。
无需公网 IP，也无需开放入站端口。
获取安装命令
进入控制台「配置 → 设备」，打开添加设备窗口。窗口会按平台生成已包含站点域名和当前网络编号的命令。
Linux 和 macOS：
curl -fsSL https://<你的站点 API 域名>/wwnet/install/join/<网络编号>.sh | sudo sh
Windows（管理员 PowerShell）：
powershell -c "irm https://<你的站点 API 域名>/wwnet/install/join/<网络编号>.ps1|iex"
尖括号仅用于说明格式。实际操作时直接复制控制台生成的完整命令，不要手工替换。
安装器执行流程
- 检测操作系统、架构和服务管理器。
- 下载并验证发布清单签名。
- 下载对应程序，验证签名和 SHA-256；校验失败时立即中止。
- 安装程序并注册系统服务。
- 使用网络编号注册设备，状态进入待审批。
Linux
支持 x86-64（x86_64、amd64）和 ARM64（aarch64、arm64）。检测到 /sbin/procd 和 /etc/rc.common 时使用 OpenWrt 的 procd；其他环境需要 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
macOS
仅支持 Apple Silicon（M 系列）。uname -m 返回 arm64 表示原生 Apple Silicon 终端；返回 x86_64 时，在「关于本机」确认芯片类型，并退出 Rosetta 终端后重试。
sudo 会请求当前 macOS 用户密码。检查 launchd：
sudo launchctl list | grep wwnet
终端软件会创建由 macOS 自动编号的 utun 接口，不需要手工设置；卸载时自动清理。
Windows
普通 PowerShell 会触发 Windows 提权提示，确认后脚本以管理员身份继续；也可先以管理员身份启动 PowerShell。
Windows 或企业终端防护可能在首次下载或运行时要求放行。安装器会验证发布清单签名和程序 SHA-256；任一校验失败都会中止，不要通过关闭校验或使用来源不明的程序绕过。
检查 Windows 服务：
Get-Service wwnet
终端软件通过 wintun 创建虚拟网卡，可在「网络连接」中查看。该网卡不需要手工配置，应保持启用；卸载时自动清理。
管理设备
批准设备
新注册设备处于待审批，不能与其他设备通信。在「配置 → 设备」核对主机名和平台后执行批准。状态变为已批准后，系统生成到其他设备的链路。
网络编号不是认证凭据，因此审批是设备获得网络访问权限的必要步骤。
编辑设备
「编辑」支持修改：
- 别名：只影响控制台显示。
- 虚拟地址：必须位于当前虚拟网络地址段（Overlay CIDR）内，并在网络内唯一；下一轮配置同步后生效。
- 传输协议：控制直连使用的传输方式。
修改虚拟网络 IP 后，同步更新引用旧地址的脚本、防火墙规则和监控配置。
阻断与放行
阻断请求成功后，服务端立即改变设备授权状态，并保留记录和配置。已有设备连接会在撤权信息到达终端后停止；控制台请求成功本身不能证明连接已停止。放行后恢复为已批准状态。
阻断是服务端访问控制，不会卸载主机上的终端软件。
网内中继
开启「网内中继」后，该设备可以在其他两台设备无法直连时转发其流量。网内中继使用自有设备和带宽，不产生云端中继费用。
设备是否会被实际选中，取决于平台能力和网络可达性。对带宽受限或按流量计费的设备，建议关闭该开关。
删除设备
控制台删除会使设备退出当前网络并移除服务端记录，但不会删除主机程序。完成本地清理时，在该主机执行：
wwnet uninstall
命令行参考
网络与策略配置在控制台完成；wwnet 负责设备侧的注册、状态和生命周期操作。
| 命令 | 作用 |
|---|---|
wwnet |
显示状态表：网络、虚拟网络 IP，以及每个对端各一行 |
wwnet join <网络编号> |
使用控制台提供的 12 位编号加入网络 |
wwnet leave |
离开当前网络、还原网络配置并移除后台服务 |
wwnet uninstall |
完整清理本机安装，不依赖后台服务运行 |
wwnet update |
立即检查并安装新版本 |
wwnet version |
显示当前版本 |
wwnet help |
显示命令用法 |
join、leave 和 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 |
正在退出并还原本机配置 |
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。
更新
终端软件启动时和运行期间会自动检查更新，只允许前向升级。所有更新都验证来源、签名和完整性。立即检查：
wwnet update
有新版本时，命令会下载安装并自动重启后台服务。新版本无法正常运行时，会在健康观察期内自动回滚。使用 wwnet version 查看当前版本。
离开网络
wwnet leave
该命令会断开网络，还原由终端软件修改的路由、DNS、防火墙和虚拟网卡，删除本机设备身份，并卸载后台服务。切换网络时，先完成 leave，再执行新网络生成的安装命令；直接加入其他网络会返回 E1042。
卸载
wwnet uninstall
uninstall 停止服务、还原网络配置，并在还原成功后删除程序和本地数据。它不依赖后台服务，适用于服务无法启动或上次清理未完成的情况。
网络配置未完全还原时，终端返回 E1060，状态显示 needs attention。重复执行 wwnet uninstall；成功前不要手工删除程序目录或恢复数据。
诊断
崩溃报告和错误日志只在本机有界保留，不会自动上传。本机不导出诊断包：需要协助时，
把 wwnet 的输出连同错误码和发生时间提供即可，详见获取支持。
退出码
| 退出码 | 含义 |
|---|---|
0 |
成功 |
1 |
操作失败，读取错误提示 |
2 |
命令或参数错误 |
4 |
缺少管理员权限 |
故障速查
| 现象 | 检查与处理 |
|---|---|
| 安装命令立即失败 | 确认管理员权限、平台架构、curl 和出站网络，再从「配置 → 设备」复制完整命令 |
| 签名或 SHA-256 校验失败 | 不要绕过校验；更换网络后重试，持续失败时联系支持 |
Linux 找不到 /dev/net/tun |
加载 TUN 模块或改用包含 TUN 支持的内核或主机环境 |
| macOS 提示 Intel Mac 不支持 | 当前版本仅支持 Apple Silicon；检查是否在 Rosetta 终端中运行 |
| Windows 终端防护拦截 | 由管理员按组织策略放行，不要使用未校验的替代程序 |
status 为 awaiting approval |
在控制台批准该设备；这是注册后的正常状态 |
| 已批准但仍离线 | 检查 wwnet 的 peers 行、后台服务和「最近通信」时间 |
| 修改虚拟地址后访问失败 | 等待配置同步，并确认新地址未冲突且调用方已更新 |
status 为 background service not running |
检查对应平台的服务状态和日志；对应错误码 E1002 |
status 为 connecting |
等待配置同步；若返回 E1003，不要反复重启服务 |
status 为 error |
读取 reason 行获取详细原因和错误码 |
needs attention |
重复执行 wwnet uninstall，成功前不要手工删除相关目录 |
完整错误码见故障排查。