自定义域名（Custom Domains）

用你自己的域名承接 LLM 调用 —— 品牌、合规、白标、抗审、地理调度、零 Lock-in

把 Hydite 默认的 acme.api.hydite.com 换成你自己的 api.acme.com，看似只是一行 DNS，背后却同时解决六个真实问题：

• 品牌一致：所有调用方看到的是「你的 AI 服务」，不暴露 Hydite。
• 白标转售：你做 LLM 中台对外二次售卖时，每个下游客户用自己的域名。
• 合规适配：监管经常按调用域名归属地判定数据流向，自有域名让审计简化一个数量级。
• 零 Vendor Lock-in：业务代码绑定自有域名后，未来要换网关供应商也无需改代码。
• 国内稳定：备案域名比海外域名抗 DNS / 网络抖动。
• 地理分流：api-cn / api-eu 各自做 GeoDNS，把用户路由到最近实例。

本文是从「最简单的子域名替换」到「企业级私网 mTLS + GeoDNS」的完整指南。

1. 三档能力#

下文分别用 ✦ L1 / ✦ L2 / ✦ L3 标注章节归属。

2. ✦ L1 · 平台子域名#

最便捷的入门方式，所有订阅档位均可使用：

控制台 → Workspaces → Domains → Edit Subdomain：

• 自动获取 <your-name>.api.hydite.com，例如 acme.api.hydite.com。
• 证书由 Hydite 自动签发并续期，业务方零运维。
• 支持自定义子域名前缀（受可用性检查与命名规范）。

业务侧调用：

1
client = OpenAI(api_key="sk-hydite-...", base_url="https://acme.api.hydite.com/v1")

适用：刚起步、不需要品牌、对域名归属无强诉求的团队。

3. ✦ L2 · 自有顶级域名#

订阅 Business 及以上档位可绑定任意自有域名。

Step 1 — 在控制台登记域名#

控制台 → Domains → Add Custom Domain 输入 api.acme.com。系统返回三种所有权验证方式（任选其一）：

通过验证后域名进入 Pending 状态。

Step 2 — 配置 DNS 指向 Hydite#

控制台会显示目标 CNAME（如 acme.edge.hydite.com）。在你的 DNS 服务商：

1
api.acme.com.   CNAME   acme.edge.hydite.com.

顶级裸域（acme.com 没有子域）由于 DNS 协议限制不能直接配 CNAME。请用子域名（api. / ai. / chat.），或在 Cloudflare / DNSPod 这类支持 CNAME Flattening 的服务商上启用 CNAME Flattening / Apex CNAME。

Step 3 — 等待 ACME 自动签证#

域名 DNS 生效后，Hydite 自动通过 ACME 签发 Let's Encrypt 证书：

• ⏱ 首次签发：通常 30 秒~5 分钟，取决于 DNS 全网生效速度。
• 🔄 自动续期：到期前 60 天自动 renew，永不过期。
• 🔐 默认启用 HSTS + OCSP Stapling，TLS 1.2 / 1.3。

控制台域名状态由 Pending 变 Active，绿色对勾即可使用。

Step 4 — 绑定 Group（可选）#

默认所有 Group 共享同一个域名。如果你希望按域名做路由（如品牌 A 的域名只走 Group A）：

控制台 → Domains → 绑定 Group → 选择目标 Group。绑定后所有走该域名的请求自动套上对应 Group 的策略包（详见 API Key Groups）。

Step 5 — 业务切流#

1
client = OpenAI(api_key="sk-hydite-...", base_url="https://api.acme.com/v1")

业务零代码改动，5 分钟整套上线完成。

4. ✦ L3 · 自带证书（BYO Cert）#

如果你希望用自己的证书（企业 CA / EV 证书 / 国密证书）：

控制台 → Domains → BYO Certificate：

• 上传 PEM（含 fullchain.pem 与 privkey.pem）或 PKCS12 / PFX 包。
• 系统校验证书指纹、有效期、域名匹配，并返回过期时间。
• 支持配置 TLS 版本范围（最低 1.2 / 1.3）、密码套件白名单。
• 到期前 30 天 Webhook 提醒，不会自动续期（需要你重新上传）。

