feat(tls): add optional nginx setup and gateway preview

docs/deploy.md

@@ -55,7 +55,22 @@ 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-浏览器认证)。
 
-该域名须由你控制并解析到公网入口。管理员可在“设置 → 域名与证书”保存 `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` 指代理主机自身，应改用受限的私网地址，并评估认证流量在私网链路上的保护。
+该域名须由你控制并解析到公网入口。管理员可在“设置 → 域名与证书”保存 `test-link.appx365.com`，并选择 Go 或 Nginx 入口模式；`VPN_TLS_DOMAIN` 和 `VPN_TLS_MODE` 环境变量优先于页面配置。两种模式只能选一种来占用 TCP 80/443，保存配置并不会安装 Nginx、开放安全组或签发证书。
+
+Go 模式（默认）使用 `golang.org/x/crypto/acme/autocert` 监听 80/443，处理 HTTP-01、自动签发和续签；首次访问 `https://test-link.appx365.com/api/health` 才开始签发。证书和 ACME 账号密钥在 `data/acme`，须备份。此模式下 80 的非挑战请求会跳转 HTTPS，443 的管理站点沿用 Gin 路由，**不会**对未知路径执行 Nginx `return 444`。如需严格的公网路径白名单，使用下面的 Nginx 模式。端口空闲、公网 DNS 和云安全组 TCP 80/443 通畅是两种模式的共同前置条件。
+
+### Nginx 模式：HTTP-01 与路径白名单
+
+“设置 → 首次引导”先检查 root、默认出口、IPv4 转发；管理员可单独启用 IPv4 转发。OpenVPN、WireGuard、IPSec 等依赖仍在“创建专线”选择相应协议时单独安装，不会因进入引导页而批量安装。“可选 · HTTPS 公网入口 → 准备 Nginx / Certbot”会读取 `/etc/os-release`，仅在 Ubuntu 使用 `apt-get`、TencentOS Server 4 使用 `dnf` 安装 Nginx/Certbot，并创建 `/var/lib/opsx-vpn/acme/.well-known/acme-challenge`。页面会实时显示安装日志；需以 root 运行平台，其他系统显示不支持。Ubuntu 上如果已有 `/usr/sbin/policy-rc.d`，初始化会拒绝覆盖该文件；安装期间临时阻止软件包脚本自动启动 Nginx，正常结束后移除临时策略。若进程在安装时被强制杀死，检查并移除该临时策略后再试。TencentOS 上安装后也需核实发行版的软件包脚本没有启动默认站点；如发行版仓库没有 Certbot，页面报告失败，由管理员检查软件源。初始化不改写已有站点，不会主动启用 80/443，也不会签发证书。
+
+“预览 Nginx 配置”仅生成当前域名和后端实际注册 API 路由对应的两段站点配置，不会写入系统目录或启动服务。第一段监听 80，仅从 `/var/lib/opsx-vpn/acme` 提供 `/.well-known/acme-challenge/`；其他路径 `return 444`。第二段在证书**已签发后**监听 443：只反代已知前端页面、构建资源和已注册 API，其余路径 `return 444`；未知 TLS 主机名拒绝握手。切换模式必须按以下顺序进行（先备份现有站点，检查是否已有服务占用 80/443）：
+
+1. 可用引导按钮安装 `nginx`、`certbot`，检查云安全组放行 TCP 80/443 和域名 A/AAAA 记录；检查现有 `/etc/nginx/sites-enabled/`，若自带 default 站点占用 `default_server`，先备份并禁用该站点。若 Go 当前监听 80/443，先规划停机切换，不能同时启动 Nginx。
+2. 创建 `/var/lib/opsx-vpn/acme/.well-known/acme-challenge`，让 Nginx 工作账户能读取该目录；将页面预览的 HTTP 段保存为站点文件，先运行 `nginx -t`，再启动或重载 Nginx。先确认挑战路径从公网可读、其他 HTTP 请求断开，再执行 `certbot certonly --webroot -w /var/lib/opsx-vpn/acme -d test-link.appx365.com`。预览中的域名是页面实际配置的域名，替换示例命令中的域名。
+3. 确认证书和私钥存在于 `/etc/letsencrypt/live/<域名>/` 后，追加预览的 HTTPS 段；运行 `nginx -t` 后重载。设置 Certbot 续期定时器和 deploy hook：续期成功时先 `nginx -t`，再 `systemctl reload nginx`。运行 `certbot renew --dry-run` 并确认 hook 的实际生效方式（测试续期时可能需要 `--run-deploy-hooks`）。
+4. 页面保存入口模式为 Nginx，启动或重启 opsx-vpn 并设置 `VPN_LISTEN_ADDR=127.0.0.1:18080`；确认 `https://<域名>/api/health`、登录及各业务页面可用，未知路径断开，80 的挑战仍可读，然后收紧 18080 公网安全组。若现有业务必须从公网直连 18080，先迁移这些客户端。
+
+不要只开放 `/oauth2/callback`：独立的 OIDC 认证域名还要转发认证组件的完整登录流程，且应另为该域名申请证书。管理站点的路由预览不覆盖认证域名；真实认证域名和组件端口确认后单独配置。若代理和 VPN 主机分离，预览里的 `127.0.0.1` 指代理主机自身，应改成受限私网地址并保护传输链路。回退时先恢复原 Nginx 配置及 opsx-vpn 入口模式，运行 `nginx -t` 后重载，不删除 `data/` 或已有证书。
 
 `/.well-known/openid-configuration` 属于发行者域名，不是认证入口上的 VPN 回调。不要只放行 `/oauth2/callback`：认证组件还需要发起登录等路由。认证入口使用独立域名，只反代给认证组件；如需按路径白名单返回 Nginx `444`，须先核对实际安装版本的完整路由，并保障 HTTP-01 验证路径。认证端口默认 19090，仅监听回环；新增 OIDC 专线自动递增并跳过已配置或已监听的端口，仍以启动时冲突检测为准。
 

