feat(tls): manage ACME domain and add desktop client settings

docs/deploy.md

@@ -55,7 +55,7 @@ sudo ss -tlnp | grep ':18080'
 
 认证入口另设可供 VPN 客户端在连接前访问的 HTTPS 地址，例如 `https://vpn-login.example.com`。它**可以与 opsx-vpn 管理后台部署在同一台服务器上**：反向代理依据域名把管理站点送往 `:18080`，把认证站点的**所有路径**送往同机 `127.0.0.1:19090`（按专线配置调整）。两者是同一台服务器上的不同 Web 服务，并非管理后台不允许提供其他页面；当前实现由平台启动和管理认证组件，回调实际由 `openvpn-auth-oauth2` 处理。最终在 OIDC 身份提供方登记 `https://vpn-login.example.com/oauth2/callback`。不要把本地认证端口或 OpenVPN 管理 socket 暴露到公网。详见 [接入说明](../README.md#openvpn-飞书--oidc-浏览器认证)。
 
-该域名须由你控制并解析到反向代理公网地址。可以在已有反向代理面板申请 Let's Encrypt 免费证书：HTTP-01 需要公网 TCP 80 能访问验证路径 `/.well-known/acme-challenge/`，续期时也要保留该路径；443 为认证入口提供 HTTPS。无需上传已有证书，也无需在 opsx-vpn 内再开发证书申请功能。若代理与 VPN 主机分离，代理上的 `127.0.0.1` 指代理主机自身，应改用受限的私网地址，并评估认证流量在私网链路上的保护。
+该域名须由你控制并解析到公网入口。管理员可在“设置 → 域名与证书”保存 `test-link.appx365.com` 并重启服务，或通过 `VPN_TLS_DOMAIN=test-link.appx365.com` 配置（环境变量优先）。Gin 进程使用已有的 `golang.org/x/crypto/acme/autocert` 依赖监听 TCP 80/443，处理 HTTP-01、签发与自动续签；无需额外引入 `gin-gonic/autotls`。证书和 ACME 账号密钥保存在 `data/acme`（随数据目录备份）。端口空闲、公网 DNS 和云安全组 TCP 80/443 通畅是必要条件；首次访问 `https://test-link.appx365.com/api/health` 才开始签发。80/443 的进程需要绑定低端口的权限；现有以 sudo 运行的服务可直接使用。原端口 `18080` 保留用于兼容，启用 HTTPS 后应限制它的公网访问。保存域名不会自动打开云安全组，也不会为其他认证域名配置反向代理。可以选择外置 Nginx / Certbot，但不要让两者同时争用 80/443；若代理与 VPN 主机分离，代理上的 `127.0.0.1` 指代理主机自身，应改用受限的私网地址，并评估认证流量在私网链路上的保护。
 
 `/.well-known/openid-configuration` 属于发行者域名，不是认证入口上的 VPN 回调。不要只放行 `/oauth2/callback`：认证组件还需要发起登录等路由。认证入口使用独立域名，只反代给认证组件；如需按路径白名单返回 Nginx `444`，须先核对实际安装版本的完整路由，并保障 HTTP-01 验证路径。认证端口默认 19090，仅监听回环；新增 OIDC 专线自动递增并跳过已配置或已监听的端口，仍以启动时冲突检测为准。
 

docs/specs/SDD-002-desktop-wireguard-client.md

@@ -0,0 +1,97 @@
+# SDD-002：opsx-vpn 桌面客户端与 WireGuard 接入评估
+
+| 字段 | 内容 |
+|---|---|
+| 版本 / 变更级别 | 0.1 / S3（未来涉及设备凭据、系统路由和隧道权限） |
+| 设计状态 | Draft |
+| 实现状态 | 客户端骨架、只读本机工具检测及托盘入口；拨号功能未实现 |
+| 负责人 / 日期 | 待指定 / 2026-10-21 |
+| 关联需求 | 仓库根目录新增 `client/`，Rust + Tauri v2 桌面客户端，优先对接 WireGuard |
+| 批准状态 | 用户要求评估并新增客户端；后续接口契约尚待确认 |
+
+## 1. 背景、目标与范围
+
+- **当前行为与证据**：[服务端路由](../../backend/internal/api/api.go)的 `/api/login` 是管理账号登录，`/api/tunnels/:id/wireguard/peers` 的读写与配置下载需要 operator 以上角色；[WireGuard 实现](../../backend/internal/service/wireguard/wireguard.go)可以为管理端生成 Peer 私钥和 `.conf`，新增/删除 Peer 会停止再启动正在运行的隧道。节点 API `/api/nodes` 是管理节点信息，尚不是面向终端用户的可用线路目录。
+- **目标**：参考 `../opsxshell` 与 `../opsxapi` 的桌面项目形态，在 `client/` 建立独立 Tauri v2 + Rust + React/TypeScript 项目；第一阶段只做可验证的真实服务健康检查和清晰的接入状态；给出后续控制面/数据面改造顺序。
+- **非目标**：第一阶段不使用管理员令牌给终端用户创建 Peer，不自动安装驱动、修改本机 DNS/路由或连接 VPN，不兼容飞连私有协议，不宣称飞书/LDAP 用户已经能领取 WireGuard 设备配置。
+- **保留行为**：现有 `frontend/` 管理后台、现有 WireGuard 隧道和已经签发的 Peer 均不改变；服务端 Go 与桌面 Rust 独立构建。
+
+## 2. 需求与约束
+
+- FR-01：桌面端可输入控制面 HTTPS 地址，使用 Rust 命令调用现有 `/api/health` 并显示真实结果；仅允许明确的本机 HTTP 开发地址。
+- FR-02：界面将“服务已可达”与“用户已登录/隧道已连接”分开显示；尚无客户端 API 时连接控制不可触发拨号，预览节点及延时必须在界面显著标记为演示数据。
+- FR-02a：桌面端采用蓝白灰连接概览、窄侧栏和独立线路弹窗；预览延时以绿、黄区分，但不伪装为实时测量。只有真实健康检查可展示控制面往返耗时，且明确不等于 VPN 节点延时。
+- FR-02b：托盘明确显示未连接，并提供打开窗口与退出；设置页只读检查本机 PATH 中是否存在 `wg`、`wg-quick`，不得把工具存在等同于可拨号或已连接。
+- FR-03（后续）：专门的终端用户认证、MFA/OIDC 与短期设备令牌；区分管理员和拨号用户，过期、退出及设备撤销有可验证行为。
+- FR-04（后续）：由桌面端生成并保管 WireGuard 私钥，只上传公钥；服务端按用户/设备身份分配地址、Peer、路由及 DNS，签发有限时配置并处理回收。
+- FR-05（后续）：针对 Windows/macOS/Linux 的系统隧道、权限、路由/DNS 回滚和断线恢复逐平台交付；首版仅标准 WireGuard UDP。
+- NFR-01：应用不能请求广泛的 shell/filesystem 权限；客户端机密不进入前端源码、日志或仓库。桌面应用与管理 API 使用不同鉴权边界。
+- NFR-02：健康检查超时且 TLS 默认验证证书；失败时展示可读原因，不把网络失败当 VPN 连接失败。
+
+## 3. 架构与取舍
+
+```text
+React 页面 → Tauri invoke → Rust 命令/服务 → opsx-vpn 控制面 HTTPS
+                                                │  登录/授权/设备与 Peer（后续）
+                                                └→ 标准 WireGuard UDP 网关
+Rust 系统隧道适配层（后续） ← 仅在本机保存的 WireGuard 私钥
+```
+
+- 客户端采用 `client/src` + `client/src-tauri`，参考同族项目的轻量 Tauri v2 壳，不复制其 SSH/HTTP 工作台或许可证逻辑。UI 使用 React + TypeScript；网络请求由 Rust 执行，避免将控制面令牌交给 WebView。
+- UI 参考用户提供的蓝白灰截图与 Clash Verge Rev 的桌面交互分层思路；Clash Verge Rev 是 GPL-3.0-only，未复制其源码和视觉资源。线路列表目前是固定的演示内容，选择仅更新当前页面状态，不写入持久配置、不进行网络探测或拨号。
+- `corplink-rs`、`Client_UI_for_Corplink` 与 PinkD 的 `wireguard-go` 面向飞连私有控制协议；现有 opsx-vpn 使用 Linux `wg`/`wg-quick` 和标准 WireGuard。不要引入 `protocol_version` 等私有扩展或假设它们兼容。SOCKS5/netstack、WireGuard over TCP 另行评估。
+- 可选的近期验证路线：由管理员在现有管理端下载独立测试 Peer 配置，再用目标 OS 的标准 WireGuard 客户端验证网关；桌面端的自动拨号必须等设备 API 和权限模型明确后再做。
+
+### Clash Verge Rev 参考范围与接入顺序
+
+已只读核对本地 `../demo/clash-verge-rev` 的 `src-tauri/src/lib.rs`、`ipc.rs`、`feat/tun.rs`、`core/tray/`、`core/service.rs`、`core/updater.rs` 与 Tauri 配置。其 Tauri IPC 类型与命令集中管理、托盘状态、服务可用性检测、配置写入失败恢复以及按平台拆分是可参考的**设计方式**；该项目的系统代理、Mihomo TUN/服务、订阅配置及更新地址都不能直接用于 opsx-vpn。其 GPL-3.0-only 源码、图标和界面资源不复制进当前仓库。
+
+| 顺序 | 借鉴方向 | opsx-vpn 需要自行实现或验证的前置条件 |
+|---|---|---|
+| 1 | Rust IPC 边界、连接状态模型、节点选择、托盘显示 | 先有独立的终端用户身份/设备授权 API；托盘只能根据真实握手与系统隧道状态宣称“已连接”，演示数据不能进入托盘 |
+| 2 | 服务可用性检查、失败恢复、跨平台权限管理 | 使用目标系统支持的**标准 WireGuard** 隧道方案，分别验证安装/卸载、DNS/路由保存与恢复、崩溃及重启行为；不以 Mihomo TUN 或系统代理开关替代 WireGuard |
+| 3 | 配置存储与更新流程 | 私钥在客户端安全存储，令牌按平台凭据库管理；普通偏好与机密分离。具备签名、可信发布地址和回滚策略后才添加自动更新 |
+
+`corplink-rs` 仅在明确提出**兼容飞连官方服务**且确认私有协议、许可与长期维护成本后作为研究参考，不能作为本项目认证或隧道实现的基础。当前项目的认证对象是 opsx-vpn 自己的 LDAP/飞书用户，需由 opsx-vpn 签发客户端设备身份；飞连企业识别码、Cookie、私有 WireGuard 扩展字段不属于本项目契约。
+
+## 4. 接口、数据与配置契约
+
+- 第一阶段复用 `GET /api/health`，不新增服务端 API、不改变数据库或现有 Peer 数据。
+- 桌面原生命令 `get_system_readiness` 返回操作系统和 PATH 中 `wg`、`wg-quick` 文件存在性；不执行这些工具、不申请特权，也不访问 VPN 凭据。托盘当前仅提供未连接静态状态、打开与退出，未来需绑定真实隧道状态机后才能展示连接状态。
+- 桌面 `check_server(base_url)` 只返回地址、是否可达及错误，不持久化用户口令或令牌。默认不配置公网地址；用户自行填真实 HTTPS 域名，开发时允许 `http://127.0.0.1` / `http://localhost`。
+- 后续拟新增独立的客户端 `/api/client/*` 契约：登录/续期、可用线路、设备注册（公钥、设备标识）、设备吊销、连接配置领取及状态。响应不下发服务端私钥，客户端私钥不上传。接口形状、LDAP/飞书绑定与授权范围在实现前另行确定。
+- 配置下载目前包含由服务端保存的客户端私钥，不得将管理员下载接口直接暴露给桌面端；现有管理员 `/api/login` 不等价于终端用户准入。
+
+## 5. 风险与验收
+
+| 风险或失败场景 | 处理方式 | 可观察信号 |
+|---|---|---|
+| 把管理 token 当拨号凭据 | 另建按用户/设备授权的控制面；第一阶段仅匿名健康检查 | 无管理 API 调用 |
+| 设备私钥从管理配置泄漏 | 后续客户端生成密钥、公钥注册及撤销；不直接调用管理下载接口 | 设备 API 与密钥审计 |
+| Peer 更新影响现有连接 | 后续用 `wg set` 等增量更新并测试掉线影响，再启用自动注册 | 连接连续性、审计日志 |
+| Windows/macOS/Linux 权限差异 | 按平台单独设计特权 helper、安装与回滚；第一阶段不创建 TUN | 平台专项验收 |
+
+| AC | 对应需求 | 前置与操作 | 预期结果 | 验证方式 | 状态 |
+|---|---|---|---|---|---|
+| AC-01 | FR-01, NFR-02 | 输入有效/无效/非本机 HTTP 地址并点检测 | 真实健康结果、错误与拒绝行为明确 | Rust 单测、桌面手动试连 | 地址校验及本机健康接口测试通过；真实服务与桌面手动试连待做 |
+| AC-02 | FR-02, FR-02a, NFR-01 | 打开桌面端并切换线路 | 蓝白灰界面、绿黄演示延时、显著的演示标记；可见未接入，不会调用管理 API 或修改系统 | UI 构建、代码检查、桌面演示启动 | UI 构建通过；桌面 demo 进程已启动，手动视觉验收待做 |
+| AC-02b | FR-02b, NFR-01 | 在桌面端打开托盘并访问设置页 | 托盘显示未连接，能打开/退出；本机工具存在性仅标注为 PATH 检查结果 | 原生构建、桌面手动检查 | UI 构建及 Rust 测试通过，Tauri 开发进程已重启；托盘点击与设置页人工验收待做 |
+| AC-03 | FR-03 | 普通用户/MFA/过期令牌/撤销设备 | 仅已授权设备可领取配置 | 后续 API 集成测试 | Not Run |
+| AC-04 | FR-04 | 同一用户多个设备注册/注销 | 各设备独立密钥、Peer、地址与审计 | 后续真实网关联调 | Not Run |
+| AC-05 | FR-05 | 各 OS 正常连接与异常退出 | 路由/DNS 可恢复，不影响已有连接 | 后续目标 OS 实机验收 | Not Run |
+
+## 6. 发布与恢复
+
+- 第一阶段仅新增 `client/`，不修改服务器进程、不申请系统特权；构建检查与桌面手动健康检查后才能称为可运行。
+- 2026-10-21 已经管理 API 在现有服务器上创建停止状态测试专线 `opsx-client-pilot`（ID 4），配置与只读核验见 [WireGuard API 创建记录](../wireguard-api-create.md)。该资源尚未启动，不代表桌面客户端可以认证或连接；启用前确认云安全组与目标路由。
+- 后续按“独立客户端身份 API → 设备注册/增量 Peer 更新 → Linux/Windows/macOS 原生隧道”逐步交付；先在独立测试 WireGuard 隧道验证。
+- 若后续客户端版本故障，先禁用其设备访问凭据并停用客户端，保留现有管理后台与隧道；数据迁移需独立备份和回滚方案。
+
+## 7. 待决问题
+
+| 问题 | 是否阻塞第一阶段 | 建议 |
+|---|---|---|
+| 首发 OS 与安装包签名 | 不阻塞骨架 | 先选一台真实目标 OS 验收，再扩平台 |
+| 企业账号映射到 VPN 权限、MFA/OIDC 与设备配额 | 阻塞自动拨号 | 稳定用户 ID + 单独设备授权策略，不按同名邮箱猜测 |
+| 会话断开是否自动注销 Peer | 阻塞自动拨号 | 区分临时连接与已授权设备；明确租约、续期与撤销 |
+| 是否需要代理模式/TCP/飞连兼容 | 不阻塞标准 WireGuard UDP | 先证明原生 WG 客户端与当前网关互通 |

docs/specs/SDD-003-domain-tls.md

@@ -0,0 +1,76 @@
+# SDD-003：域名与 HTTPS 证书管理
+
+| 字段 | 内容 |
+|---|---|
+| 版本 / 变更级别 | 0.1 / S3（证书私钥、网络入口及生产代理配置） |
+| 设计状态 | Draft |
+| 实现状态 | 应用内 ACME、域名设置与管理员状态页已实现，本地构建/单测通过；生产端口/证书待部署验证 |
+| 负责人 / 日期 | 待指定 / 2026-10-21 |
+| 关联需求 | `test-link.appx365.com` 使用 HTTP-01 自动签发和续期；管理后台提供域名及证书页面；桌面客户端可使用 HTTP 或 HTTPS，并在设置中填写地址 |
+| 批准状态 | 用户要求开发与评估；生产入口切换以部署核验为准 |
+
+## 1. 背景、目标与范围
+
+- 当前行为：[后端路由](../../backend/internal/api/api.go)在 `:18080` 提供管理站点和 API；[部署文档](../deploy.md)仅描述外置 Nginx/Let's Encrypt 方案，没有集成证书状态页面。桌面 [URL 校验](../../client/src-tauri/src/server.rs)拒绝远端 HTTP，地址位于概览页。
+- 2026-10-21 只读核对：`test-link.appx365.com` 解析到 `121.4.111.208`；服务器没有发现 Nginx、Certbot，80/443 未被监听。
+- 本次目标：使用项目已有的 Go `autocert` 依赖，在现有 Gin 进程中提供公网 80/443、HTTP-01 自动签发/续签；管理 API 和页面展示域名及缓存证书状态；桌面将地址放在设置中，接受 HTTP（提示明文风险）。单域名场景无需 Nginx、Certbot 或额外的 `gin-gonic/autotls` 封装。
+- 非目标：将证书私钥存到 SQLite/浏览器；允许任意命令、代理任意上游、公开认证服务内部端口；向桌面发放管理员 token；把 WireGuard 51820/UDP 交给 Nginx 代理。
+- 保留行为：旧 `:18080` 管理界面与现有 VPN 专线不受证书签发流程影响；证书失败保持现有 HTTP 服务可用。
+
+## 2. 需求与约束
+
+- FR-01：管理员能查看当前域名、DNS、监听地址、证书颁发者/到期日；接口不返回私钥、登录凭据或证书正文。
+- FR-02：服务端仅为管理员保存的域名或 `VPN_TLS_DOMAIN` 指定的单一有效域名签发（环境变量优先），ACME 使用该域名 HostWhitelist；首次 HTTPS 握手签发，证书与账号密钥持久缓存于 `data/acme`，禁止任意域名签发。
+- FR-03：续签由 `autocert.Manager` 自动管理；重启后缓存证书由首次握手加载并继续续签，到期日由管理页显示；签发或续签失败保留已有 18080 HTTP 入口。
+- FR-04：HTTP 80 通过 `autocert.Manager.HTTPHandler` 放行 HTTP-01，其他当前域名请求重定向 HTTPS；443 用同一 Gin handler 提供管理站点与 API。OIDC 认证入口若另设域名需另行设计其路由，不从后台域名假设回调。
+- FR-05：桌面客户端服务端地址移到“设置”，支持完整 HTTP/HTTPS 根地址并允许保存；HTTP 展示风险提示，但健康检查可以执行。不保存账号和令牌。
+- NFR-01：管理 API 仅 `admin`，域名符合严格 FQDN 白名单；私钥缓存目录权限 0700，不暴露证书缓存内容或触发任意命令。
+- NFR-02：部署前核对 DNS、云安全组 TCP 80/443、端口占用、现有入口与回退；续签有可观测到期信息。浏览器页面与 Tauri 环境的 URL 校验一致。
+
+## 3. 架构与方案
+
+```text
+Internet TCP 80 → autocert HTTPHandler（HTTP-01；其余跳转 HTTPS）
+Internet TCP 443 → autocert TLSConfig → 同一 Gin 管理站点 / API
+ACME 密钥与证书 → data/acme（重启保留）
+管理页面 → admin API → 仅读 DNS、域名及证书缓存元数据
+旧 TCP 18080 → 同一 Gin handler（保留兼容；后续限制公网访问）
+```
+
+使用项目已存在的 `golang.org/x/crypto/acme/autocert`，无需额外 Gin 插件或依赖：管理员将域名保存到 `data/tls-domain`，重启后生效；`VPN_TLS_DOMAIN` 优先于文件配置，`VPN_TLS_HTTP_ADDR` / `VPN_TLS_HTTPS_ADDR` 可覆盖监听地址；未配置域名时完全保留旧启动行为。证书管理不写入业务数据库。首次公网 HTTPS 请求后才有真实缓存证书，管理页未签发前必须显示“等待首次访问”，不能声称证书已签发。HTTP 客户端输入只是用户选择；登录与设备令牌将来仍应推荐 HTTPS。
+
+## 4. 接口、数据与配置契约
+
+- `GET /api/system/tls` 与 `PUT /api/system/tls/domain` 仅管理员可用，分别读取状态与保存单域名；状态返回当前/待启用域名、是否需重启、DNS、监听地址及 autocert 缓存证书的颁发者/到期日。没有手动签发按钮，首次 TLS 握手会触发签发。证书缓存位于 `data/acme`，不接收请求任意域名作为签发目标。
+- 云安全组 TCP 80/443 与 DNS A 解析须对应当前服务器；`VPN_TLS_DOMAIN=test-link.appx365.com` 生效时若端口占用，应用拒绝启动并保持旧进程可回滚。
+- 桌面仅在本机保存不含凭据的服务端地址；只允许 `http` / `https` 和根地址，拒绝 URL 账号、查询、片段、非根路径；实际健康检查继续调用 `/api/health`。
+
+## 5. 风险与验收
+
+| 风险或失败场景 | 防护 / 恢复 | 可观察信号 |
+|---|---|---|
+| 域名指向错误或 80 不可达 | 不启用证书前先核对 DNS 和公网入站；失败保留旧 18080 | ACME 错误日志、证书未缓存 |
+| 80/443 端口占用 | 启动时先绑定两个端口，失败则终止新版进程并回退旧版 | 启动日志与端口监听 |
+| 续签失败与证书过期 | autocert 自动续签、到期日提示、缓存保留 | 证书到期信息与 ACME 日志 |
+| 公网 HTTP 管理凭据泄漏 | HTTPS 默认推荐；明示 HTTP 风险；服务端切换后限制 18080 公网 | HTTPS 可达、18080 仅可信入口 |
+
+| AC | 对应需求 | 前置与操作 | 预期结果 | 验证方式 | 状态 |
+|---|---|---|---|---|---|
+| AC-01 | FR-01, NFR-01 | 管理员/非管理员请求状态 | 仅管理员可查看，证书私钥不回传 | 路由权限检查；线上请求待验证 | 部分验证 |
+| AC-02 | FR-02, NFR-01 | 设置非法域名或端口占用 | 启动前拒绝，不向任意域名申请 | 域名/端口失败分支单测 | 已通过（本地） |
+| AC-03 | FR-03, FR-04, NFR-02 | 首次 HTTPS 请求与后续续签 | HTTP-01 可达、443 站点正确、缓存保留与自动续签 | DNS、ACME、TLS 实机验证 | Not Run |
+| AC-04 | FR-05 | 桌面保存远端 HTTP/HTTPS 并检测 | 地址保存在设置；HTTP 提示且能检测，其他协议拒绝 | Rust 单测、UI 构建；桌面实机待验证 | 部分验证 |
+
+## 6. 发布与恢复
+
+- 先完成本地构建和测试，备份现有二进制、确认公网 80/443 无占用及云安全组策略，再配置 `VPN_TLS_DOMAIN` 并切换新二进制。以 `https://test-link.appx365.com/api/health` 触发首次签发；确认 TLS 域名、证书到期和管理站点之后收敛 18080 公网权限。
+- 若端口监听、HTTP-01 或首次握手失败，恢复原二进制/启动参数并重启旧 `:18080` 入口；`data/acme` 保留避免重复申请。不修改现有 VPN 网关或删除证书缓存。
+- 私钥文件和用户数据不删除；证书吊销、DNS 变更及防火墙收敛分别决策。
+
+## 7. 待决问题
+
+| 问题 | 是否阻塞 | 推荐方案 |
+|---|---|---|
+| 云安全组 TCP 80/443 是否放行 | 阻塞线上 HTTP-01 | 先核实公网访问再签发 |
+| `test-link.appx365.com` 是否同时承载 OIDC 认证服务 | 不阻塞管理站点 | 初版仅反代管理站点；OIDC 独立域名或另行设计路径路由 |
+| 证书到期告警 | 不阻塞本地实现 | 当前页面展示到期时间；后续可补主动告警 |