61 lines
5.2 KiB
Markdown
61 lines
5.2 KiB
Markdown
# 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 公网访问 | 否 | 核实旧客户端地址迁移后再改为回环监听并调整安全组 |
|