Skip to content
MGModel Gate
登录开始使用
指导和见解

白标 AI API 端点：自定义域、TLS 自动化和租户安全路由

品牌 AI API 端点需要的不仅仅是 CNAME。构建经过验证的域生命周期，将所有权、证书、DNS 准备情况、边缘路由、API-密钥授权、续订监控和安全卸载分开。

2 分钟阅读Model Gate Editorial Team

指向您网关的客户 CNAME 不会创建生产就绪的品牌端点。 DNS 记录可能会在证书可用之前解析，证书只能在验证记录保持完整的情况下续订，未经检查的 Host 标头可能会将请求路由到错误的租户上下文。

更安全的模型是将每个品牌主机名视为持久的控制平面资源。所有权、证书颁发、DNS 切换、路由激活、暂停和删除都需要明确的状态。在请求时，主机名会缩小允许的租户上下文，而 API 键仍保留授权边界。

将域生命周期分为独立检查

不要使用单个布尔值（例如 verified）表示自定义域。至少跟踪四个独立条件：

  • 所有权： 客户是否证明对主机名具有控制权？
  • 证书： 是否已在边缘颁发并部署有效证书？
  • DNS： 权威 DNS 是否指向预期网关目标？
  • 路由：是否绑定到活动租户和路由配置文件的确切主机名？

这种分离反映了已记录的边缘提供商行为。托管自定义主机名产品可以使用不同的记录和状态来进行主机名所有权和证书验证。因此，仅 DNS 解析并不能证明端点已准备就绪。

实用的状态机是：

requested
  -> ownership_pending
  -> certificate_pending
  -> dns_pending
  -> ready
  -> suspended
  -> draining
  -> deleted

这些是业务状态，而不是提供商状态的直接副本。单独存储提供者的原始状态，然后根据记录的不变量导出您自己的状态。例如，仅当所有权有效、证书处于活动状态、DNS 指向预期目标并且边缘路由已启用时，才标记域 ready。

建议： 在初始激活期间使转换保持单调。短暂成功的 TLS 探测不应跳过所有权验证或路由检查。激活后，协调可能会将域从 ready 移至 suspended，或者在这些不变量不再有效时将域移至显式降级状态。

将域存储为一流资源

操作白标签 AI API 网关 的域记录应包含足够的信息，以便从不明确的 API 调用和提供商中恢复drift:

{
  "domain_id": "dom_01J...",
  "hostname_ascii": "api.customer.example",
  "tenant_id": "ten_01H...",
  "brand_id": "brand_42",
  "state": "certificate_pending",
  "ownership_method": "dns_txt",
  "ownership_record": {
    "name": "_gateway-verify.api.customer.example",
    "value": "verify=..."
  },
  "certificate_status": "pending_validation",
  "expected_cname": "customers.edge.example",
  "routing_profile_id": "route_openai_compatible_v3",
  "provider_hostname_id": "edge_8f2...",
  "creation_operation_id": "op_01J...",
  "last_reconciled_at": "2026-11-02T10:00:00Z",
  "last_reconciliation_result": "certificate_pending"
}

在进行唯一性检查之前，使用 IDNA 感知库将主机名标准化为小写 ASCII。删除尾随点并拒绝 IP 文字、URL 路径、端口、通配符（除非明确支持）以及超出接受的公共后缀策略的名称。仅将提交的显示表单保留为非权威元数据。

对规范化主机名实施全局唯一性约束。两个租户决不能声明相同的权限，即使它们使用不同的大写或 Unicode 表示形式也是如此。

更改生产 DNS 之前进行预验证

当边缘平台支持时，请在要求客户更改生产 CNAME 之前颁发和部署证书。典型的顺序是：

  1. 使用幂等性密钥创建域资源。
  2. 返回所有权和证书验证记录。
  3. 轮询或接收提供程序事件，直到两次验证都成功。
  4. 确认已为确切的主机名部署证书。
  5. 要求客户将生产 CNAME 指向网关目标。
  6. 从多个网络位置解析权威 DNS。
  7. 启用路由并执行经过身份验证的端到端探测。
  8. 标记域 ready。

