38 lines
4.9 KiB
Markdown
38 lines
4.9 KiB
Markdown
# 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 站点启用及认证域名接入尚未开发成页面一键操作，也未在生产环境执行。
|