Files
webup-cloud/docs/DOMAINS.md
T

5.9 KiB
Raw Blame History

项目域名与 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 虚拟主机中配置:

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 记录接口、精确子域名记录查询。ESA 后续适配依据:CreateRecord、GetRecord。