citlyze docs
使用 Citlyze

安装 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

开始之前:生成站点密钥

无论使用哪个平台,每种安装方式都需要一个站点密钥:

  1. 在应用中前往 设置 → 连接 → 网站跟踪。
  2. 点击生成站点密钥。为密钥命名,最好同时填写它要上报的域名;填写域名还能加强对该网站已签名爬虫的验证。
  3. 从确认对话框中复制两个值:密钥 ID 和签名密钥(以 ctk_ 开头)。签名密钥只显示一次;如果丢失,请对该密钥使用轮换,生成新的签名密钥。

请妥善保管签名密钥:任何拿到它的人都可以为你的网站提交伪造的流量上报。Cloudflare、Vercel 和自建服务器的代码片段都从环境变量 CITLYZE_SIGNING_SECRET 读取它,因此它不会出现在你的代码中;WordPress 插件则把它保存在插件设置里。切勿把它提交到代码仓库,也不要粘贴到客户端代码中。

Cloudflare Worker

适用于 DNS 托管在 Cloudflare 且网站已开启代理(橙色云开关)的情况。这是最完整的方案:它能在边缘看到每一个请求,上报真实的 HTTP 状态码,而且无论 Cloudflare 后面运行的是什么都能工作。

  1. 在 设置 → 连接 → 网站跟踪 → 安装代码片段中打开 Cloudflare 标签页,复制代码片段。
  2. 将代码片段中的 SITE_KEY_ID 替换为你的密钥 ID。签名密钥不要写进代码;你会在第 5 步把它添加为 Worker 机密。
  3. 在 Cloudflare 控制台中,前往 Workers & Pages → Create → Create Worker。为它命名(例如 ai-crawler-tracker),点击 Deploy 创建一个空的 Worker。
  4. 点击 Edit code,把自动生成的示例替换为你的代码片段,再次点击 Deploy。
  5. 添加签名密钥:在该 Worker 中打开 Settings → Variables and Secrets → Add,类型选择 Secret,命名为 CITLYZE_SIGNING_SECRET,粘贴你的签名密钥,然后点击 Deploy。Cloudflare 会加密保存它,它不会出现在 Worker 的代码中。
  6. 把 Worker 连接到你的网站:打开该 Worker 的 Settings → Domains & Routes → Add → Route,选择你的域(zone),添加路由 example.com/*。如果网站同时通过 www.example.com 提供服务,请再为 www.example.com/* 添加一条路由。
  7. 完成:网站代码无需任何改动。Worker 会把每个请求原样转发到你的源站,并在后台上报符合条件的访问。

有两点需要检查:

  • 路由必须覆盖所有路径(/*),否则将无法看到爬虫对未覆盖页面的访问。
  • 如果这些路由上已经有一个 Worker 在运行,由于 Cloudflare 每条路由只执行一个 Worker,请把代码片段的逻辑合并到现有 Worker 中,而不是再添加一个。

Vercel / Next.js 中间件

适用于部署在 Vercel 上的 Next.js 应用。同一个文件也适用于自托管的 Next.js。

  1. 在 设置 → 连接 → 网站跟踪 → 安装代码片段中打开 Vercel / 代理标签页,复制代码片段。
  2. 在你的 Next.js 代码仓库中,在项目根目录(如果应用位于 src/,则在 src/ 中)创建 middleware.ts,并粘贴代码片段。
  3. 将 SITE_KEY_ID 替换为你的密钥 ID。签名密钥不要写进该文件。
  4. 在 Vercel 项目中打开 Settings → Environment Variables,为每个需要追踪的环境添加 CITLYZE_SIGNING_SECRET,值为你的签名密钥,并将其标记为 Sensitive。自行托管 Next.js?请在服务器环境中设置同一个变量。
  5. 如果你已经有 middleware.ts,不要再新建第二个文件,因为 Next.js 只会运行一个。把代码片段中的辅助代码块复制到现有文件中,在中间件函数开头调用其上报逻辑,并确保 matcher 配置仍覆盖所有路径。
  6. 提交并部署。

说明:

  • 中间件在响应生成之前运行,因此事件的 HTTP 状态会上报为 unknown。这是正常现象。如需状态码,请改用 Vercel log drain 代替此中间件(两者同时使用会把每次访问计算两次),或者使用 Cloudflare 或自建服务器安装方式,它们还会上报重定向。
  • 在 Vercel 上,访客 IP 取自平台设置的请求头,可以信任。如果你把 Next.js 自托管在自己的代理之后,请确保代码片段读取的转发 IP 请求头是由你自己的代理设置的,而不是从客户端原样传过来的。

WordPress 插件

适用于任何可以安装插件的 WordPress 网站。

该插件还能免费检查你的 robots.txt 允许哪些 AI 爬虫访问,以及是什么拦截了其余爬虫;参见 WordPress 插件。

  1. 在 WordPress 后台前往 插件 → 安装插件,搜索 AI Crawler Control by Citlyze,点击立即安装,再点击启用。插件已上架 WordPress.org 官方插件目录,无需上传 zip 文件。

  2. 想手动安装?在 设置 → 连接 → 网站跟踪 → 安装代码片段中打开 WordPress 标签页,点击下载插件(Download plugin),然后在 插件 → 安装插件 → 上传插件中上传该 zip 文件。

  3. 前往 Citlyze → Connect Citlyze,填写全部三个字段:

    • Tracker base URL:https://app.citlyze.com
    • Key ID:你的密钥 ID
    • Signing secret:你的 ctk_... 签名密钥 填写追踪器基础 URL 之前,插件不会上报任何数据。
  4. 点击发送测试事件(Send test event)。你应该会看到“已连接”的确认提示,这说明凭据和网络连接已经端到端打通。

  5. 网站位于 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 上运行)。

  1. 在 设置 → 连接 → 网站跟踪 → 安装代码片段中打开自建服务器 / Node 标签页,复制代码片段。
  2. 把它保存为 aeo-tracker.mjs,放在服务器入口文件旁边。
  3. 将 SITE_KEY_ID 替换为你的密钥 ID,并在服务器上将环境变量 CITLYZE_SIGNING_SECRET 设置为你的签名密钥:可以在托管平台的机密设置中设置,也可以写入一个永不提交的 .env 文件。签名密钥本身不要写进这个代码文件。
  4. 在你的路由之前注册中间件:
    import { aeoCrawlerTracker } from "./aeo-tracker.mjs";
    app.use(aeoCrawlerTracker());
  5. 如果服务器位于负载均衡器或反向代理(nginx、ALB)之后,请配置 Express 信任它(例如 app.set("trust proxy", 1)),这样中间件上报的才是真实的客户端 IP,而不是代理的 IP。爬虫身份验证检查的正是这个 IP。
  6. 部署。中间件在每次响应完成后才上报,因此不会增加任何延迟,并且包含真实的 HTTP 状态码。

不用 Express?返回的处理函数接收普通的 (req, res, next) 参数,可以适配 Fastify、Koa 或 Node 的 http 服务器。对于完全不同的语言(Python、Go、PHP、Ruby 等),请实现签名信标协议;每个带签名的 HTTPS POST 请求携带一个批次,最多包含 50 个符合条件的请求。

Webflow

Webflow 自身的托管无法运行服务器端代码,而浏览器端脚本又看不到 AI 训练爬虫,因此追踪需要安装在 Webflow 前面的代理层:

  1. Webflow 在 Enterprise 套餐中支持自行管理的反向代理;请与你的 Webflow 对接人协商开通,并把域名路由到你的代理(Cloudflare、CloudFront、Fastly 或你自己的 nginx)。
  2. 在该代理层安装追踪器:
  3. 按照下文所述进行验证。

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 插件检测到页面缓存时提示你。

本页内容