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)確認資料能成功送達。填入 Tracker base 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 的請求:由全頁快取直接提供的頁面、由 網頁伺服器或 CDN 執行的重新導向,以及在 WordPress 載入前就被防火牆擋下的請求。 外掛偵測到頁面快取時,會在設定頁面提醒你。快取較多的網站,請使用 Cloudflare Worker 或上傳伺服器記錄檔。如果 WordPress 位於 Cloudflare 以外的代理伺服器或負載 平衡器後方,請在外掛設定中填寫代理伺服器使用的用戶端 IP 標頭與代理位址,以便依 爬蟲的真實位址進行驗證。

每個網站只使用一個收集器。如果網站收集器與伺服器記錄來源同時回報同一個網域, 每次造訪都會被計算兩次;發生這種情況時,安裝追蹤頁面會提醒你。

自建伺服器與其他語言

自建伺服器分頁提供的是 Node 中介軟體,但任何技術堆疊都能回報資料:以經過簽章的 HTTPS POST 請求傳送到 https://app.citlyze.com/api/track,請求主體為 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 epoch 起算的毫秒數表示。超過 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 範圍來源位址落在營運者為其爬蟲公開的範圍內。
反向 DNS來源位址解析到營運者的網域,且該名稱也解析回同一個位址。
已知 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 取得。

本頁內容