适合金融、政企、需要走自有 CA 体系的客户。也可与 ACME 混用：默认 ACME，单域名启用 BYO Cert。

5. ✦ L3 · 私网域名（Private Domain）#

只在客户内网 / VPC 内解析的域名，不暴露公网：

• 在客户内网 DNS（CoreDNS / 阿里云私网解析 / Route 53 Private Zone）添加 ai.internal.acme.com → AO 内网入口。
• 配合 Connected Self-Host Agent 模式，业务调用全程不出 VPC。
• 可启用 mTLS 双向证书 —— 客户端必须出示企业 CA 签发的客户端证书才允许调用。

1
# 私网域名配置示例
2
domain: ai.internal.acme.com
3
exposure: private              # 仅内网解析
4
tls:
5
  source: byo                  # 自带证书
6
  client_auth: require         # 强制 mTLS
7
  trusted_cas:                 # 可信客户端 CA
8
    - acme-internal-ca-v3
9
network:
10
  allowed_cidrs:
11
    - 10.0.0.0/8
12
    - 172.16.0.0/12

适合金融生产环境、等保三级、政企内网。

6. ✦ L3 · 多区域 GeoDNS#

把同一个对外域名解析到离用户最近的 AO 实例：

1
api.acme.com   →   GeoDNS:
2
                     • CN 用户 → cn.edge.acme.com  → 华东集群
3
                     • EU 用户 → eu.edge.acme.com  → 法兰克福集群
4
                     • 其它    → us.edge.acme.com  → 弗吉尼亚集群

控制台 Domains → GeoDNS Routing 内置规则编辑器：

• 按 GeoIP 地区 / ASN / 自定义优先级选择目标 Region。
• 健康检查：某个 Region 不健康时自动从池中剔除，60s 内切换。
• 失败回落：用户首选区不可用时，按优先级回落到下一个。
• TTL 控制：默认 60s，可调 30s~3600s。

适合：

• 全球业务，希望用户感知到的延迟最低。
• 跨境数据合规：欧盟用户必须命中欧洲集群、中国大陆用户必须命中境内集群。
• 灾备：主区域故障时自动切到备份区域。

7. ✦ L3 · 多域名（一对多 / 多对一）#

订阅 Business 默认支持 1 个自有顶级域名，企业定制不限制数量。

8. ✦ L3 · CDN 与前置代理#

很多客户已经把 Cloudflare / Akamai / 阿里云 CDN / AWS CloudFront 部署在所有对外域名前。Hydite 完全兼容：

• 直接前置：CDN 把 api.acme.com 反代到 Hydite 边缘 —— Hydite 用 X-Forwarded-For 还原真实客户端 IP，鉴权与限流不受影响。
• 保留鉴权头：CDN 必须透传 Authorization、X-Hydite-* 等头，不要做 Header 改写。
• 不缓存 POST：所有 LLM 调用 POST，CDN 默认不缓存即可；GET /v1/models 等元数据接口可短缓存（< 60s）。
• WebSocket 兼容：流式调用建议直连，不经 CDN（很多 CDN 默认不开 WS / SSE 长连接）。
• HTTP/3 兼容：Hydite 边缘原生支持 HTTP/3 / QUIC，与 CDN 的 HTTP/3 互通无碍。

控制台 Domains → Edge Settings 提供与主流 CDN 的"已知兼容矩阵"，照着配 5 分钟搞定。

9. 一份完整可复制的配置清单#

1
# 一个标准的 Enterprise 客户配置
2
domains:
3
  - host: api.acme.com
4
    exposure: public
5
    tls:
6
      source: acme               # ACME 自动签发
7
      hsts: true
8
      min_version: TLS1.2
9
    routing:
10
      bind_group: prod-api
11
    geo:
12
      cn: cn.edge.acme.com → group=prod-api-cn
13
      eu: eu.edge.acme.com → group=prod-api-eu
14
      default: us.edge.acme.com
15
16
  - host: ai.internal.acme.com
17
    exposure: private            # 仅内网解析
18
    tls:
19
      source: byo                # 企业 CA 证书
