# 项目域名与 HTTPS 当前实现直接入口链路:平台域名分配 / 自定义域名 TXT 验证 → 发布版本中的服务 → Kubernetes Ingress → DNS 核对 → cert-manager 证书核对 → ACTIVE。该实现不是 ESA 自动开通链路;ESA 站点、非标准端口回源、缓存规则和边缘证书自动化仍需补齐。真实 DNS / Ingress / 证书签发尚未联调。 ## 用户与运营页面 - 用户 `/domains`:平台稳定地址、自定义域名 TXT 记录、验证、配置 / 重试、主域名、解绑与执行日志。 - 管理员 `/admin/domains`:用户 / 项目 / 域名查询、执行日志、按原因重试或解绑,`domains:write` 权限与操作审计。 - 平台前缀为 3–63 位小写字母、数字或中划线,拒绝 admin / api / www 等保留名称。正式地址不会随新版本发布而改变。 - 自定义域名经 IDN 规范化,不接受 URL、端口、IP、路径或通配符。TXT 名称 `_webup-challenge.{域名}`,随机值有效二十四小时。未通过验证不创建绑定,不允许覆盖其他项目。 - 域名解绑后保留绑定历史与名称归属,不把悬空解析直接分配给其他租户;跨租户迁移需人工核对,当前无自动域名转移功能。 ## 测试集群准备 1. 部署支持所用网络插件 NetworkPolicy 的 Kubernetes、隔离 RuntimeClass、Ingress 控制器与 cert-manager。 2. 由管理员配置可签发证书的 ClusterIssuer;HTTP-01 / DNS-01 具体挑战方式由该 Issuer 负责。此工程不会猜测 ACME 账户或 DNS 凭证。 3. 部署 `infra/k8s/runtime-rbac.yaml`,重新构建包含 `domain_runtime.py` 的 node-agent 镜像并更新私有网关。 4. 在 `platform-sandboxes` 的 `webup-runtime` ConfigMap 设置 `TLS_ISSUER`(已有 ClusterIssuer 名称)和 `INGRESS_CLASS`(例如 nginx)。网关 Deployment 通过 `RUNTIME_TLS_ISSUER` / `RUNTIME_INGRESS_CLASS` 读取。 5. 配置后端和独立运行 Worker 的 `RUNTIME_URL` / `RUNTIME_TOKEN`;启用 Compose `hosting` profile 或 `RUNTIME_WORKER_ENABLED=true`。令牌使用 Secret,不提交仓库。 6. 在独立管理后台配置部署根域名、项目入口 CNAME 目标,以及阿里云 DNS 凭证、根域名和 TTL。该 CNAME 目标应指向实际 Ingress 入口。 7. 创建项目服务、购买测试套餐、审核网站并成功发布服务,随后配置域名。自定义域名由用户添加 CNAME 或受 DNS 服务商支持的别名解析。 网关镜像固定单进程,示例 Deployment 为单副本;当前域名操作锁不提供多副本分布式一致性保证。不要以该清单宣称多节点高可用已验收。后续多副本支持还需要分布式 fencing 与故障演练。 ## 就绪与失败处理 - `VERIFIED`:名称 / 所有权已确认,尚未开通。 - `QUEUED` / `PROVISIONING`:等待或执行配置。 - `WAITING_DNS`:入口已配置,但 DNS 还未指向预期目标。 - `WAITING_TLS`:DNS 已匹配,证书尚未就绪。 - `WAITING_ROUTE`:DNS 和证书已匹配,入口地址或服务 Pod 尚未就绪。 - `ACTIVE`:上述条件全部通过,并每五分钟重新核对。 - `ERROR`:保留具体阶段错误,最多五次自动尝试,之后需手动重试。 - `REMOVING` / `REMOVED`:入口解绑执行中 / 已确认。 ## IP 项目入口 在「系统设置」填写对外的 IPv4 入口地址,例如 `http://192.0.2.20`。然后在「网站管理与人工审核」为项目开启 IP 入口并填写路径名。浏览器访问 `http://192.0.2.20/student-info` 后,会跳转到该项目已生效的 HTTPS 域名。若有多个可用域名,优先使用主域名。 将该 IP 的 HTTP 流量接到控制面,反向代理需保留请求的 `Host` 和原路径。例如在专用 Nginx 虚拟主机中配置: ```nginx server { listen 80; server_name 192.0.2.20; location ~ "^/[a-z0-9][a-z0-9-]{1,61}[a-z0-9]/?$" { proxy_set_header Host $http_host; proxy_pass http://127.0.0.1:8080; } location / { return 404; } } ``` 将示例 IP 和上游地址换成实际配置。如果入口本身用 HTTPS,代理还需提供覆盖该 IP 的证书。清空系统设置中的入口地址即可关闭所有 IP 入口;也可从网站管理关闭单个项目。 入口只对审核通过、托管套餐有效、部署生效且域名就绪的项目开放。项目被封禁、归档或停运后,入口停止跳转。项目名使用唯一的小写路径名,关闭入口后仍为该项目保留原路径。 ## 域名运行校验 证书核对包含目标域名、Secret 名称、当前 observedGeneration 的 Ready 条件和有效期。Ingress 入口需要控制器报告外部地址;自建控制器需正确配置发布地址。工作负载必须有实际 Ready Pod,不能仅凭创建 API 返回成功就视为上线。 平台域名调用阿里云 DNS 时先查询精确主机记录;已有冲突不覆盖。借用已有正确 CNAME 时不取得删除权。新增记录返回 ID 后才登记由本平台创建;创建超时后无法证明归属的记录按外部记录保留,不冒险清理。解绑只删除明确登记且内容仍匹配的记录;AK 身份改变后保留原记录并要求人工核对。删除重试会先检查记录是否已经不存在。 网关为域名操作记录单调 generation,拒绝旧操作重新创建已解绑入口,并通过资源归属标签和 Kubernetes resourceVersion 检查避免覆盖其他资源。外部写入与数据库之间不是分布式事务,执行日志和幂等核对用于恢复部分成功状态。 API 依据:[阿里云 DNS 记录接口](https://help.aliyun.com/en/dns/api-alidns-2015-01-09-overview)、[精确子域名记录查询](https://help.aliyun.com/en/dns/api-alidns-2015-01-09-describesubdomainrecords)。ESA 后续适配依据:[CreateRecord](https://help.aliyun.com/en/edge-security-acceleration/esa/api-esa-2024-09-10-createrecord)、[GetRecord](https://help.aliyun.com/en/edge-security-acceleration/esa/api-esa-2024-09-10-getrecord)。