citlyze docs
使用 Citlyze

AI 爬虫

查看哪些 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 无法使用完整的爬虫追踪。基于 Hydrogen 或 Oxygen 的 Headless 店面会运行服务器端代码,可以使用自建服务器代码片段。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 个事件。

必需的请求头:

请求头值
x-aeo-schema字面字符串 3。
x-aeo-key-id你的密钥 ID(生成站点密钥时显示的 UUID)。
x-aeo-ts以秒为单位的 Unix 时间戳;与追踪器时钟的偏差必须在 5 分钟以内。
x-aeo-nonce每个批次唯一:16 到 64 个字符,由十六进制数字和连字符组成。去掉连字符的 UUID 即可。
x-aeo-signature小写十六进制 HMAC,计算方式见下文。

计算签名:

  1. 派生签名用的密钥:对你的签名密钥(完整的 ctk_... 字符串)计算 SHA-256,得到 64 个字符的小写十六进制字符串。将该字符串的 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:// 来源网址。只对从 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 声称是某个爬虫,也没有相反的迹象,但我们无法确认。这类访问单独显示,绝不计入你的总数。

验证会采用运营方支持的以下方式:

方式能证明什么
已签名请求请求带有加密签名,我们已对照运营方公开的密钥完成校验。这是目前最有力的证据。
公布的 IP 段来源地址位于运营方为其爬虫公布的 IP 段内。
反向 DNS来源地址解析到运营方的域名,而该域名又解析回同一地址。
已知 IP 段来源地址位于运营方文档中列出的固定 IP 段内。
CDN 证明你的 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 资源支持按 crawler_id、已追踪网站和精确的 path 筛选;来自 AI 回答的真人访问可通过 GET /api/v1/ai-referrals 获取。

本页内容