20
      client_auth: require       # mTLS
21
    routing:
22
      bind_group: backend-batch
23
    network:
24
      allowed_cidrs: [10.0.0.0/8]
25
26
  - host: api.customer-acme.com  # 白标转售
27
    exposure: public
28
    tls:
29
      source: acme
30
    routing:
31
      bind_group: customer-acme  # 二级客户独立 Group
32
    branding:
33
      logo: https://acme.com/logo-cust.svg
34
      console_subdomain: console.customer-acme.com

10. 运营 Playbook#

域名健康检查

控制台 Domains 列表对每个域名展示：

健康状态变化会触发 Webhook（控制台 Domains → Webhooks）。

切换上游与降级

1
A · 自定义域名 → Hydite 边缘 → AO Routing

任何一段出问题时，业务侧无需改代码：

• DNS / 证书故障 → 控制台 5 分钟切到平台子域名兜底。
• 区域故障 → GeoDNS 60s 自动切到备份区域。
• 想换网关供应商 → DNS 改个 CNAME 即可，业务代码不变。

这正是「自定义域名带来零 Lock-in」的真正意义。

撤销 / 释放#

控制台 → Domain → Release：

• 立即停止接收该域名的请求（5 秒内生效）。
• 解绑 Group、删除证书、清理 GeoDNS 规则。
• 24 小时内可一键恢复，超过 24 小时永久清除。

11. 安全加固：CAA · DNSSEC · CT 监控#

接入企业安全团队时经常被问到的"硬指标"，Hydite 全部原生支持：

CAA 记录（Certification Authority Authorization）#

在你的 DNS 里添加 CAA 记录，明确声明只允许哪些 CA 为该域名签证：

1
api.acme.com.   CAA   0 issue "letsencrypt.org"
2
api.acme.com.   CAA   0 issue "hydite-ca.com"       ; 允许 Hydite 托管 ACME
3
api.acme.com.   CAA   0 issuewild ";"                ; 禁止任何 CA 签发通配符证书
4
api.acme.com.   CAA   0 iodef "mailto:secops@acme.com"  ; 违规尝试时邮件通知

即便攻击者通过社工拿到 DNS 控制权，非白名单 CA 也无法给该域名签证，大幅提升安全下限。控制台 Domains → Security 会定期核查你的 CAA 与实际用的 CA 是否一致，不一致就告警。

DNSSEC#

若你的 DNS 服务商支持 DNSSEC（Cloudflare / Route 53 / DNSPod / 阿里云），强烈建议开启。配合 Hydite 提供的 DS 记录模板，一键在域名注册商侧启用。开启后：

• 防止中间人劫持解析（最典型的"假 CNAME"攻击）。
• 金融监管（等保三级 / PCI-DSS）默认要求。

Certificate Transparency 监控#

所有经 Hydite ACME 签发的证书都会自动写入 CT Logs。控制台 Domains → CT Monitoring 订阅该域名的 CT 事件：

• 任何非预期签发（如 CA 被入侵或钓鱼证书）都会在几分钟内触发告警。
• 保留 2 年历史，可用于事后审计。
• 支持 Webhook 推送到你的 SIEM / 飞书 / Slack。

其它默认开启的加固项

12. SDK 快速参考#

不论哪种语言，切换到自定义域名的方式都一样 —— 只改 base_url。

Python (OpenAI SDK)#

1
from openai import OpenAI
2
3
client = OpenAI(
4
    api_key="sk-hydite-...",
5
    base_url="https://api.acme.com/v1",
6
    timeout=60.0,
7
    max_retries=2,
8
)
9
10
stream = client.chat.completions.create(
11
    model="claude-sonnet-4-5",
12
    messages=[{"role": "user", "content": "Hi"}],
13
    stream=True,
14
)

TypeScript (OpenAI SDK)#

1
import OpenAI from "openai"
2
3
const client = new OpenAI({
4
  apiKey: process.env.HYDITE_KEY,
5
  baseURL: "https://api.acme.com/v1",
6
  maxRetries: 2,
7
})

Go#

1
client := openai.NewClient(
2
    option.WithAPIKey(os.Getenv("HYDITE_KEY")),
3
    option.WithBaseURL("https://api.acme.com/v1"),
4
)

