自定义域名让你可以通过自己拥有的主机名(例如 ai.example.com)发送 AI Gateway 请求,而不是使用默认的 gateway.ai.cloudflare.com 端点。
该主机名会标识你的账户和 gateway,因此可以从请求 URL 中省略账户 ID 和 gateway ID。请求会直接进入 AI Gateway 的提供商原生路由以及 OpenAI 兼容的 compat 路由。
自定义域名也是使用 Cloudflare Access 实现基于身份的控制的基础,可让用户在调用 gateway 之前通过身份提供商进行身份验证。
例如,如果你的自定义域名是 ai.example.com,OpenAI 提供商请求会使用:
https://ai.example.com/openai/v1/chat/completions而不是:
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/v1/chat/completionsOpenAI 兼容端点同样适用。例如,https://ai.example.com/compat/chat/completions 会通过同一 gateway 使用 compat 路由。
要添加自定义域名:
- 在 Cloudflare 仪表板 ↗中,前往 AI > AI Gateway。
- 选择要配置的 gateway。
- 前往 Domains(域名) 选项卡。
- 选择 Add Domain(添加域名) 并输入要使用的主机名。也可以选择子域名。
- AI Gateway 会在仪表板中自动创建 DNS 记录。
域名设置完成后,即可向其发送请求。若要要求用户在调用 gateway 之前进行身份验证,请在该域名上设置 Cloudflare Access。
你也可以通过 Cloudflare API 创建和管理自定义域名。
与仪表板不同,API 不会为你创建 DNS 记录。创建自定义域名后,请使用返回的 cname_target 为你的主机名创建已代理的 CNAME 记录。
curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/ai-gateway/gateways/%7Bgateway_id%7D/custom-domains" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"domain": "ai.example.com",
"zone_id": "395566f4c8a5b9d2a5fc0d457b007c44"
}'响应包含自定义域名状态和 CNAME 目标:
{
"success": true,
"result": {
"hostname": "ai.example.com",
"gateway_id": "my-gateway",
"status": "pending_dcv",
"cname_target": "<cname-target>",
"created_at": 1782925200000,
"modified_at": 1782925200000
}
}在拥有该自定义域名的 zone 中创建已代理的 CNAME 记录。将 content 设为创建自定义域名时返回的 cname_target。
curl "https://api.cloudflare.com/client/v4/zones/%7Bzone_id%7D/dns_records" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"type": "CNAME",
"name": "ai",
"content": "<cname-target>",
"proxied": true
}'自定义域名会保持 pending_dcv 状态,直到域名控制权验证完成。
curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/ai-gateway/gateways/%7Bgateway_id%7D/custom-domains" \
--request GET \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/ai-gateway/gateways/%7Bgateway_id%7D/custom-domains/%7Bhostname%7D" \
--request GET \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/ai-gateway/gateways/%7Bgateway_id%7D/custom-domains/%7Bhostname%7D" \
--request DELETE \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"向自定义域名发送请求,路径中无需包含账户 ID 或 gateway ID:
curl -X POST "https://ai.example.com/openai/v1/chat/completions" \
--header "Content-Type: application/json" \
--data '{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "What is Cloudflare?"
}
]
}'如果该域名受 Cloudflare Access 保护,请求还必须包含有效的 Access 令牌。详情请参阅 Cloudflare Access。
自定义域名尚不支持通过 Cloudflare REST API(api.cloudflare.com)提供的较新 AI Gateway 端点。