AI 爬虫

AI 爬虫追踪展示哪些 AI 引擎真正在访问你的网站：GPTBot、ClaudeBot、PerplexityBot、Bingbot 等。它与 GEO 审计互补：审计告诉你机器人能否到达页面；爬虫追踪告诉你它们是否真的来了。

为什么用服务器端捕获

AI 训练爬虫不运行 JavaScript，Google Tag Manager 或 JavaScript 像素永远 看不到 GPTBot 或 ClaudeBot。Citlyze 在服务器端捕获爬虫访问，那里能看到 真实的请求 User-Agent，因此不执行 JavaScript 的爬虫也会被统计。

人类这一半则不同：由 AI 回答引荐的访客会运行 JavaScript，因此对 AI 流量来说，浏览器代码片段或 Tag Manager 安装就够用了（见 安装 AI 流量追踪）。本页的 服务器端安装方式会同时捕获两类访问。

安装追踪

前往 设置 → 连接 → 网站跟踪并生成站点密钥。密钥有两部分（密钥 ID 和签名 密钥），只显示一次；两者都要复制。然后为你的平台添加对应代码片段 （每个选项的逐步安装讲解见 安装 AI 爬虫追踪）：

• Cloudflare（推荐）：把 Worker 片段放在站点前面。
• Vercel / 反向代理：添加中间件片段。
• WordPress：下载 AI Crawler Control by Citlyze，在 wp-admin → 插件中 上传，然后在其设置中填写全部三个字段：Tracker base URL (https://app.citlyze.com)、Key ID 和 Signing secret。再使用 发送测试事件（Send test event）验证连接。在填写追踪器基础 URL 之前，插件不会上报任何数据。
• 自建服务器 / Node：适用于自托管站点（AWS、GCP、Azure、裸机、容器）： 添加 Express 风格的中间件片段（Node 20+）。它可适配 Fastify、Koa 或原生 http，其他语言也可以直接实现签名信标协议。

Cloudflare、Vercel 和自建服务器的代码片段从环境变量 CITLYZE_SIGNING_SECRET（在 Cloudflare 上是加密的 Worker 机密）读取签名 密钥，因此签名密钥永远不会出现在你提交或分享的代码中。WordPress 插件则把它 保存在插件设置里。

每个事件都用你的密钥签名，追踪器可以拒绝伪造的信标。

该签名只证明这份上报来自你的网站，并不能说明访问者是谁。确认访问者确实是 GPTBot 是另一个步骤，见验证如何工作。

标准 Shopify 商店无法运行服务器端捕获，而且 Shopify 不支持在商店前架设代理 （例如 Cloudflare），因此标准 Shopify 无法使用完整的爬虫追踪。Headless 的 Hydrogen 或 Oxygen 店面运行服务器端代码，可以使用自建服务器片段。Webflow 托管同样无法运行服务器代码；在 Webflow Enterprise 上，自行管理的反向代理 可以在代理层运行 Cloudflare Worker 或自建服务器片段。

采集器会上报每个请求的结果：

• Cloudflare Worker、自建服务器中间件和 WordPress 插件会发送精确的 HTTP 状态码（200、301、404、410、500 等），用于驱动下文的错误和重定向 洞察。Vercel 中间件在响应产生之前运行，因此无法上报；如需在 Vercel 上获得 状态码，请改用 网站跟踪 → 服务器日志中的 Vercel log drain，而不是中间件。
• 发生重定向时，这三种采集器还会发送重定向目标：指向你自己网站的页面时 发送路径，指向其他网站时只发送域名。
• 爬虫访问还会发送查询字符串（例如 ?page=2）。人类访客的查询字符串永远 不会离开你的网站。

事件以带签名的批次发送。如果 Citlyze 暂时无法访问，Cloudflare Worker 和 自建服务器中间件会重试一次；WordPress 插件会把未送达的事件在你的 WordPress 数据库中保留最多一天，并持续重试。重试永远不会被重复计数。每个已安装的 采集器还会至少每天刷新一次已知爬虫列表，因此无需更新片段或插件即可识别新 出现的爬虫。当你的片段或插件有新版本时，网站跟踪页面会提示你。

WordPress 插件能看到每个到达 WordPress 的请求，包括在页面渲染前被其他插件 重定向的请求。它看不到从未到达 WordPress 的请求：由全页缓存直接返回的页面、 由你的 Web 服务器或 CDN 完成的重定向，以及在 WordPress 加载前被防火墙拦截 的请求。插件设置页检测到页面缓存时会提示你。对于大量使用缓存的网站，请使用 Cloudflare Worker 或上传服务器日志。如果 WordPress 位于 Cloudflare 以外的 代理或负载均衡器之后，请在插件设置中填写代理设置的客户端 IP 请求头和代理 地址，以便按真实地址验证爬虫。

每个网站只使用一种采集方式。如果网站采集器和服务器日志来源上报同一个域名， 每次访问都会被计算两次；出现这种情况时，网站跟踪页面会提醒你。

自建服务器与其他语言

自建服务器标签页提供的是 Node 中间件，但任何技术栈都可以上报：向 https://app.citlyze.com/api/track 发送带签名的 HTTPS POST 请求，携带 JSON 请求体（最大 256 KB）和 Content-Type: application/json。每个请求 携带一个包含 1 到 50 个事件的批次。

必需的请求头：

计算签名：

1. 派生签名用密钥：对你的签名密钥（完整的 ctk_... 字符串）取小写 64 位 十六进制 SHA-256。将该十六进制字符串的 UTF-8 字节用作 HMAC 密钥； 不要对它做十六进制解码。
2. 构造消息："3\n" + timestamp + "\n" + nonce + "\n" + bodyDigest，其中 bodyDigest 是你实际发送的请求体字节的小写十六进制 SHA-256。签名之后 任何重新序列化都会使签名失效。
3. x-aeo-signature 就是用第 1 步的密钥对该消息计算的小写十六进制 HMAC-SHA256。

请把签名密钥保存在环境变量或平台的机密存储中，永远不要写进源代码。

请求体字段：

• collector：你的集成的简短名称，例如 my-app/1.0（字母、数字、.、 _、/ 和 -，最长 64 个字符）。
• events：事件列表。每个事件包含以下字段（除注明外均为必填）：
  • occurredAt：请求发生的时间，以自 Unix 纪元起的毫秒数表示。超过 48 小时的事件会被忽略。
  • host：请求的主机名（不含端口），或空字符串。主机既不是你站点密钥的 域名、也不是其子域名的事件会被忽略。
  • userAgent：访问者的 User-Agent，最长 1024 个字符。
  • path：请求路径，以 / 开头，不含查询字符串和片段标识，最长 2048 个字符。
  • query（可选）：不含 ? 的查询字符串，仅用于爬虫请求。
  • visitorIp：你的服务器看到的客户端 IP。位于负载均衡器或反向代理之后 时，从你自己的代理设置的转发头中取值；爬虫身份验证检查的正是这个字段。
  • referrer：空字符串，或去掉查询和片段的 https:// 来源 URL。只对从 AI 回答点击进入的人类访问有意义。
  • utmSource（可选）：当来自 AI 回答的访问没有来源信息时，填写 utm_source 的值。
  • status：响应的三位 HTTP 状态码；如果在响应产生之前上报，则为 unknown。
  • method：大写的 HTTP 方法。
  • redirectTarget（可选）：对于 3xx 响应，填写它指向的 Location。

只上报 User-Agent 看起来是自动化程序、或来源是 AI 回答引擎的请求，并在响应 之后发送批次，绝不要让访客等待。如果批次因网络错误、429 或 5xx 失败， 请使用相同的 nonce 和请求体以及新的时间戳重试：已经送达的批次会按其 nonce 识别，只计算一次。429 响应带有 Retry-After 请求头。其他任何 4xx 都表示批次本身无效，请不要重试。

你还可以选择每天从 GET https://app.citlyze.com/api/track/registry 获取 一次最新的已知爬虫标识和 AI 来源主机列表，并在 x-aeo-key-id 请求头中 携带你的密钥 ID。响应头 x-aeo-registry-signature 是用第 1 步的密钥对 "citlyze-registry-1\n" + bodyDigest 计算的小写十六进制 HMAC-SHA256； 不匹配时请忽略该列表。

要验证你的集成，发送一个带 "test": true 的批次，其中只包含一个事件， 该事件的 userAgent 以 citlyze-connection-test/ 开头，path 为 /citlyze-test。签名正确的测试返回 HTTP 200 且不存储任何内容；真实批次 返回 204，无论访问最终是否出现在你的报告中。

轮换或撤销密钥

如果签名密钥可能已泄露（例如被提交到代码仓库或出现在截图中），请使用密钥 旁边的轮换。轮换会为同一密钥签发新的签名密钥：密钥 ID、名称、域名和 全部历史记录都会保留，但旧的签名密钥会立即停止通过验证，请尽快把 CITLYZE_SIGNING_SECRET（或插件设置）更新为新的签名密钥。 撤销则不同：它会永久停用该密钥，并停止该站点的追踪。

解读分析

诊断 → AI 爬虫活动 → 概览页面针对所选时间范围展示：

• 头部指标卡：爬虫总访问、不同爬虫数、最活跃爬虫和趋势
• 爬虫访问随时间变化（每日总量）
• 爬虫访问时段：按一天中各小时统计的访问量
• 各爬虫趋势（每个爬虫一条线）
• 按爬虫细分，含组织、用途、访问量和趋势
• 被抓取最多的页面（前 10，附完整列表链接）
• 未识别的机器人：与任何已知 AI 爬虫都不匹配的类机器人 User-Agent， 归入"未知机器人"分组，让新爬虫尽早显现

日期和小时按你浏览器的时区计算，因此纽约晚上 9 点的访问计入当天，而不是 第二天。按页面的表格使用 UTC 日期。

趋势只比较完整的日期。今天尚未结束时不参与比较，每个完整的日期都与上一个 时间段中对应的日期比较。在上一个时间段没有访问的爬虫显示新增而不是百分比； 如果追踪是在上一个时间段开始之后才启动的，则暂不显示趋势。

使用预设时间范围（7/30/90 天）、自定义日期范围和爬虫筛选器聚焦视图。追踪 多个站点的工作区还会显示站点筛选器。从 AI 回答进入的访客见 AI 流量。

验证如何工作

任何客户端都能在 User-Agent 里写上 GPTBot。所以 User-Agent 只是一种声称， 而非证据。Citlyze 也按此处理：核心爬虫数据只统计我们能独立确认的流量。

每次访问会得到三种置信度之一：

• 已验证：我们对照运营方公开的信息确认了访问者的网络身份。只有这些计入 你的总数。
• 疑似：有旁证支持，例如你的 CDN 将该请求标记为已知机器人，但没有独立 确认。
• 未验证：User-Agent 声称是某个爬虫且没有矛盾之处，但我们无法确认。会 单独展示，绝不计入你的总数。

验证会使用运营方所支持的方式：

未公布任何可校验信息的运营方，最多只能达到未验证。这是该爬虫本身的特性， 不是你的配置有问题；这也正是我们分开展示、而不是混成一个数字的原因。

有两点值得了解：

• 代理流量单独统计。 由人操作的工具（例如 ChatGPT Agent）会出现在代理活动 中，而不计入爬虫总数：一个人点击与一个爬虫为你建立索引，并不是同一种信号。
• 有时我们无法完成校验：运营方的 IP 列表可能暂时无法访问。这类访问会保持 未验证而不是被计入，因此你的总数绝不会包含我们未确认的内容。

被抓取页面

诊断 → AI 爬虫活动 → 被抓取页面是完整的下钻视图：所选时间范围内 AI 爬虫抓取过的 每个页面，支持搜索、排序和分页。每行显示访问量、占全部爬虫流量的份额、与 上一时间段的趋势对比、错误数、重定向数、最活跃爬虫和最近访问时间；展开一行 可查看按爬虫的细分，以及爬虫收到的具体状态码。

相关时，表格上方会出现以下洞察：

• 被抓取但从未被引用：AI 引擎抓取了但从未在你追踪的回答中引用的页面； 适合改写为更清晰、更易被引用的内容。
• 返回错误的页面：以 4xx/5xx 响应爬虫的页面。损坏的页面无法被读取或 引用。
• 发生重定向的页面：爬虫仍在请求、随后被重定向的旧 URL。请把内部链接 和站点地图指向最终 URL。
• 首次被抓取的页面：自追踪开始以来、在本时间段之前从未被任何 AI 爬虫 抓取过的页面。新内容出现在这里，说明爬虫已经发现了它。

状态码和重定向需要能上报它们的采集器：Cloudflare Worker、自建服务器中间件、 WordPress 插件或服务器日志。

在包含数据导出的套餐中，表格可下载为 CSV。

抓取日志

诊断 → AI 爬虫活动 → 抓取日志按天、按时间顺序列出已验证 AI 爬虫和已签名代理对你 网站发出的每个请求，并归入抓取会话（同一爬虫的请求之间间隔不超过 30 分钟）。 每个请求都会显示时间、页面及其查询字符串、状态码；对于重定向，还会显示 重定向目标，以及爬虫是否在同一会话中跟随了它。在一个会话中被多次抓取的 页面会有标记。

抓取日志只保存已验证爬虫和已签名代理的请求，从不包含其他访客，也从不存储 IP 地址或 User-Agent。可能包含凭据或个人数据的查询参数（例如 token 或 email）的值会被替换为 redacted。可回看的天数取决于你的套餐，见 套餐与限额。在包含数据导出的 套餐中，单日日志可下载为 CSV。

通过 API 和 MCP 获取数据

安装追踪后，爬虫访问即可编程获取：

• REST：GET /api/v1/crawler-events，见 AI Crawler Events 资源。
• MCP：list_crawler_events 工具，见 MCP 工具参考。

两者均为只读、限定在你的工作区内。REST 资源支持按 crawler_id、被追踪站 点和精确 path 筛选；来自 AI 回答的人类访问通过 GET /api/v1/ai-referrals 获取。