Make Nginx the default public gateway
This commit is contained in:
Codex committed
1 parent
6d5973bea3
commit
ff4c36bcce
10 files changed
+136
-66
No files matched your search
+4
-4
@@ -56,13 +56,13 @@ sudo ss -tlnp | grep ':18080'
|
||||
|
||||
内置方案复用管理域名与证书；先在「设置 → 飞书身份」启用身份服务并同步公网路由，Nginx 仅允许固定 `/id/` 身份路径。创建并启动唯一一条使用当前域名的 OpenVPN OIDC 测试专线后再次同步，才会把 `/oauth2/` 转发到其本机认证组件 `127.0.0.1:19090+`。未启动专线时不会开放 `/oauth2/` 路由。不要把认证端口或 OpenVPN 管理 socket 暴露到公网。详见 [接入说明](../README.md#openvpn-飞书--oidc-浏览器认证)。
|
||||
|
||||
该域名须由你控制并解析到公网入口。管理员可在“设置 → 域名与证书”保存 `test-link.appx365.com`，并选择 Go 或 Nginx 入口模式；`VPN_TLS_DOMAIN` 和 `VPN_TLS_MODE` 环境变量优先于页面配置。两种模式只能选一种来占用 TCP 80/443，保存配置并不会安装 Nginx、开放安全组或签发证书。
|
||||
该域名须由你控制并解析到公网入口。管理员可在“设置 → 域名与证书”保存 `test-link.appx365.com`，由 Nginx 处理公网监听；`VPN_TLS_DOMAIN` 等环境变量优先于页面配置。保存配置并不会自动安装 Nginx、开放安全组或签发证书。HTTP 可以使用 IPv4 与自定义端口；HTTPS 签发仍要求域名。
|
||||
|
||||
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 通畅是两种模式的共同前置条件。
|
||||
旧实例如果显式配置 `data/tls-mode=autocert` 或 `VPN_TLS_MODE=autocert`，仍沿用 Go 直监听 80/443 以避免升级时断网，但页面不再提供切换入口模式，也不允许在旧模式下保存新的公网入口。迁移时先备份入口模式、程序和证书，在维护窗口内准备 Nginx/Certbot 与可回退的站点配置，停用占用公网端口的 Go 管理进程，将入口模式显式改为 `nginx`，启用 Nginx 站点，再启动管理进程并核对登录、OIDC 发现文档、OpenVPN 浏览器回调和证书续签。任何验证失败都应恢复备份的配置、站点和程序。不能只修改模式文件后重启：未准备好站点会让公网入口不可用。新实例未写模式配置时默认为 `nginx`，不会自行监听公网端口。
|
||||
|
||||
### 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，也不会签发证书。
|
||||
“设置 → 首次引导”先检查 root、默认出口、IPv4 转发；管理员可单独启用 IPv4 转发。OpenVPN、WireGuard、IPSec 等依赖仍在“创建专线”选择相应协议时单独安装，不会因进入引导页而批量安装。“Nginx 入口与证书 → 准备 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）：
|
||||
|
||||
@@ -71,7 +71,7 @@ Go 模式（默认）使用 `golang.org/x/crypto/acme/autocert` 监听 80/443，
|
||||
3. 证书签出后程序自动追加 HTTPS 站点、检查配置并重载，同时安装固定续签钩子（`nginx -t` + `systemctl reload nginx`）。确认 Certbot 续签定时器运行，执行 `certbot renew --dry-run` 检查续签；生产验证时再核对 `--run-deploy-hooks` 对钩子的实际效果。证书状态页读取实际的证书到期日；不要仅以站点文件存在判断公网可用。
|
||||
|
||||
2026-10-22 生产实例已启用 `test-link.appx365.com`，证书有效至 2027-01-19，`certbot renew --dry-run --run-deploy-hooks --non-interactive` 模拟续签成功。当前管理服务仍在公网 `:18080` 监听，沿用 HTTP 地址的客户端可绕过 Nginx 的路径白名单；完成客户端地址迁移后，需限制 18080 仅回环访问。模拟续签执行钩子时 `nginx -t` 的正常 stderr 被 Certbot 记录为警告，但退出成功。
|
||||
4. 页面保存入口模式为 Nginx，启动或重启 opsx-vpn 并设置 `VPN_LISTEN_ADDR=127.0.0.1:18080`；确认 `https://<域名>/api/health`、登录及各业务页面可用，未知路径断开，80 的挑战仍可读，然后收紧 18080 公网安全组。若现有业务必须从公网直连 18080，先迁移这些客户端。
|
||||
4. 确认入口模式为 Nginx，启动或重启 opsx-vpn 并设置 `VPN_LISTEN_ADDR=127.0.0.1:18080`；确认 `https://<域名>/api/health`、登录及各业务页面可用，未知路径断开，80 的挑战仍可读，然后收紧 18080 公网安全组。若现有业务必须从公网直连 18080，先迁移这些客户端。
|
||||
|
||||
不要只开放 `/oauth2/callback`：认证组件还需要 `/oauth2/` 下的登录入口。内置身份服务方案通过设置页同步已托管的 Nginx 站点；外部发行者或独立认证域名仍须单独配置，不能直接复用管理站点路径。若代理和 VPN 主机分离，预览里的 `127.0.0.1` 指代理主机自身，应改成受限私网地址并保护传输链路。回退时恢复原 Nginx 配置，运行 `nginx -t` 后重载，不删除 `data/`、签名密钥或已有证书。
|
||||
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# 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 公网访问 | 否 | 核实旧客户端地址迁移后再改为回环监听并调整安全组 |
|
||||
Reference in new issue
Block a user