Java (LangChain4j)#

1
OpenAiChatModel model = OpenAiChatModel.builder()
2
    .apiKey(System.getenv("HYDITE_KEY"))
3
    .baseUrl("https://api.acme.com/v1")
4
    .modelName("claude-sonnet-4-5")
5
    .build();

curl（最稳的上线前验证）#

1
curl https://api.acme.com/v1/chat/completions \
2
  -H "Authorization: Bearer sk-hydite-..." \
3
  -H "Content-Type: application/json" \
4
  -d '{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"ping"}]}'

Anthropic Messages 风格#

Hydite 同时兼容 /v1/messages：

1
curl https://api.acme.com/v1/messages \
2
  -H "x-api-key: sk-hydite-..." \
3
  -H "anthropic-version: 2023-06-01" \
4
  -d '{"model":"claude-sonnet-4-5","max_tokens":64,"messages":[{"role":"user","content":"Hi"}]}'

13. 零停机迁移：从平台子域到自有域名#

大客户已经有 N 个业务系统/合作方在用 acme.api.hydite.com，想切换到 api.acme.com 又不能中断。标准做法是双域名并行：

1
Phase 0  (初始)：业务方 → acme.api.hydite.com   (唯一)
2
Phase 1  (并行)：业务方 → acme.api.hydite.com + api.acme.com
3
                            两者都接收流量，共用同一个 Group & Key 池
4
Phase 2  (灰度)：分批次通知业务方改 base_url 到 api.acme.com
5
Phase 3  (单一)：业务方 → api.acme.com   (唯一)
6
Phase 4  (清理)：释放 acme.api.hydite.com（可选）

控制台 Domains → Aliases 直接支持多域名同时在线，同一个 Group 绑定多个 host，证书、限流、审计完全同步。全程零停机、零代码改动（对每个业务方而言只改一次 base_url）。

建议时间表

14. 每域可观测性#

除了基础域名状态，控制台 Domains → Metrics 针对每一个域名单独输出：

API：

• GET /domains/{host}/metrics?range=24h
• GET /domains/{host}/tls-handshakes
• GET /domains/{host}/ct-events

推送到 Prometheus / Datadog / 客户 SIEM 的方式见 Shared Edge · 可观测性。

15. 上线前自查清单#

L2 / L3 域名正式切流前，按这份 10 项清单走一遍，失误率 ≈ 0：

• DNS 在全球主流递归 DNS（114 / 1.1.1.1 / 8.8.8.8 / Ali / Tencent / Quad9）都能解出正确 CNAME
• dig +trace api.acme.com 无异常跳转
• 证书 openssl s_client -connect api.acme.com:443 -servername api.acme.com 输出链完整，Verify return code: 0 (ok)
• HSTS / HTTP 跳转工作：curl -I http://api.acme.com 返回 308 + Strict-Transport-Security
• 业务侧 curl 能成功调通 /v1/chat/completions（带真实 Key）
• 限流生效：用超配额 Key 调用，验证返回 429 + X-Hydite-Limit-Layer
• Group 绑定正确：控制台 Overview 能看到该域名的流量落在预期 Group
• CT Logs 已有本次签发记录，无意外条目
• 备用域名（旧子域）仍然工作（保留至少 2 周做回滚锚点）
• Webhook 告警配好（证书到期、DNS 漂移、CT 异常）

控制台 → Domains → Pre-launch Checklist 会自动帮你跑前 8 项，通过就亮绿灯。

16. 故障排查 FAQ#

Q1 — DNS 已配完 24 小时，控制台仍然 Pending？#

最常见三种原因：

1. 所有者验证没过：dig TXT _hydite-verify.api.acme.com 看是否解析出 Hydite 给的验证串。
2. CNAME 指错：dig CNAME api.acme.com 要匹配控制台显示的目标 host，不要中间再套一层 CDN（会导致 ACME HTTP Challenge 失败）。
3. 裸域强用 CNAME：见 §3 关于 CNAME Flattening 的说明。

Q2 — 证书签发时反复失败，日志显示 urn:ietf:params:acme:error:connection？#

