SDD-004：客户端企业入口与线路选择

字段	内容
版本 / 级别	0.2 / S3（客户端交互、认证配置安全边界与列表展示）
设计状态	实施中
实现状态	客户端企业入口、能力读取、路由标签、实测隧道探测与信号格、WireGuard 认证配置边界和专线列表已实现；WireGuard 浏览器 OIDC 仍未实现
日期	2026-10-21
关联需求	企业选择、飞书登录入口、模式和节点延迟；WireGuard 认证方式与专线列表操作
批准状态	用户提供竞品截图并要求按现有项目继续实现

1. 背景、目标与范围

当前 client/src/App.tsx 只有服务端地址和密码表单、线路平铺列表。backend/internal/api/api.go 的匿名 /api/client/capabilities 返回 oidc: false；OpenVPN 的 openvpn-auth-oauth2 与 WireGuard 客户端会话互不兼容。backend/internal/api/client.go 的线路含 endpoint，不含节点 RTT；client_probe 是经 WireGuard 到固定公网 TCP 目标的诊断。
目标：以 OpsX 自己的品牌做企业入口、认证选择和节点选择弹窗；用户配置的服务器才是“单位”，不预填竞品单位。只给实测线路显示延迟/颜色和信号格。
本次不新增身份映射、全局路由覆盖或系统 DNS 修改。登录方式与网络模式必须与真实服务端/本机能力一致。保留已有 HTTP 地址支持、密码/MFA 登录、登录会话、设备私钥和连接状态语义。

2. 需求与约束

FR-01：登录页标为“选择接入点”，填写服务端地址并自动带入上次使用的地址；验证真实 /api/health 后进入认证界面。切换接入点清除账号口令，不显示历史地址下拉。
FR-02：根据服务端 /api/client/capabilities 的 password/oidc 能力决定展示入口；password:false 不呈现密码表单，oidc:false 不呈现飞书入口。oidc:true 但客户端浏览器回调未实现时明确禁用，不重定向到 OpenVPN 回调；两者均不可用时提示管理员。未来开启浏览器登录须实现授权码+PKCE、回调一次性交换与稳定 issuer/sub 绑定 VPNUser，禁止按邮箱自动授予线路。
FR-03：线路选择展示服务端真实授权线路；极速/全局用线路下发的路由策略判断。未有可切换策略时模式只是当前策略标记，不保存虚构偏好或擅自修改 AllowedIPs。
FR-04：延迟数据必须来自对应线路的实际 Go WireGuard 探针。探测失败/未登记设备时显示不可测，不得用控制面健康请求替代节点 RTT；阈值只用于实测后的色彩映射。
NFR-01：无效授权与离线不应误报已登录、已连接或高质量节点；浏览器预览不调用原生接口。
FR-05：WireGuard 创建和编辑页展示认证方式：现有“客户端账号 + 设备密钥”可选；第三方 OAuth2/OIDC 显示接入说明且不可选。服务端对显式提交未知模式或 oidc 拒绝保存；旧配置无字段保持原行为。静态 Peer 的已有密钥能力不受此选项保护，页面应如实提示。
FR-06：专线列表和详情显示认证方式；列表启动/停止按钮固定可见，并依据实际运行状态切换；其他协议不臆测认证类型。

3. 架构与方案

前端负责向导和显示；Rust 验证服务端地址、取得 password/oidc 能力并调用当前已有的客户端 API；Go 组件执行真实 TCP 出口探测。按用户选择的运行中线路拨号，后端继续按 VPNUser 授权隔离。节点列表使用现有 /api/client/lines，不造地理位置/服务器名称。OpenVPN OIDC 配置不作为客户端 OIDC 能力来源。

4. 接口、数据与配置契约

匿名 /api/client/capabilities 既有 password/oidc/wireguard 布尔值；可选 oidc_provider 用于将飞书/Lark 与其他 OIDC 提供商区分，旧服务端缺字段按普通“第三方认证”显示。oidc:false 时隐藏第三方认证入口，password:false 时隐藏密码表单；老服务端返回 HTML 则不进入登录步骤。
client_probe 在原结果基础上增加本次成功连接耗时 latency_ms（含隧道启动与握手）；未成功时不提供延迟。前端只为对应线路显示该值，重新选择单位或重新登录后清除。可选 latency_probe 为 VPN 路由内的 IP:端口；未配置时用 223.5.5.5:443。线路接口增加由 AllowedIPs 推断的 routing_mode（split / global_ipv4）；旧服务端缺字段时客户端不推断全局模式。
不修改 SQLite、设备配置或 WireGuard Peer 授权范围。不新增第三方 logo、虚构地区和用户协议链接。
WireGuard 配置新增可选 auth_mode=password；旧记录缺失时按既有客户端账号+设备密钥行为显示。只有 WireGuard 新增服务端枚举校验，oidc 不能写入配置；列表从 JSON 配置读取既有 OpenVPN auth_mode，未知配置显示未指定。启动/停止使用原有 API。

5. 风险与验收

风险	防护 / 恢复	可观察信号
将 OpenVPN OAuth 当 WireGuard 登录	飞书入口根据客户端能力禁用；文案区分两者	`oidc:false` 下无法点击浏览器授权
非法 WireGuard OIDC 配置被误认为安全登录	下拉禁选且后端验证拒绝；保留原设备密钥与静态 Peer 流程	创建/编辑传 `oidc` 返回校验错误
将 HTTP 或隧道探针误称为节点 RTT	清楚标注“隧道 TCP 建链耗时”，未测为中性	无数据时没有绿色/黄色毫秒值
选择全局模式导致错误路由	根据专线真实 AllowedIPs 显示当前策略，未具备切换条件则不可切换	不更改系统路由与专线配置

AC	对应需求	操作与预期	验证方式	结果
AC-01	FR-01	新用户配置地址、检测成功、进入认证；切换单位清空表单	客户端 UI 构建、桌面窗口启动；真实登录需账号验收	构建/启动通过，真实登录待验收
AC-02	FR-02	`oidc:false` 隐藏第三方入口；`password:false` 隐藏密码入口；`oidc_provider=feishu` 显示飞书标签但保持禁用	客户端 UI 构建、能力契约单测；实际账号登录待验收	构建与契约单测通过，实际登录待验收
AC-03	FR-03	运行中线路可选；全局模式不在私网路由上假激活	路由推断 Go 单测、客户端 UI 构建	通过
AC-04	FR-04	真实探测显示毫秒数；失败显示不可测	Go/Rust 测试、真机试验	测试通过，真机延迟/线路切换待验收
AC-05	FR-05	WireGuard 创建/编辑显示两种方式，其中 OIDC 不可选；手工请求 `auth_mode=oidc` 被拒；无字段旧配置可验证	后台构建、Go 单测	通过；界面手工验收待进行
AC-06	FR-06	不同协议列表认证标签正确；运行和停止状态有清晰按钮	后台构建、代码检查	构建通过；界面手工验收待进行

6. 发布与恢复

先验证 Go 服务端再发布前端及桌面客户端；本轮不修改生产网关。若需回退，恢复原服务端/前端构建与桌面客户端构建；新 auth_mode=password 对旧服务端为普通附加字段，旧配置仍可读取。无需迁移数据库或撤销现有授权。

7. 待决问题

正式飞书 OIDC 需要 HTTPS issuer、应用凭据与回调域名，以及管理员确认的飞书 issuer/sub 对 VPNUser 授权映射；没有这些配置不得显示可用的一键登录。全局 VPN 需后续系统隧道权限、NAT 与 DNS 恢复验收。

7.5 KiB Raw Permalink Blame History Unescape Escape