安装 AI 爬虫追踪
面向 Cloudflare、Vercel、WordPress、自建 Node 服务器、Webflow 和 Shopify 的分步安装指南。
本页逐一讲解每种安装方式的具体步骤。爬虫追踪测量什么、验证如何进行,请见 AI 爬虫。同一套安装还会上报由 AI 回答带来的真人访问,因此完成安装后,AI 流量也会随之获得数据;该页面的纯浏览器方案见安装 AI 流量追踪。
根据网站的运行环境选择对应的指南:
| 你的环境 | 使用这份指南 |
|---|---|
| 网站位于 Cloudflare 之后(橙色云代理) | Cloudflare Worker |
| 部署在 Vercel 上的 Next.js 应用(或自托管 Next.js) | Vercel / Next.js 中间件 |
| WordPress 网站 | WordPress 插件 |
| 托管在自己服务器上的自研网站(AWS、GCP、Azure、VPS、容器) | 自建服务器 / Node |
| Webflow 网站 | Webflow |
| Shopify 商店 | Shopify |
开始之前:生成站点密钥
无论使用哪个平台,每种安装方式都需要一个站点密钥:
- 在应用中前往 设置 → 连接 → 网站跟踪。
- 点击生成站点密钥。为密钥命名,最好同时填写它要上报的域名;填写域名还能加强对该网站已签名爬虫的验证。
- 从确认对话框中复制两个值:密钥 ID 和签名密钥(以
ctk_开头)。签名密钥只显示一次;如果丢失,请对该密钥使用轮换,生成新的签名密钥。
请妥善保管签名密钥:任何拿到它的人都可以为你的网站提交伪造的流量上报。Cloudflare、Vercel 和自建服务器的代码片段都从环境变量 CITLYZE_SIGNING_SECRET 读取它,因此它不会出现在你的代码中;WordPress 插件则把它保存在插件设置里。切勿把它提交到代码仓库,也不要粘贴到客户端代码中。
Cloudflare Worker
适用于 DNS 托管在 Cloudflare 且网站已开启代理(橙色云开关)的情况。这是最完整的方案:它能在边缘看到每一个请求,上报真实的 HTTP 状态码,而且无论 Cloudflare 后面运行的是什么都能工作。
- 在 设置 → 连接 → 网站跟踪 → 安装代码片段中打开 Cloudflare 标签页,复制代码片段。
- 将代码片段中的
SITE_KEY_ID替换为你的密钥 ID。签名密钥不要写进代码;你会在第 5 步把它添加为 Worker 机密。 - 在 Cloudflare 控制台中,前往 Workers & Pages → Create → Create Worker。为它命名(例如
ai-crawler-tracker),点击 Deploy 创建一个空的 Worker。 - 点击 Edit code,把自动生成的示例替换为你的代码片段,再次点击 Deploy。
- 添加签名密钥:在该 Worker 中打开 Settings → Variables and Secrets → Add,类型选择 Secret,命名为
CITLYZE_SIGNING_SECRET,粘贴你的签名密钥,然后点击 Deploy。Cloudflare 会加密保存它,它不会出现在 Worker 的代码中。 - 把 Worker 连接到你的网站:打开该 Worker 的 Settings → Domains & Routes → Add → Route,选择你的域(zone),添加路由
example.com/*。如果网站同时通过www.example.com提供服务,请再为www.example.com/*添加一条路由。 - 完成:网站代码无需任何改动。Worker 会把每个请求原样转发到你的源站,并在后台上报符合条件的访问。
有两点需要检查:
- 路由必须覆盖所有路径(
/*),否则将无法看到爬虫对未覆盖页面的访问。 - 如果这些路由上已经有一个 Worker 在运行,由于 Cloudflare 每条路由只执行一个 Worker,请把代码片段的逻辑合并到现有 Worker 中,而不是再添加一个。
Vercel / Next.js 中间件
适用于部署在 Vercel 上的 Next.js 应用。同一个文件也适用于自托管的 Next.js。
- 在 设置 → 连接 → 网站跟踪 → 安装代码片段中打开 Vercel / 代理标签页,复制代码片段。
- 在你的 Next.js 代码仓库中,在项目根目录(如果应用位于
src/,则在src/中)创建middleware.ts,并粘贴代码片段。 - 将
SITE_KEY_ID替换为你的密钥 ID。签名密钥不要写进该文件。 - 在 Vercel 项目中打开 Settings → Environment Variables,为每个需要追踪的环境添加
CITLYZE_SIGNING_SECRET,值为你的签名密钥,并将其标记为 Sensitive。自行托管 Next.js?请在服务器环境中设置同一个变量。 - 如果你已经有
middleware.ts,不要再新建第二个文件,因为 Next.js 只会运行一个。把代码片段中的辅助代码块复制到现有文件中,在中间件函数开头调用其上报逻辑,并确保matcher配置仍覆盖所有路径。 - 提交并部署。
说明:
- 中间件在响应生成之前运行,因此事件的 HTTP 状态会上报为
unknown。这是正常现象。如需状态码,请改用 Vercel log drain 代替此中间件(两者同时使用会把每次访问计算两次),或者使用 Cloudflare 或自建服务器安装方式,它们还会上报重定向。 - 在 Vercel 上,访客 IP 取自平台设置的请求头,可以信任。如果你把 Next.js 自托管在自己的代理之后,请确保代码片段读取的转发 IP 请求头是由你自己的代理设置的,而不是从客户端原样传过来的。
WordPress 插件
适用于任何可以安装插件的 WordPress 网站。
该插件还能免费检查你的 robots.txt 允许哪些 AI 爬虫访问,以及是什么拦截了其余爬虫;参见 WordPress 插件。
-
在 WordPress 后台前往 插件 → 安装插件,搜索 AI Crawler Control by Citlyze,点击立即安装,再点击启用。插件已上架 WordPress.org 官方插件目录,无需上传 zip 文件。
-
想手动安装?在 设置 → 连接 → 网站跟踪 → 安装代码片段中打开 WordPress 标签页,点击下载插件(Download plugin),然后在 插件 → 安装插件 → 上传插件中上传该 zip 文件。
-
前往 Citlyze → Connect Citlyze,填写全部三个字段:
- Tracker base URL:
https://app.citlyze.com - Key ID:你的密钥 ID
- Signing secret:你的
ctk_...签名密钥 填写追踪器基础 URL 之前,插件不会上报任何数据。
- Tracker base URL:
-
点击发送测试事件(Send test event)。你应该会看到“已连接”的确认提示,这说明凭据和网络连接已经端到端打通。
-
网站位于 Cloudflare 以外的代理或负载均衡器之后?在 Visitor IP behind a proxy 中选择代理设置的请求头,并填写代理地址,以便按真实 IP 验证爬虫。如果位于 Cloudflare 之后,则无需任何设置。
插件会在每个页面返回之后上报,并附带确切的状态码,包括在页面渲染前被其他插件重定向的请求。事件会先保存在你的 WordPress 数据库中,再分批发送;Connect Citlyze 页面会显示有多少事件在等待发送,以及最近一次送达的时间。
注意:由全页缓存直接返回的页面、由 Web 服务器或 CDN 完成的重定向,以及在 WordPress 加载前就被防火墙拦截的请求,都不会到达插件。Connect Citlyze 页面检测到页面缓存时会提示你。如果你的网站大量使用缓存,建议改用 Cloudflare Worker 安装方式,或上传服务器日志。
自建服务器 / Node
适用于你自己托管的自研网站:AWS、Google Cloud、Azure、VPS 或容器。该代码片段是面向 Node 20 及以上版本的 Express 风格中间件(也可以在 Bun 和 Deno 上运行)。
- 在 设置 → 连接 → 网站跟踪 → 安装代码片段中打开自建服务器 / Node 标签页,复制代码片段。
- 把它保存为
aeo-tracker.mjs,放在服务器入口文件旁边。 - 将
SITE_KEY_ID替换为你的密钥 ID,并在服务器上将环境变量CITLYZE_SIGNING_SECRET设置为你的签名密钥:可以在托管平台的机密设置中设置,也可以写入一个永不提交的.env文件。签名密钥本身不要写进这个代码文件。 - 在你的路由之前注册中间件:
import { aeoCrawlerTracker } from "./aeo-tracker.mjs"; app.use(aeoCrawlerTracker()); - 如果服务器位于负载均衡器或反向代理(nginx、ALB)之后,请配置 Express 信任它(例如
app.set("trust proxy", 1)),这样中间件上报的才是真实的客户端 IP,而不是代理的 IP。爬虫身份验证检查的正是这个 IP。 - 部署。中间件在每次响应完成后才上报,因此不会增加任何延迟,并且包含真实的 HTTP 状态码。
不用 Express?返回的处理函数接收普通的 (req, res, next) 参数,可以适配 Fastify、Koa 或 Node 的 http 服务器。对于完全不同的语言(Python、Go、PHP、Ruby 等),请实现签名信标协议;每个带签名的 HTTPS POST 请求携带一个批次,最多包含 50 个符合条件的请求。
Webflow
Webflow 自身的托管无法运行服务器端代码,而浏览器端脚本又看不到 AI 训练爬虫,因此追踪需要安装在 Webflow 前面的代理层:
- Webflow 在 Enterprise 套餐中支持自行管理的反向代理;请与你的 Webflow 对接人协商开通,并把域名路由到你的代理(Cloudflare、CloudFront、Fastly 或你自己的 nginx)。
- 在该代理层安装追踪器:
- 代理在 Cloudflare 上 → 按照 Cloudflare Worker 指南操作。
- 你自己的 Node 代理 → 按照自建服务器 / Node 指南操作。
- 其他情况 → 在你的代理中实现签名信标协议。
- 按照下文所述进行验证。
Webflow Cloud 应用无法实现全站追踪:它们只处理挂载路径下的请求,永远看不到爬虫对常规页面的访问。
Shopify
标准 Shopify 店面无法运行此追踪器:Shopify 不允许商家在店面请求上运行服务器端代码,也不支持在商店前架设代理(例如 Cloudflare)。浏览器端脚本也不能替代:AI 训练爬虫从不执行 JavaScript,而且浏览器脚本会暴露你的签名密钥。
你可以这样做:
- 基于 Hydrogen 构建、托管在 Oxygen 上(或任何自托管环境)的 Headless 店面会运行服务器端代码;请把自建服务器 / Node 代码片段的逻辑接入店面的服务器请求处理程序。
- 对于标准商店,Citlyze 的其他测量(提示词追踪、引用、GEO 审计)不受商店托管位置影响,照常可用。
验证安装
- 在 设置 → 连接 → 网站跟踪中,站点密钥表格有一列最后事件。追踪代码首次成功上报后,这一列就会更新;爬虫访问和来自 AI 回答的引荐点击都计算在内。
- WordPress 用户可以点击发送测试事件(Send test event)立即确认能否送达(测试事件只验证凭据和连通性,不会更新最后事件)。
- 请耐心等待:流量较小的网站,第一次真实的爬虫访问可能需要几小时到几天。事件到达后,诊断 → AI 爬虫活动 → 概览就会显示数据。
- 如果几天后仍然没有任何数据,请重新检查:代码片段(或插件设置)中的密钥 ID 是否属于一个有效、未撤销的密钥;
CITLYZE_SIGNING_SECRET是否为该密钥当前的签名密钥;你的路由或中间件是否覆盖了所有路径。没有有效的签名密钥时,代码片段不会上报任何数据,并会记录一次“Citlyze crawler tracking is off”。 - 站点密钥表格还会显示每个密钥所用的采集器版本,并在代码片段或插件有新版本、或 WordPress 插件检测到页面缓存时提示你。