ACME Challenge 被你的安全产品（WAF / Cloudflare Bot Fight Mode）拦了。解决：

• DNS 验证方式改用 DNS-01（在 DNS 里加 TXT，绕过 HTTP）。
• 或在 CDN / WAF 里放行 /.well-known/acme-challenge/*。

Q3 — 客户端偶发 SSL_ERROR_BAD_CERT_DOMAIN / ERR_CERT_AUTHORITY_INVALID？#

• 客户端系统时间不对 → 证书验证对时间敏感，差 > 5 分钟就 FAIL。
• 中间 CA 不在客户端信任库 → 老 Android / 老 Java 可能缺 ISRG Root X1，升级客户端或用 BYO Cert 走客户企业 CA。
• CDN SNI 错发 → CDN 前置时确保 SNI = api.acme.com，不要设置为 CDN 的默认 host。

Q4 — 某个区域用户延迟突然飙升？#

控制台 GeoDNS → Health：

• 若该 Region 状态为 🔴 Unhealthy，GeoDNS 会在 60s 内切走；看切换是否发生。
• 若 Region 健康但用户延迟高，大概率是用户本地运营商 DNS 解析错误（把 CN 用户解析到海外）。可启用 EDNS Client Subnet 或换用 edgedns.hydite.com 托管解析。

Q5 — CDN 前置后返回 421 Misdirected Request？#

CDN 把 Host 头改成了 CDN 内部值。Hydite 边缘基于 Host + SNI 判别 Group，Host 与证书不匹配就返回 421。修复：

• CDN 设置 Preserve Host Header / Forward Original Host。
• 或 CDN 到 Hydite 的回源用 相同 SNI。

Q6 — HTTP/3（QUIC）偶发失败、回退到 HTTP/2？#

• 检查出口防火墙是否放行 UDP/443。
• 移动网络 NAT 超时窗口较短，会被降级回 HTTP/2 —— 正常现象。
• 强制使用 HTTP/2：控制台 Domains → Protocol → disable_h3。

Q7 — 迁移期间同一个业务同时收到两份计费？#

不会。多域名绑定同一 Group 时，所有维度（限流、预算、审计）共享同一账本，按 Key / Group 计费而非按域名计费。控制台 Billing 里"域名"只是维度标签，不会产生二次扣费。

Q8 — 撤销域名后想立刻恢复？#

24 小时内控制台点 Restore，所有配置（证书、Group 绑定、GeoDNS 规则）原样回来。超过 24 小时只能重新走一遍 Step 1~3。

Q9 — 需要通配符证书 *.acme.com？#

L3 档位支持。ACME 通配证书仅能走 DNS-01 验证（不能用 HTTP Challenge），请把 _acme-challenge.acme.com CNAME 委托给 Hydite 自动续期。

Q10 — 企业要求证书过期前 45 天必须通知，且通知 3 次？#

控制台 Domains → Webhooks → Cert Expiry：

• 支持 45 / 30 / 15 / 7 / 1 天多级阈值。
• 通知通道可同时挂飞书 / 钉钉 / Slack / 邮件 / SIEM。
• 对接 ServiceNow / Jira 自动开工单。

17. 档位差异#

18. 反模式#

• ❌ 裸域 CNAME：DNS 协议不允许 acme.com 直接 CNAME，请用子域 api.acme.com 或启用 CNAME Flattening。
• ❌ CDN 不透传 Authorization 头：会导致全部请求 401。
• ❌ CDN 缓存 POST：会让两个客户拿到对方的 completion，严重数据安全事故。
• ❌ 同一域名同时绑定多个 Group：路由策略冲突，请用不同子域或同一 Group 内部分流。
• ❌ 私网域名暴露到公网解析：相当于把内网入口公开。
• ❌ BYO Cert 不监控过期：到期那天全员断网。
• ❌ DNS TTL 设得过长（> 1 小时）：故障切换很慢。

下一步

• 多 Key 治理 → API Key Groups
• 限流与配额 → Rate Limiting
• 接口大全 → API Reference
• 企业级 mTLS / 私网完整方案 → Dedicated Instance