5.8 KiB
OpsX VPN 桌面客户端
仓库根目录的 client/ 是独立的 Rust + Tauri v2 + React/TypeScript 桌面项目。形态参考同级 opsxshell、opsxapi：界面运行在 Tauri WebView，服务请求经 Rust 命令完成。与仓库的 frontend/ 管理后台独立构建。
客户端通过独立的 /api/client/* 接口登录拨号用户、获取授权线路、自动登记设备公钥并领取配置；私钥保存在本机 Rust 数据目录，前端不接触令牌和私钥。登录页允许 HTTP 和 HTTPS 地址，HTTP 明确提示明文风险。概览每隔 30 秒检查控制面可达性；该往返耗时不是 VPN 节点延时，连接状态以网关握手为准。
登录入口只需填写接入点的服务端地址（自动带入上次使用的地址），验证服务端健康与客户端能力后按服务端 password/oidc 能力展示对应入口。当前 WireGuard 客户端接口只支持密码/MFA；飞书 / Lark 仅在服务端声明 OIDC 能力时展示接入状态，浏览器一键登录按钮暂不可用。OpenVPN 的 openvpn-auth-oauth2 不能直接签发桌面 WireGuard 客户端会话，不能仅根据邮箱将飞书身份关联拨号用户。
客户端不调用本机 wg 或 wg-quick，也不会在内置直连未就绪时回退到系统工具。浏览器界面预览不会调用本机检查。安装包附带官方 wireguard-go 的 Go 网络栈组件，支持无特权出口探测和本机 SOCKS5 代理 socks5h://127.0.0.1:18743；概览和线路页可显式启动代理，并自动登记拨号用户的本机设备。macOS 上在设备配置包含 0.0.0.0/0 时，还可以手动启用系统 SOCKS 代理，使遵循系统代理的应用无需逐个设置；不修改系统路由，不保证所有应用或 UDP 经过节点。已有系统代理/PAC 时拒绝接管，关闭时只还原自身设置，客户端异常结束后下次启动会清理残留。实际 macOS 代理权限、浏览器 DNS 行为与故障恢复仍需真机验收。系统隧道设计、平台验收与发布门槛见 SDD-003。
内置 Go 原生 TUN 目前已具备 macOS 接口创建、网关物理出口只读检查、IPv4 路由计划和握手计数查询；Rust 侧有受限的子进程桥接，但尚未挂载连接按钮。系统地址、路由、DNS 的特权配置和异常恢复仍需实现并通过真机验收，现阶段不能将接口创建视为可联网。
使用与验收
- 在桌面客户端使用拨号用户登录（管理后台的
admin不是拨号用户），选择已运行、已授权的 WireGuard 专线。首次接入时客户端自动生成设备私钥并向服务端登记公钥，无需下载.conf。 - 当前版本的内置直连尚未完成，不能通过安装系统 WireGuard 工具启用直连。
- 可在设置页启动本机应用代理，再在需要访问的应用中设置
socks5h://127.0.0.1:18743。例如在终端验证curl --proxy socks5h://127.0.0.1:18743 http://www.baidu.com。设置页“测试 VPN 出口”会连接223.5.5.5:443；握手或测试成功不代表整机路由已切换。
概览的“选择线路”弹窗和线路页只列出该账号真正获授权的 WireGuard 专线；极速/全局按钮按专线的 AllowedIPs 选择具备该路由能力的线路。没有该模式的授权线路时按钮不可选；同一线路不能由客户端私自扩大授权路由。每条线路的“测速”使用已登记设备经 WireGuard 到管理员配置的 latency_probe（可访问的 IP:端口，缺省 223.5.5.5:443）的 TCP 建链时间，包含隧道启动与握手，并非节点 RTT；绿色表示 ≤120 ms，黄色表示较高耗时，失败或未测量时保持灰色。专线若未授权探测目标或网关未启用所需转发，测速不可用，不能把控制面健康请求当作节点延迟。
公网代理需要管理员为该专线下发覆盖目的地和 DNS 服务器的 AllowedIPs，并在 VPN 网关开启 IPv4 转发与仅匹配 WireGuard 网段的出口 NAT；现有 opsx-client-pilot 测试专线仍只授权 10.88.0.0/24，不能直接用于公网代理。本机 SOCKS5 监听仅绑定 127.0.0.1、无额外口令，其他本机进程也能使用；切换账号、撤销本机设备、退出登录或退出应用时会停止代理。客户端意外退出后代理最多约两秒内检测到父进程消失并退出。
浏览器打开 http://127.0.0.1:5176/ 只能预览 UI；原生登录、Go 代理及系统隧道必须在 Tauri 桌面窗口测试。HTTP 服务端地址允许使用，但账号口令和令牌会明文传输，生产请使用可信 HTTPS。
开发与构建
cd client
npm install
npm run build:tunnel # 为本机目标架构构建 Go WireGuard 组件；需要 Go 工具链
npm run dev # Tauri 桌面窗口
npm run dev:ui # 仅预览界面；浏览器里不能执行 Tauri 的真实健康检查
npm run build:ui # 界面类型检查与构建
npm run build # Tauri 安装包（需目标 OS 的构建依赖）
cd src-tauri && cargo test
cd ../tunnel-go && go test ./...
平台使用标准 WireGuard UDP，没有复用管理员登录令牌或飞连私有协议。认证和设备 Peer 接口设计见 SDD-002；当前客户端已实现这部分接口，真实目标 OS 隧道与 DNS/路由恢复仍需实机验收。
Go 模块固定 golang.zx2c4.com/wireguard 版本并提交 go.sum。构建工具链只用于开发和发行打包，员工机器不需要 Go 或 Homebrew。探测结果只报告目标 TCP 是否可达：要验证公网，专线必须给该客户端下发覆盖公网目标的 AllowedIPs，网关必须开启 IP 转发及对应网段的出口 NAT。当前测试专线仍只下发私网路由，管理员授权公网后才可在设置页使用公网代理。