Cloudflare AI Gateway 怎麼接 Access？用 cf.user_id 做使用者用量分流

先分清楚三種請求入口#

AI Gateway 同時存在預設入口、Access custom domain 與 service token。不要只看到請求成功，就推論三條路徑的身份資訊相同：

Cloudflare 文件指出，Access JWT 的 sub 不是使用者 email；它是 Access token 的 subject。若你的報表需要顯示 email 或組織內的人員名稱，應另外建立身份對照，不要把 cf.user_id 當成 email 欄位。

設定前先準備 custom domain#

Cloudflare 的 Access 整合必須先有 AI Gateway custom domain。設定流程可以依下面順序進行：

1. 在要保護的 gateway 上設定 custom domain，例如 ai.example.com。
2. 確認 DNS 與 domain control validation 已完成，不要在 pending_dcv 時就把正式 client 全部切過去。
3. 到 Cloudflare dashboard 的 AI → AI Gateway，選擇該 gateway 的 Access 設定。
4. 建立 Access application 與 policies，限制哪些身份可以呼叫 gateway。
5. 讓 client 透過 Access 的瀏覽器登入、service token 或其他已核准的 Access 流程取得 token。
6. 先用一個測試 identity 呼叫 custom domain，再到 logs、analytics 或 User Insights 確認分流結果。

設定 Access tab 會替 gateway 建立對應的 Access application；非瀏覽器 client 仍要依 Access 的 token header 或 cookie 規則送出認證。不要把 Access token、provider key 或 gateway 管理 token 放進前端 bundle。

Custom domain 的請求路徑會變短#

使用 custom domain 後，Cloudflare 文件的 OpenAI-compatible 範例會把 account ID 與 gateway ID 從路徑拿掉：

1
cloudflared access curl \
2
  --header 'Content-Type: application/json' \
3
  'https://ai.example.com/openai/v1/chat/completions' \
4
  --data '{
5
    "model": "gpt-4.1-mini",
6
    "messages": [{"role": "user", "content": "Hello"}]
7
  }'

這個範例的重點不是固定使用 cloudflared access curl；如果你的 client 使用 Access bearer token 或 cookie，也可以按照 Access 的非瀏覽器流程傳遞。重點是請求要打到受 Access 保護的 custom domain，而不是仍然打到預設 gateway endpoint，卻期待它自動出現 cf.user_id。

Cloudflare 也說明，當 custom domain 受 Access 保護後，每個請求都必須通過 Access policy。只送 gateway token、沒有有效 Access token 的請求，會在到達 AI Gateway 前被 Access 擋下；原本使用 gateway.ai.cloudflare.com 的整合則不會自動繼承這個 policy。

cf.user_id 從哪裡來？#

當 AI Gateway 收到有效且有非空 subject 的 Access JWT，它會在 request metadata 加入 cf.user_id。這個值由 Cloudflare 產生並保留，不能由 client 自行在 metadata 裡偽造：

• cf.user_id 的來源是 Access JWT sub，不是 email。
• service token 不代表個別使用者，因此不會有 cf.user_id。
• cf. 開頭的 metadata key 是 Cloudflare 保留欄位，不能由你自行提供。
• 如果 JWT 沒有非空 user subject，Access 仍可能完成驗證，但不會產生可用的 cf.user_id。

這個邊界很重要：如果前端傳來 user_id: "alice"，那只是 client metadata，不等於 Cloudflare 已驗證的使用者。需要可信身份時，應使用 Access policy 與 cf.user_id，不要把前端欄位直接當成計費或權限依據。

User Insights 與 spend controls 要放在哪一層？#

AI Gateway 的 User Insights 可以用 gateway 流量觀察組織的 AI 使用量。沒有身份或 custom metadata 時，流量會被歸到匿名識別；若使用 Access，經過驗證的 identity 可以用來篩選 spend 與 analytics。

但 Access 本身不是 spend limit。建議分成三層：

1. Access policy：誰能進入 custom domain。
2. AI Gateway User Insights：哪個已驗證 identity 產生多少請求與支出。
3. AI Gateway spend controls：在 gateway 或組織層設定用量與成本界線。

如果你同時使用 Workers AI 與第三方模型的 Unified Billing，請把帳單入口和身份入口分開檢查，可參考 Cloudflare Workers AI 統一計費與 AI Gateway 的分工。Access 會改善「誰在用」的可見度，不會自動改變 provider、credits 或 billing 路徑。

切換前用三個測試請求驗證#

不要只用一個登入帳號測試。至少準備下面三種請求，並比較 logs／analytics／User Insights：

若要支援 automation 或 coding agent，另外測試 service token。它適合代表一個服務，不應被當成某位人員的 cf.user_id；需要逐人歸因時，應讓使用者以個人 Access identity 呼叫，或在產品層建立明確且可審核的代理流程。

結論：把身份驗證留在入口#

AI Gateway + Access 的正確使用方式，是讓 custom domain 負責「誰可以呼叫」，讓 cf.user_id 負責「這個已驗證身份產生了哪些流量」，再由 User Insights 和 spend controls 負責觀測與成本治理。不要把 gateway token、Access token 和前端自訂 user ID 混成一個欄位，也不要因為預設 endpoint 能回應，就以為它已經受到 Access policy 保護。

常見問題#