事实： 托管 SaaS 边缘文档介绍了零停机迁移序列，其中验证和证书颁发发生在生产 CNAME 更改之前。 权衡：这可以避免明显的 TLS 激活间隙，但要求客户创建额外的 TXT、CNAME 或委托验证记录。

如果预验证不可用，请明确暴露可能的中断。仅在流量移动后才开始颁发证书时，请勿承诺零停机时间。

按确切的权限进行路由，然后授权密钥

受信任的边缘应维护从主机名到允许的租户或品牌上下文的精确白名单：

api.customer.example -> {
  tenant_id: "ten_01H...",
  brand_id: "brand_42",
  state: "ready"
}

拒绝未知、不活动和不明确的权限。切勿将它们发送给默认租户。对于HTTP/1.1，验证Host；对于HTTP/2 和HTTP/3，验证:authority。如果 TLS 在同一边缘终止，请将请求权限与代理支持的 SNI 和证书上下文进行比较。

转发标头需要相同的规则。公共边缘应删除传入的 X-Forwarded-Host、Forwarded 和任何内部租户标头，然后添加规范主机和解析的租户信号。源端应仅通过经过身份验证的边到源连接接受这些信号。

运行时授权顺序应为：

  1. 通过活动主机名白名单解析规范化权限。
  2. 独立验证 API 密钥。
  3. 加载附加到源的不可变租户标识符密钥。
  4. 验证解析的主机名上是否允许密钥的租户。
  5. 使用租户和密钥 ID 应用模型、预算、速率限制和路由策略。
  6. 根据这些不可变 ID（而不是主机名）写入使用记录。

这会保留合作伙伴 API 的角色自动化，无需将域管理操作转换为授权快捷方式。

当权限与配置的源或连接上下文不匹配时返回421 Misdirected Request。当主机名有效但经过身份验证的密钥属于不允许使用它的租户时，返回 403 Forbidden。保持错误正文足够通用，以免泄露哪个租户拥有主机名。

规范和品牌端点兼容性

某些客户需要一把密钥才能同时在网关的规范端点及其品牌端点上工作。仅当两个主机名解析为相同的授权租户上下文时，这是可接受的。将每个密钥严格绑定到一个主机名可以减少跨品牌使用，但会使迁移和在端点之间切换的客户端变得复杂。

建议： 模型允许端点上下文作为密钥策略，而不是比较应用程序代码内的字符串。例如，密钥可能允许 tenant:any-active-hostname、brand:brand_42 或一个确切的 domain_id。

通过合作伙伴公开生命周期操作 API

最低限度的 API 应支持创建、检查、重新验证、暂停、恢复和删除：

POST   /partner/v1/custom-domains
GET    /partner/v1/custom-domains/{domain_id}
POST   /partner/v1/custom-domains/{domain_id}/revalidate
POST   /partner/v1/custom-domains/{domain_id}/suspend
POST   /partner/v1/custom-domains/{domain_id}/resume
DELETE /partner/v1/custom-domains/{domain_id}

创建和删除操作应接受稳定的幂等性密钥。提供商 API、DNS 传播和网络超时可能会让调用者不确定操作是否成功。在调用边缘提供程序之前保留操作记录，并在使用相同密钥和等效负载重试请求时返回相同的域或删除操作。

发出签名的生命周期事件，例如custom_domain.verification_required、custom_domain.certificate_active、custom_domain.ready、custom_domain.dns_drifted、custom_domain.renewal_at_risk和custom_domain.deleted。事件是通知，而不是唯一的事实来源；消费者应该能够在错过或重复交付后检索当前状态。

持续协调 DNS、证书和路由

激活并不是生命周期的结束。 DNS 记录被编辑、验证记录消失、边缘配置发生变化以及证书即将续订。

运行定期协调器来检查：

  • 权威 DNS 和预期的 CNAME 或委托目标
  • 提供商主机名和证书状态
  • 证书名称、过期和续订health
  • 是否存在所需的 DNS 验证记录
  • 准确的边缘路由所有权和激活状态
  • 租户当前提供流量服务的资格

经过 DNS 验证的证书自动化可能取决于仍可公开解析的验证 CNAME 记录。在到期前发出警报，而不是假设自动续订始终会成功。

