SDD-010：测试环境 OpenVPN 2.7 升级与飞书身份验证

字段	内容
版本 / 级别	0.1 / S3
设计状态	已形成
实现状态	进行中
日期	2026-10-23
关联需求	将飞书认证后的稳定身份写入在线会话，而非显示 `UNDEF`
批准状态	用户明确授权在测试服务器卸载旧版并升级验证

1. 背景、目标与范围

服务器 Ubuntu 24.04 自带 OpenVPN 2.6.19，官方认证组件 2.3.0 的 --openvpn.override-username 明确要求 OpenVPN Server 2.7。现有 openvpn-auth-oauth2.yaml 尚未包含新生成的 oauth2.openvpn-username。参考 vpn-install/openvpn-install/openvpn-install.sh 的官方签名 APT 源方案，但服务器暂时无法连接该源。官方 GitHub 发布了 v2.7.8 源包及 SHA-256 摘要。

目标是在保留现有专线 ID、CA、tls-crypt 密钥、VPN 用户、飞书身份配置和客户端配置的前提下安装 2.7，启用 override-username，用真实重新连接验证状态。仅在确实需要重建时才删除测试专线并重新生成客户端配置；升级不要求重建。不会把 UNDEF 按 IP/时间猜测为某个用户。

2. 需求与约束

FR-01：仅从官方可信发布取得、验证版本和 SHA-256 的 OpenVPN 2.7 构建；保留旧二进制以便回退。
FR-02：内置飞书专线生成稳定 subject 用户名表达式，2.7 时认证组件开启用户名覆盖；外部 OIDC 保持原有配置。
FR-03：重启后既要验证服务端版本和配置，也要验证认证入口及真实客户端重连后的用户名；无法模拟飞书本人授权时如实标注未通过。
NFR-01：现有数据库、密钥、专线实例与证书先备份，生产重启仅影响测试 OpenVPN 专线，故障时恢复旧版本与原配置。

3. 架构与方案

参考安装脚本只借鉴获取官方包的渠道，不运行其初始化、iptables、证书签发与服务文件逻辑，因为这些由 opsx-vpn 管理。优先使用官方签名 APT 源；若网络不通，可校验官方 GitHub Release 的源码摘要并隔离构建到独立目录，先以 --config .../server.conf 检验兼容，再替换可执行路径。先确认认证组件对 override-username 的配置语义与 2.7 服务端支持情况，更新 Go 配置生成和相关测试；专线刷新时沿用原 ID 和 PKI。

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

管理 API 和数据库模型不变。内置发行者的认证组件 YAML 可增加 openvpn.override-username: true，保留 oauth2.openvpn-username: string(token.claims.sub)；只有目标组件和服务端都支持时启用。旧 .ovpn 仍使用原 CA、tls-crypt 和端点，不需重新导入。

5. 风险与验收

风险	防护 / 恢复	观察
网络或依赖不足	不卸载可用的 2.6；保留旧版并停止升级	来源、SHA-256、构建日志
配置语义或 2.7 不兼容	测试二进制和配置、实例及数据库备份、可回退版本	启动日志、监听与健康接口
用户认证期间短时中断	先确认在线连接数并记录维护窗口	状态文件、认证监听
用户身份仍为 `UNDEF`	不推测身份；记录原始状态和组件日志并回滚	真实重连状态 Username

AC	对应需求	操作与预期	验证方式	结果
AC-01	FR-01、NFR-01	官方版本校验成功且回退文件可用	摘要、版本、备份检查	通过：v2.7.8 源包 SHA-256 `c070d1d2440b5a6fca6c2c68645c98cd492116ac36ef4f0946177115532c8e36`；数据库备份 quick_check 为 ok
AC-02	FR-02	内置配置有两个身份选项，外部 OIDC 不变	Go 测试、组件配置解析	通过：Go 全量测试通过，线上 YAML 含两项；外部模式由单测覆盖
AC-03	FR-03	重启后服务健康、OIDC 入口可用	状态、HTTP、日志	通过：2.7.8 服务端与认证组件均运行，本机/公网健康接口通过；组件连接到管理 socket
AC-04	FR-03	真实飞书登录后状态 Username 为稳定 subject，管理端显示对应姓名	客户端重连 + 状态/审计	待验证：重连进入 WebAuth 待授权，尚无本轮成功登录；此时 status 为 `UNDEF`

6. 发布与恢复

先校验包和编译、备份 data/vpn-platform.db、data/secret.key、原实例及当前 OpenVPN 二进制，检查在线客户端；再有序停止测试专线、切换二进制、刷新认证配置、启动。若失败，恢复旧二进制与原实例配置和数据库备份（仅当迁移实际需要），重启原专线，核对监听、Nginx 公网健康、OIDC 回调。清理精确目标，不删除整个 data/；如最终重建，将明确告知旧配置失效并重新下载。

7. 待决问题

官方 APT 源不可达。改用官方 GitHub Release v2.7.8 发布资产，经镜像传输后在本机和服务器两次核对官方摘要；在 /tmp/openvpn-2.7.8 隔离构建，官方 make check 2 项通过、3 项因缺少测试配置跳过。旧 2.6 软件包已卸载，2.7.8 由 data/bin/openvpn 提供；保留 /tmp/opsx-vpn-openvpn-27/openvpn-2.6.19 和整套敏感备份（目录 0700、文件 0600）。
真实飞书登录仍需用户在客户端完成 WebAuth。当前重新连接尚停留在授权等待，UNDEF 是待认证状态，不能据此判定成功身份覆盖；完成认证后再检查 OpenVPN CLIENT_LIST 的 Username 与管理端在线会话及审计。

5.4 KiB Raw Blame History