跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

自定义域名

最后更新 查看 MarkdownAgent 设置

自定义域名会用你拥有的主机名(例如 search.example.com)提供 公共端点,而不是默认的 <PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com 主机名。

端点与请求格式不变,仅主机名会变化:

https://search.example.com/search
https://search.example.com/chat/completions
https://search.example.com/mcp

自定义域名也是 使用 Cloudflare Access 限制访问 的基础,可让用户在查询已索引内容之前先通过身份提供商进行身份验证。

要求

  • 必须已在实例或 namespace 上启用公共端点。向没有活动公共端点的实例添加自定义域名会返回错误 7093。
  • 主机名必须属于 已添加到同一 Cloudflare 账户 且处于活动状态的 zone。其他账户上的主机名会返回错误 7090。
  • 每个实例或 namespace 支持一个自定义域名。
  • 一个主机名一次只能附加到一个公共端点。重复使用主机会返回错误 7091。
  • 主机名必须是最多 253 个字符的完全限定域名,例如 search.example.com。不支持通配符。主机名以小写存储。

添加自定义域名

在创建或更新实例时设置 public_endpoint_params.custom_domains。

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/default/instances/<INSTANCE_NAME>" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_endpoint_params": {
      "enabled": true,
      "custom_domains": ["search.example.com"]
    }
  }'

namespace 上也有相同字段。请参阅 Namespace 公共端点。

Cloudflare 会为该主机名签发证书,并开始域名控制验证。

创建 DNS 记录

在拥有自定义域名的 zone 中创建 已代理 的 CNAME 记录。目标是公共端点的默认主机名,即 <PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com。

Type Name Target Proxy status
CNAME search <PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com Proxied
curl -X POST "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/dns_records" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CNAME",
    "name": "search",
    "content": "<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com",
    "proxied": true
  }'

域名控制验证完成后,自定义域名开始提供流量。

关闭默认主机名

默认情况下,公共端点会同时在自定义域名和默认的 <PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com 主机名上响应。将 default_domain_enabled 设为 false,即可仅通过自定义域名提供服务。默认主机名随后会返回带有错误 60018 的 404。

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/default/instances/<INSTANCE_NAME>" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_endpoint_params": {
      "enabled": true,
      "custom_domains": ["search.example.com"],
      "default_domain_enabled": false
    }
  }'

当你在自定义域名前放置安全控制时,请关闭默认主机名。这些控制运行在你自己的 zone 中,因此到达默认主机名的任何流量都会跳过它们。请参阅 Cloudflare Access。

适用三条规则:

  • 没有至少一个自定义域名时,不能关闭默认主机名。该请求会返回错误 7096。
  • 由于 public_endpoint_params 会被完整替换,之后的更新若省略 default_domain_enabled,会将其重置为 true,默认主机名会再次可达。
  • 保持 CNAME 记录指向默认主机名。AI Search 根据客户端请求的主机名进行路由,而不是 CNAME 目标,因此在关闭默认主机名后该记录仍然有效。

移除自定义域名

将 custom_domains 作为空数组发送。Cloudflare 会移除证书并停止路由该主机名。

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/default/instances/<INSTANCE_NAME>" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_endpoint_params": {
      "enabled": true,
      "custom_domains": []
    }
  }'

如果 default_domain_enabled 为 false,在同一请求中移除最后一个自定义域名会返回错误 7096。请先重新启用默认主机名,然后再移除域名。

删除实例或 namespace 会移除其自定义域名和证书。

错误

代码 消息 原因
7090 custom_domain_not_a_verified_zone_on_this_account 该主机名不属于此账户上的活动 zone。
7091 custom_domain_already_in_use 该主机名已附加到另一个公共端点。
7092 custom_domain_provisioning_failed 证书预配失败。请重试请求。
7093 custom_domains_require_an_active_public_endpoint 实例或 namespace 没有活动的公共端点。
7096 disabling_the_default_domain_requires_at_least_one_custom_domain 在没有自定义域名的情况下将 default_domain_enabled 设为 false。
60018 default domain disabled 请求到达了已关闭的默认主机名。

后续步骤

这篇文档对您有帮助吗?