SDD-007：公网入口收敛为 Nginx
| 字段 |
内容 |
| 版本 / 变更级别 |
0.1 / S3（公网监听及旧模式兼容） |
| 设计状态 |
已形成 |
| 实现状态 |
已实现；待生产验证 |
| 负责人 / 日期 |
opsx-vpn / 2026-10-26 |
| 关联需求 |
页面不再展示 Go/Nginx 模式选择；Nginx 统一承接新公网入口 |
| 批准状态 |
用户要求继续实施上述评估方案 |
1. 背景、目标与范围
- 当前行为：
tlsservice.configFromEnvironment 在没有模式配置时默认 autocert；Start 在该模式监听 HTTP-01 与 HTTPS 端口，nginx 模式只运行管理服务；PUT /api/system/tls/mode 可写入任一模式；GatewaySettings.vue 的模式选择与证书申请会写这个配置。生产运行 Nginx，管理端为 18080；此前磁盘模式误设 autocert 导致重启时与 Nginx 争用 80。
- 目标：新安装默认 Nginx，页面只配置协议、地址、端口和证书；不再通过 Web/API 切换监听所有者。已有
autocert 配置维持旧运行行为直到管理员显式迁移。
- 非目标：本次不自动接管现有 Go 直监听实例、不关闭公网 18080（需核对旧客户端）、不修改当前生产域名或证书。
- 保留：HTTP IPv4、自定义端口、Nginx 白名单、证书申请/续签、OIDC 活跃回调保护和旧 Go 模式的启动兼容性。
2. 需求与约束
- FR-01：没有显式模式配置的新实例从 Nginx 模式启动，不绑定外部 80/443；HTTPS 仍要求域名和证书，HTTP 可以 IPv4。
- FR-02：页面移除模式选择和对模式写入接口的调用，展示 Nginx 入口及当前协议/端口；旧 Go 模式显示迁移提醒并禁止页面保存入口和触发 Nginx 证书流程。
- FR-03：移除
PUT /api/system/tls/mode；旧持久化或环境配置 autocert 保留可读并继续按旧方式启动，迁移需管理员按文档停机处理，不能隐式改配置。
- NFR-01：现有 Nginx + HTTPS 站点、管理监听、OpenVPN 认证进程不变；失败时可恢复旧二进制，Nginx 配置不变。
3. 架构与方案
tlsservice 仅把缺省模式改为 nginx，保留读取显式旧模式及旧 listener 代码。后台移除模式写接口并拒绝旧模式通过域名保存误建新入口。前端去掉模式 selector 和 mode PUT 调用，旧模式给出明确迁移提示，要求通过运维流程准备 Nginx 后切换。Nginx 入口继续使用当前渲染、检查、热重载和 Certbot webroot 流程。内网管理端口绑定方式与公网路径白名单为独立任务。
4. 接口、数据与配置契约
GET /api/system/tls 保留 mode 与 configured_mode 字段以兼容旧客户端；PUT /api/system/tls/mode 移除（调用返回 404/405）。data/tls-mode=autocert 和 VPN_TLS_MODE=autocert 仍作为旧配置读取；未配置时默认为 nginx。无自动数据库/文件迁移。- 旧模式运行时
PUT /api/system/tls/domain 返回 409，避免产生重启后意外生效的入口草稿。
5. 风险与验收
| 风险或失败场景 |
防护 / 恢复 |
可观察信号 |
| 旧实例自动切换导致公网中断 |
显式 autocert 保持不变 |
状态仍为 autocert，原 listener 仍工作 |
| 旧模式下误保存新域名 |
API 返回 409，文件不变 |
409、原入口仍响应 |
| Nginx 未安装的新部署没有公网入口 |
页面初始化提示、需明确启用站点 |
站点状态 none，管理端继续运行 |
| 管理 18080 直连绕过白名单 |
保留页面现有告警，后续迁移旧客户端并限制端口 |
management_direct_public |
| AC |
对应需求 |
操作 |
预期结果 |
验证方式 |
结果 |
| AC-01 |
FR-01 |
空配置 Start |
模式 nginx、不绑定 Go 公网监听 |
Go 单测 |
已通过 Go 单测 |
| AC-02 |
FR-02 |
打开公网入口页面并保存 |
无模式控件/模式 PUT，已有 HTTPS 值不变 |
构建及 UI 代码检查 |
构建及代码检查通过；未执行浏览器交互 |
| AC-03 |
FR-03 |
显式旧配置启动、模式 PUT、旧模式改域名 |
保持旧状态；模式 PUT 不可用，域名保存为 409 |
Go/API 单测 |
旧模式读取与 409 单测通过；路由检查通过 |
| AC-04 |
NFR-01 |
远端发布后核对 |
Nginx 80/443、管理 18080、登录页、OIDC 与 OpenVPN 均正常 |
线上只读探测 |
Not Run |
6. 发布与恢复
本地 Go 测试和前端构建后，提交代码并在服务器确认当前托管站点、配置、进程及工作树。备份管理二进制到 /tmp/opsx-vpn-backups，更新代码、编译前后端、精准重启管理进程；不修改生产 tls-mode、域名、证书或 Nginx 站点，不重启 VPN 进程。验证 HTTP/HTTPS/管理端、OIDC discovery 和 OpenVPN 存活。异常时用备份二进制恢复并保留 Nginx 配置。旧 Go 实例迁移另行安排维护窗口：先准备证书与 Nginx 配置及回滚方案，再停 Go 公网监听、将模式改为 nginx、启动 Nginx 和管理进程并核对回调；不得直接在页面切换。
7. 待决问题
| 问题 |
是否阻塞 |
推荐方案 |
| 何时收紧 18080 公网访问 |
否 |
核实旧客户端地址迁移后再改为回环监听并调整安全组 |
