自定义域名会用你拥有的主机名(例如 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 会为该主机名签发证书,并开始域名控制验证。
在拥有自定义域名的 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 |
请求到达了已关闭的默认主机名。 |