安装 AI 爬虫追踪

本页逐步讲解每一条安装路径。关于爬虫追踪测量什么、验证如何工作，见 AI 爬虫。

选择与你的网站运行环境匹配的指南：

开始之前：生成站点密钥

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

1. 在应用中前往 AI 爬虫 → 安装追踪。
2. 点击生成站点密钥。给密钥起一个名字，最好同时填写它将上报的域名； 该域名还能加强该站点的签名爬虫验证。
3. 从确认对话框中复制两个值：密钥 ID 和签名密钥（以 ctk_ 开头）。签名密钥只显示一次；如果丢失，请在该密钥上使用轮换 生成替换的签名密钥。

请务必保管好签名密钥：任何拿到它的人都可以为你的站点提交伪造的流量 上报。不要把它提交到公共代码仓库，也不要粘贴到客户端代码中。

Cloudflare Worker

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

1. 在 AI 爬虫 → 安装追踪中打开 Cloudflare 标签页并复制代码片段。
2. 把片段中的 SITE_KEY_ID 和 ctk_SITE_KEY_SECRET 替换为你的密钥 ID 和签名密钥。
3. 在 Cloudflare 控制台中，前往 Workers & Pages → Create → Create Worker。起一个名字（例如 ai-crawler-tracker），点击 Deploy 创建空的 Worker。
4. 点击 Edit code，把自动生成的示例替换为你的片段，再次点击 Deploy。
5. 把 Worker 连接到你的网站：打开该 Worker 的 Settings → Domains & Routes → Add → Route，选择你的域（zone），添加路由 example.com/*。如果网站同时通过 www.example.com 提供服务，再为 www.example.com/* 添加一条路由。
6. 完成：网站代码无需任何改动。Worker 会把每个请求原样透传到你的源站， 并在后台上报匹配的访问。

有两点需要检查：

• 路由必须覆盖所有路径（/*），否则爬虫对未覆盖页面的访问将不可见。
• 如果这些路由上已经运行了一个 Worker，Cloudflare 每条路由只会执行一个 Worker；请把片段的逻辑合并进现有 Worker，而不是再加一个。

Vercel / Next.js 中间件

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

1. 在 AI 爬虫 → 安装追踪中打开 Vercel / 反向代理 标签页并复制 代码片段。
2. 在你的 Next.js 代码仓库中，在项目根目录（如果应用位于 src/，则在 src/ 中）创建 middleware.ts 并粘贴片段。
3. 把 SITE_KEY_ID 和 ctk_SITE_KEY_SECRET 替换为你的密钥 ID 和签名 密钥。
4. 如果你已经有 middleware.ts，不要再新建第二个文件；Next.js 只会 运行一个。把片段的辅助代码块复制进现有文件，在你的中间件函数开头调用 其上报逻辑，并确保 matcher 配置仍覆盖所有路径。
5. 提交并部署。

说明：

• 中间件在响应产生之前运行，因此事件的 HTTP 状态会上报为 unknown。 这是预期行为；错误洞察需要 Cloudflare 或自建服务器安装方式。
• 在 Vercel 上，访客 IP 取自平台设置的请求头，可以信任。如果你把 Next.js 自托管在自己的代理之后，请确保片段读取的转发 IP 头是由 你的代理设置的，而不是从客户端透传的。

WordPress 插件

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

1. 在 AI 爬虫 → 安装追踪中打开 WordPress 标签页，点击 下载插件（Download plugin）。
2. 在 WordPress 后台前往 插件 → 安装插件 → 上传插件，选择下载的 zip，点击立即安装，再点击启用。
3. 前往 设置 → AI Crawler Tracker，填写全部三个字段：
   • Tracker base URL：https://app.citlyze.com
   • Key ID：你的密钥 ID
   • Signing secret：你的 ctk_... 签名密钥 在填写追踪器基础 URL 之前，插件不会上报任何数据。
4. 点击发送测试事件（Send test event）。你应该会看到"已连接"的确认； 这证明你的凭据和连通性端到端有效。

注意：全页缓存和 CDN 可能根本不运行 WordPress 就直接响应请求，这会少计 爬虫访问。如果你的网站在 Cloudflare 后面大量使用缓存，请优先选择 Cloudflare Worker 安装方式。

自建服务器 / Node

适用于自己托管的自研网站：AWS、Google Cloud、Azure、VPS 或容器。该片段 是面向 Node 20 及更新版本的 Express 风格中间件（也可在 Bun 和 Deno 上 运行）。

1. 在 AI 爬虫 → 安装追踪中打开自建服务器 / Node 标签页并复制 代码片段。
2. 把它保存为 aeo-tracker.mjs，放在服务器入口文件旁边。
3. 把 SITE_KEY_ID 和 ctk_SITE_KEY_SECRET 替换为你的密钥 ID 和签名 密钥。如果团队更喜欢环境变量，在文件顶部把它们读入这两个常量即可； 只要确保签名密钥不进入源代码管理。
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。

Webflow

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

1. Webflow 在 Enterprise 计划上支持自行管理的反向代理；与你的 Webflow 联系人协商开通，并把域名路由到你的代理（Cloudflare、 CloudFront、Fastly 或你自己的 nginx）。
2. 在该代理层安装追踪器：
   • 代理在 Cloudflare 上 → 按照 Cloudflare Worker 指南操作。
   • 你自己的 Node 代理 → 按照 自建服务器 / Node 指南操作。
   • 其他情况 → 在你的代理中实现 签名信标协议。
3. 按照下文所述进行验证。

Webflow Cloud 应用不是全站追踪的途径：它们只处理挂载路径下的请求， 永远看不到爬虫对常规页面的访问。

Shopify

标准 Shopify 店面无法运行此追踪器：Shopify 不允许商家在店面请求上运行 服务器端代码，也不支持在商店前架设代理（例如 Cloudflare）。浏览器端脚本 不是替代方案：AI 训练爬虫从不执行 JavaScript，而且浏览器脚本会暴露你的 签名密钥。

你可以做的：

• 基于 Hydrogen 构建、托管在 Oxygen 上（或任何自托管环境）的 Headless 店面运行服务器端代码；把 自建服务器 / Node 片段的逻辑接入店面的服务器 请求处理器。
• 对于标准商店，Citlyze 的其他测量（提示词追踪、引用、GEO 审计）不受 商店托管位置影响，照常工作。

验证安装

• 在 AI 爬虫 → 安装追踪中，站点密钥表格有一列最后事件。当你的 安装送达第一份被接受的上报后它就会更新；爬虫访问和来自 AI 回答的 引荐点击都算。
• WordPress 用户可以通过发送测试事件（Send test event）立即确认送达 （测试事件验证凭据和连通性，但不会更新最后事件）。
• 给它一点时间：低流量网站的第一次真实爬虫访问可能需要几小时到几天。 事件到达后，AI 爬虫 → 分析就会填充数据。
• 如果几天后仍然没有任何数据，请重新检查安装中的密钥 ID 和签名密钥是否 对应一个有效（未撤销）的密钥，以及你的路由或中间件是否覆盖所有路径。