docs/specs/SDD-004-nginx-acme-entry.md

@@ -0,0 +1,37 @@
+# SDD-004：Nginx 公网认证入口与 HTTP-01
+
+| 字段 | 内容 |
+|---|---|
+| 级别 | S3（公网暴露面、系统服务、证书私钥） |
+| 状态 | 本地实现入口模式保存、首次初始化与路由白名单预览；线上未安装 Nginx/Certbot，80/443 尚未启用 |
+| 已有实现 | SDD-003 的 Go `autocert` 单域名监听已在本地完成，尚未上线 |
+| 目标 | 管理员从页面设置域名并查看证书；可选地由 Nginx 承担 80/443、HTTP-01 和认证反代，未知管理站点路径直接断开 |
+
+## 现状与决定
+
+管理平台在 `:18080`，`openvpn-auth-oauth2` 按专线监听 `127.0.0.1:19090+`。2026-10-21 服务器未安装 Nginx/Certbot、80/443 未监听；公网证书尚未签发。Go `autocert` 与 Nginx 不能同时绑定 80/443，必须将入口模式明确区分。服务器的 `/.well-known/openid-configuration` 属于身份提供方的 issuer，并非本项目的 ACME 站点；不能放行所有 `/.well-known/` 子路径，只需 `/.well-known/acme-challenge/`。
+
+推荐的 Nginx 模式：Certbot `--webroot` 签发，Nginx 提供 HTTP-01 和 HTTPS；Certbot 的系统定时器自动续期，并在证书更新后 reload Nginx。Go 保留 `:18080` 但不监听 80/443。管理站点域名（如 `test-link.appx365.com`）只放行现有 SPA 路由、前端静态资源和 Gin 已注册的 API 路由；其他路径 `return 444`。认证入口应使用独立域名（尚未提供真实域名），反代**所有**认证组件路由到其对应的回环端口；只放行 `/oauth2/callback` 会截断登录发起、状态及错误处理。认证组件的路由清单应在安装具体版本后核对，不能预先硬编码。
+
+## 部署与回退
+
+首次引导增量：设置页将通用网络检查（root、默认出口、IPv4 转发）与可选的 Nginx 入口准备分开；只有管理员点击通用修复时才启用 IPv4 转发。各协议专属依赖仍在“创建专线”按所选协议单独检测、安装。Nginx 卡片只读检测 `/etc/os-release`、root、软件可用性；点击准备后以 POST 流接收逐条进度。服务端只执行 Ubuntu 的 `apt-get` 或 TencentOS Server 4 的 `dnf` 固定安装参数，创建 ACME webroot，不接受客户端命令、路径或包名。单次仅一项任务、各命令有超时；浏览器离开不取消已开始的系统包操作。不会写已有 Nginx 站点配置，也不会假称证书已签出。安装完成后须按下述步骤启用 HTTP 站点并签发。初始化失败保留软件包状态，重新检测后可重试，不删除已有配置。
+
+1. 由管理员先核对域名、云安全组 TCP 80/443、站点冲突、Nginx/Certbot 软件包和 Certbot 续期定时器；如启用 Go 监听，先规划停止 Go 80/443 后再启动 Nginx。页面只保存入口模式和预览配置，不会写入 `/etc/nginx`，也不会实际检测外部代理状态。
+2. 生成最小 HTTP 站点，仅让指定域名的 `/.well-known/acme-challenge/` 从固定 webroot 读取令牌；其他请求关闭。检查 `nginx -t` 后启动 Nginx，用 Certbot `--webroot` 首次签发。
+3. 证书签出后添加 443 站点；Nginx 配置要精确匹配管理站点路由，TLS 默认主机拒绝握手，认证入口仅以独立 Host 转发到 `127.0.0.1:19090+`。`nginx -t` 通过后 reload，再验证合法 API、SPA 深链接、未知路径、HTTP-01、证书域名和到期日。
+4. 验证续期的 `certbot renew --dry-run` 与 deploy hook；失败时恢复原站点配置与原 HTTP 服务，保留 `data/` 和证书缓存。Nginx 模式不把签发结果宣称为 Go `autocert` 的缓存证书。
+
+## 验收
+
+| 编号 | 验证 | 预期 | 状态 |
+|---|---|---|---|
+| NG-01 | 非法 Host、未知管理路径、任意 `/.well-known/` 路径 | 不转发，关闭连接；ACME 路径独立可访问 | 配置单测通过，实机待测 |
+| NG-02 | 登录、MFA、SPA 深链接、管理 API 和静态资源 | 正常访问，仍由平台做身份与权限校验 | 待测 |
+| NG-03 | 认证域名打开登录、回调和认证组件所需路径 | 全流程可达，组件只监听回环 | 待真实认证域名与组件 |
+| NG-04 | 首次签发与续期 dry-run | 证书有效、续期后 Nginx 重载 | 待服务器安装与部署 |
+| NG-05 | Ubuntu / TencentOS 4 首次引导 | 匹配各自包管理器、实时显示输出、并发重复请求拒绝；不覆盖已有站点 | 方案与并发单测通过，实机安装待测 |
+
+## 边界
+
+`return 444` 是 Nginx 的断连响应，不是权限控制；合法接口仍必须由 Gin 鉴权。Go `autocert` 模式不会提供 `return 444`。不能用路径白名单阻断 ACME 续期、MFA 或 WebAuth。认证域名与管理域名若合并，需要重新设计路径分发及 Cookie 隔离，不能直接套用独立域名配置。安装初始化已提供页面按钮；签发、续期、Nginx 站点启用及认证域名接入尚未开发成页面一键操作，也未在生产环境执行。