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

4.0 KiB Raw Blame History Unescape Escape