57 lines
4.0 KiB
Markdown
57 lines
4.0 KiB
Markdown
# SDD-006：HTTP 公网入口支持 IPv4 与派生地址
|
||
|
||
| 字段 | 内容 |
|
||
|---|---|
|
||
| 版本 / 变更级别 | 0.1 / S3（公网认证入口地址） |
|
||
| 设计状态 | 已形成 |
|
||
| 实现状态 | 已实现并完成本地验证 |
|
||
| 负责人 / 日期 | opsx-vpn / 2026-10-26 |
|
||
| 关联需求 | 默认选 HTTP；输入 IPv4 121.4.111.208 和端口 28080；Base URL 自动生成并明显不可编辑 |
|
||
| 批准状态 | 用户要求修改 |
|
||
|
||
## 1. 背景、目标与范围
|
||
|
||
- 当前行为：`GatewaySettings.vue` 的表单状态初始为 HTTPS:443，Base URL 是 `computed(buildPublicBase(entry))` 的 readonly 输入；`tlsservice.ValidDomain`、`nginxconfig.RenderWithOptions` 和托管站点解析均拒绝 IP。
|
||
- 目标：没有已保存域名/地址的新表单预选 HTTP:80；管理员可在 HTTP 下填 IPv4 + 自定义端口；Base URL 派生为 `http://IP:port`，呈灰色只读、可复制。已保存配置（特别是当前生产 HTTPS）加载时优先保持原值。
|
||
- 非目标：给 IP 自动签发 HTTP-01 域名证书，或将当前生产入口自动切换为 HTTP。
|
||
- 保留：管理服务仍监听 18080；Nginx 白名单及 OIDC 运行中回调保护继续生效；HTTPS 地址仍必须是有效完整域名。
|
||
|
||
## 2. 需求与约束
|
||
|
||
- FR-01：无已配置入口时预选 HTTP:80；加载既有入口时显示其真实协议/端口，不能静默改写。
|
||
- FR-02：HTTP 支持单个 IPv4 或完整域名；保存、运行状态、Nginx 预览、托管站点识别以及 OIDC URL 均使用同一地址校验与拼接规则。
|
||
- FR-03：Base URL 随协议、地址和端口实时更新，仅展示和复制，不单独保存。
|
||
- NFR-01：拒绝无效 IP、IPv6、伪 IP 与包含 URI/端口的地址；HTTPS 维持现有域名与证书要求，HTTP 警示明文风险。
|
||
|
||
## 3. 架构与方案
|
||
|
||
在 `tlsservice` 保留严格 `ValidDomain` 用于证书/ACME，新增按协议验证公网 Host 的函数：HTTP 可用 IPv4 或域名、HTTPS 仅域名；配置读取、持久化、URL 构造、Nginx 渲染及站点读取共用该函数。UI 初始显示 HTTP，但加载到已保存地址时服从实际配置。Base URL 用 disabled/read-only 风格展示并保留复制按钮。
|
||
|
||
## 4. 接口、数据与配置契约
|
||
|
||
`PUT /api/system/tls/domain` 的 `domain` 字段在 HTTP 下也可存 IPv4；响应 `public_base` 为实际地址。原 `data/tls-domain` 仍存 Host，不新增表或迁移；旧 HTTPS 配置保持兼容。Go autocert 模式仍仅支持 HTTPS 域名。
|
||
|
||
## 5. 风险与验收
|
||
|
||
| 风险或失败场景 | 防护 / 恢复 | 可观察信号 |
|
||
|---|---|---|
|
||
| HTTP 登录明文 | 页面提示；HTTPS 现有配置不自动切换 | 表单及生产 HTTPS 探测 |
|
||
| IP 被误送至 Certbot | HTTPS/Go 模式拒绝 IP，HTTP Nginx 不申请证书 | 400/预览错误及单测 |
|
||
| 活跃 OIDC 回调引用旧 URL | 复用保存时冲突检测 | 409，旧站点保留 |
|
||
|
||
| AC | 对应需求 | 前置/操作 | 预期结果 | 验证方式 | 结果 |
|
||
|---|---|---|---|---|---|
|
||
| AC-01 | FR-01 | 无配置加载、已有 HTTPS 加载 | 分别显示 HTTP:80 与原 HTTPS 配置 | 前端构建/逻辑检查 | 已通过代码检查与构建；未做交互测试 |
|
||
| AC-02 | FR-02, NFR-01 | 用 121.4.111.208:28080 渲染/保存 HTTP，尝试伪 IP 和 HTTPS IP | HTTP 成功；错误输入被拒绝 | Go 单测 | 已通过 Go 单测；未在生产保存入口 |
|
||
| AC-03 | FR-03 | 修改协议、IP、端口 | 灰色只读 Base URL 自动变化且无单独提交字段 | 前端构建/代码检查 | 已通过代码检查与构建；未做交互测试 |
|
||
|
||
## 6. 发布与恢复
|
||
|
||
本地后端测试及前端构建；部署时保留当前 HTTPS:443 和 OIDC 专线，备份程序、数据库及 Nginx 托管站点，再替换管理二进制。验收 `/api/health`、OIDC issuer、登录页、监听端口及 VPN 进程；不在生产执行 HTTP 切换。异常恢复旧二进制和站点，不修改用户的实际公网设置。
|
||
|
||
## 7. 待决问题
|
||
|
||
| 问题 | 是否阻塞 | 推荐方案 |
|
||
|---|---|---|
|
||
| HTTPS IP 证书支持 | 否 | 另行设计证书类型与 IP SAN 验证；本次仅支持 HTTP IPv4 |
|