Files
WebUp Cloud 2f93fb023a
Verify control plane / verify (push) Canceled after 0s
Verify control plane / verify (pull_request) Canceled after 0s
Add administrator-controlled IP project entry redirects
2026-11-08 12:25:01 +08:00

67 lines
5.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 项目域名与 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)。