客户端与控制

客户端负责把一台机器接入 WG Free Mesh，并接受控制台下发的配置和控制命令。

客户端是纯命令行实现，没有本地图形界面。它更适合服务器、边缘设备和自动化运维场景；安装、绑定、查看状态、读取日志、启停服务都可以直接写进脚本。

下载客户端

在工具列表进入下载页面后，选择“客户端下载”。页面只提供构建并下载入口，产物缓存、构建路径和文件清理都由后端处理。

下载文件按系统和架构区分。Windows 目前支持常见 64 位版本，并额外提供 32 位客户端。下载后建议解压到固定目录，后续不要随意移动；如果移动目录，需要重新执行安装。

安装

安装需要管理员或 root 权限。安装完成后，wfmctl 会加入 PATH，后续大部分命令在三端保持一致。

Windows 使用 PowerShell 管理员，在客户端目录执行：

.\wfmctl.exe install; $env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine")

Linux 和 macOS 在客户端目录执行：

sudo ./wfmctl install

安装过程会输出客户端标识、版本信息，并检查本机是否具备 wg 和 awg 工具链。缺失工具链时，客户端会给出提示，但安装本身不应该因为这些检查失败而中断。

CLI 命令

安装完成后，除重新安装这种当前目录场景外，日常命令统一使用 wfmctl。

命令	用途	备注
wfmctl install	安装服务。	需要管理员或 root 权限。首次安装请优先使用上方平台命令。
wfmctl uninstall	卸载服务。	停止服务、取消自启动、删除服务定义和 PATH 项，保留本地数据。
wfmctl uninstall --purge	卸载并清理本地数据。	同时删除本地 profile、运行数据和日志。
wfmctl bind --server <url> --token <token>	绑定端点。	绑定命令建议直接从端点控制页面复制。
wfmctl bind <url> <token>	绑定端点的简写形式。	等价于显式传入 --server 和 --token。
wfmctl unbind <profile_id>	删除单个本地绑定。	不会撤销服务端节点权限。
wfmctl unbind --all	删除本机全部本地绑定。	多 profile 排查时使用。
wfmctl list	查看本机绑定列表。	显示 profile、配置/端点名、服务端地址和 MQTT 信息。
wfmctl status	查看服务和绑定状态。	排查问题时优先执行。
wfmctl logs	查看服务日志。	默认显示最近 100 行。
wfmctl logs --lines <n>	查看指定行数日志。	例如 wfmctl logs --lines 300。
wfmctl start	启动服务。	自启动配置不受影响。
wfmctl stop	停止服务。	自启动配置仍保留。
wfmctl restart	重启服务。	重新加载本地绑定和配置。
wfmctl version	查看客户端版本。	也可以使用 wfmctl --version 或 wfmctl -v。
wfmctl help	查看帮助。	使用 wfmctl help <命令> 查看子命令说明。

首次接入流程

推荐按这个顺序操作：

1. 在控制台创建配置和端点。
2. 在下载页面下载对应系统和架构的客户端。
3. 解压客户端到固定目录。
4. 执行安装命令。
5. 回到端点控制页面复制绑定命令。
6. 执行绑定命令。
7. 使用 wfmctl status 确认服务正在运行。
8. 回到控制台下发配置并启动隧道。

绑定后检查

绑定成功后，用下面命令确认本地状态：

wfmctl status

重点看这些信息：

• State 是否为 running。
• Profiles 是否大于 0。
• 绑定项里是否显示正确的配置名和端点名。
• MQTT 主机、端口和 TLS 状态是否符合预期。

如果 Profiles 为 0，说明本地没有有效绑定。回到端点控制页面重新复制绑定命令。

日志排查

客户端日志用于排查服务启动、MQTT 连接、配置下发和控制命令执行问题。

wfmctl logs --lines 300

客户端会记录关键状态变化，例如：

• 服务启动和停止。
• profile 加载。
• MQTT 连接成功。
• MQTT 断开。
• MQTT 重连成功。
• 配置下发失败。
• 控制命令执行结果。

连接检测和重试过程本身不会持续刷日志，避免日志噪声过大。

端点控制

端点控制页面依赖客户端在线和 MQTT 服务。常见操作包括：

• 刷新状态。
• 下发配置。
• 启动隧道。
• 停止隧道。
• 查看 WireGuard / AmneziaWG 状态。
• 重置客户端绑定。

重置客户端时，系统会同步删除或禁用对应 EMQX 用户，并尝试立即断开客户端 MQTT 连接。客户端需要重新绑定后才能继续受控。

MQTT 不可用时

如果部署关闭了 MQTT 服务，客户端绑定、端点控制、在线状态和远程命令会被系统层面禁用。此时仍可维护配置和静态 Mesh 数据，但不能通过控制台驱动客户端行为。