对证书操作使用具有指数退避和抖动的有限重试。保留您直接操作发行的 ACME 账户和订单状态。重复删除和重新创建可能会消耗证书顺序或注册域的速率限制。待处理的主机名记录也可能会消耗提供商配额，直至明确删除。

操作预测： 如果不进行协调，最常见的故障将出现在成功加入后、DNS 编辑、证书续订、提供商端偏差或客户流失期间。这是架构预期，而不是测量的故障率。

分两个阶段卸载

首先删除数据库行是不安全的，因为边缘映射、证书或 DNS 的寿命可能比它长。使用可审核的两阶段工作流程：

  1. 将域移至 draining 并停止将其公布以用于新集成。
  2. 确定现有请求是接受较短的宽限期还是立即拒绝。
  3. 禁用边缘路由，以便主机名无法解析为默认租户。
  4. 从提供商。
  5. 要求客户删除或替换 DNS 记录。
  6. 验证 DNS 是否不再指向您的服务。
  7. 标记资源 deleted，同时保留标识符和审核记录。

针对已取消配置的服务的悬空 CNAME 可能会产生子域接管风险。相反，让过时的映射保持活动状态可以继续通过您的边缘发送前客户的流量。将提供商清理和 DNS 验证结合到同一删除操作中，但独立记录每个结果。

测试边界，而不仅仅是顺利路径

在启用客户域之前，自动执行以下一致性测试：

  • 伪造的 Host 或 X-Forwarded-Host 标头
  • SNI 和 HTTP 权限冲突值
  • 未知主机名和已知但已暂停的主机名
  • 租户 A 的有效密钥用于租户 B 的主机名
  • 使用相同幂等性密钥重复创建和删除请求
  • 使用大小写、尾随点或 Unicode 变体提交的相同主机名
  • DNS 更改为偏离预期目标激活
  • 续订前删除的证书验证记录
  • 在删除边缘映射后但在 DNS 更改之前删除中断

同时验证日志、结算、使用归属、速率限制和政策决策是否使用租户和密钥 ID。主机名是可变的表示和路由输入；它们不应成为财务或安全身份。

实施清单

  • 规范主机名并强制执行全局唯一性。
  • 分别跟踪所有权、证书、DNS 和路由准备情况。
  • 在支持的情况下在切换前预先验证证书。
  • 将受信任的确切权限列入允许列表边缘。
  • 剥离不受信任的转发标头并创建经过身份验证的源信号。
  • 根据主机名的租户上下文授权 API 密钥。
  • 对于源或连接不匹配使用 421，对于跨租户密钥使用使用 403。
  • 进行创建和删除幂等。
  • 持续协调提供商状态、DNS、路由和续订运行状况。
  • 显式删除边缘映射并在卸载期间验证 DNS。

仅当控制平面状态和数据平面行为一致时，品牌端点才准备就绪。显式地对协议进行建模，测试否定路径，并将 API 键保留为最终租户授权边界。

相关阅读

FAQ

常见问题

CNAME 是否足以激活品牌 AI API 端点？
不会。 CNAME 建立 DNS 路由，但生产准备就绪还需要域控制验证、活动证书、精确的边缘映射和成功的授权检查。独立跟踪这些条件。
自定义主机名是否应该确定租户？
主机名可以选择或限制可能的租户上下文，但它不应自行授权请求。独立验证 API 密钥，并在该主机名不允许密钥的租户时拒绝请求。
网关何时应返回 HTTP 421 而不是 403？
当请求权限与为服务器或连接上下文配置的源不匹配（例如 SNI 和主机不匹配）时，请使用 421 Misdirected Request。当主机名有效但经过身份验证的密钥未获得其租户或品牌的授权时，请使用 403。
一个 API 键可以在规范和自定义端点上工作吗？
是的，前提是每个接受的主机名都映射到相同的授权租户上下文，并且密钥策略明确允许这些端点上下文。计费和策略执行仍应使用不可变的租户和密钥标识符。
当客户删除自定义域时必须发生什么？
暂停或排出流量，删除边缘映射和证书关联，验证 DNS 不再以该服务为目标，并保留审核记录。不要将本地数据库行的删除视为完全卸载。
继续阅读

相关文章

查看全部文章 →