公共端点 在设计上是未经身份验证的。知道 URL 的任何人都可以查询你的已索引内容。
在公共端点前放置 自定义域名,并用 Cloudflare Access 保护它。用户随后会先通过身份提供商进行身份验证,请求才会到达 AI Search。这样无需编写认证层,就能将公开知识库变成内部知识库。
自定义域名是你拥有的 zone 中的主机名。当该主机名的 CNAME 记录为 Proxied(已代理) 时,请求会先经过你自己的 zone,再到达 AI Search:
flowchart LR A[Client] --> B["Your zone<br/>Access, WAF, Bots"] B --> C["AI Search<br/>public endpoint"] C --> D[Your indexed content]
Access 运行在你的 zone 中,因此会先评估每个请求。未通过策略的请求永远不会到达 AI Search。AI Search 无需额外配置即可支持这一点,并会在之后应用自己的 速率限制。
这种路由称为 orange-to-orange。它要求 CNAME 记录已代理。DNS only(仅 DNS) 记录会完全绕过你的 zone,Access 不会运行。
- 要保护的实例或 namespace 上已有 自定义域名,且
CNAME记录为 Proxied(已代理)。 - 账户已启用 Cloudflare Access。
- 已将 身份提供商 连接到 Cloudflare Access,或使用 Cloudflare 的一次性 PIN。
Access 只保护你的自定义域名。默认的 <PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com 主机名不会经过你的 zone,因此会继续响应未经身份验证的请求,并使你即将编写的策略失效。
在创建 Access 应用之前,将 default_domain_enabled 设为 false。
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": ["access.search.example.com"],
"default_domain_enabled": false
}
}'默认主机名现在会返回带有错误 60018 的 404。
- 在 Cloudflare 仪表板 ↗ 中,前往 Zero Trust > Access controls > Applications。
- 选择 Add an application > Self-hosted。
- 为应用命名,例如
AI Search。 - 添加自定义域名的公共主机名,例如
access.search.example.com。 - 保存应用。
完整选项请参阅 发布自托管应用。
没有策略的应用会拒绝每个请求。请至少添加一条描述谁可以查询内容的 Allow 策略。
| Action | Rule type | Selector | Value |
|---|---|---|---|
| Allow | Include | Emails ending in | @example.com |
使用电子邮件、国家/地区、IP 范围或身份提供商组 选择器 来匹配你的组织。更多示例请参阅 常见策略。
浏览器会跟随 Access 登录重定向并收到 CF_Authorization cookie。MCP 客户端、后端服务和脚本无法完成交互式登录,因此需要 服务令牌。
-
前往 Zero Trust > Access controls > Service credentials > Service Tokens。
-
选择 Create Service Token,为其命名并选择有效期。
-
复制 Client ID 和 Client Secret。密钥只会显示一次。
-
返回你的 Access 应用并添加第二条策略:
Action Rule type Selector Value Service Auth Include Service Token ai-search-client
在每个请求上以标头发送这两项凭据。
curl https://access.search.example.com/search \
--header "Content-Type: application/json" \
--header "CF-Access-Client-Id: <CLIENT_ID>" \
--header "CF-Access-Client-Secret: <CLIENT_SECRET>" \
--data '{
"messages": [
{
"content": "How do I configure AI Search?",
"role": "user"
}
]
}'{
"mcpServers": {
"ai-search": {
"url": "https://access.search.example.com/mcp",
"headers": {
"CF-Access-Client-Id": "<CLIENT_ID>",
"CF-Access-Client-Secret": "<CLIENT_SECRET>"
}
}
}
}MCP 客户端对标头的支持各不相同。如果你的客户端无法发送自定义标头,请参阅 保护 MCP server 了解基于身份的替代方案,或对命令行请求使用 cloudflared access curl。
没有凭据的请求会返回 Access 登录页,而不是搜索结果:
curl --include https://access.search.example.com/search \
--header "Content-Type: application/json" \
--data '{"messages":[{"content":"test","role":"user"}]}'确认默认主机名已关闭:
curl https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/search \
--header "Content-Type: application/json" \
--data '{"messages":[{"content":"test","role":"user"}]}'响应为带有错误代码 60018 的 404。
- 面向公众网站上的 UI snippets 会停止工作。 UI snippets 会从访问者的浏览器调用公共端点。在 Access 之后,只有通过策略的访问者才能使用它们。对内部站点使用 Access,对面向公众的营销站点保持端点开放。
- 跨源浏览器请求需要 Access CORS 配置。 如果不同源上的页面调用受保护主机名,除了公共端点上的 允许的源 外,还要在 Access 应用上配置 CORS 设置。
- 速率限制仍然适用。 AI Search 会在 Access 之后执行自己的速率限制,并且在所有已认证调用方之间共享。
- 允许的源不是身份验证。
authorized_hosts设置 CORS 响应头,只有浏览器会遵守。它不会阻止来自curl或脚本的直接请求。
一旦 CNAME 记录已代理,其他 Cloudflare 产品也会应用于该主机名:
| 产品 | 用途 |
|---|---|
| WAF 自定义规则 | 允许特定国家/地区、ASN、IP 范围或请求头 |
| 速率限制规则 | 应用超出公共端点限制的按客户端限制 |
| Bot Management | 为自动化流量评分并挑战 |
| Turnstile | 在浏览器客户端调用端点之前验证是否为人类 |