Claude 應用程式閘道部署和運營

1. 設定您的身份提供者：註冊 OAuth 用戶端並檢查 Okta、Entra 和 Google 的各個 IdP 說明
2. 部署閘道：建置固定版本的容器映像並在 Kubernetes、Cloud Run 或您自己的平台上執行。本章節也涵蓋成本、繞過、多閘道和無伺服器決策
3. 設定運營：日誌、健康探針、中斷行為、祕密輪換和升級。當您連接監控和運行手冊時的參考資料
4. 檢查安全態勢：資料流向何處、威脅模型和合規性答案。用於安全審查的參考資料

​

身份提供者設定

• 在生產環境中透過 HTTPS 提供 /.well-known/openid-configuration；閘道接受 http:// 發行者，環回發行者另外需要 CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
• 支援授權碼流程。PKCE（代碼交換的證明金鑰）預設開啟；對於不支援它的 IdP，使用 oidc.use_pkce: false 停用它
• 在 id_token 中傳回 email 和可選的 groups，或使用 oidc.userinfo_fallback: true 從 userinfo 端點提供它們

• Okta：位於 https://example.okta.com 的組織授權伺服器傳回省略 email 和 groups 的簡化 id_token，因此當您將其用作 issuer 時設定 oidc.userinfo_fallback: true。包含 id_token 中 email 和可選 groups 的自訂授權伺服器（例如 https://example.okta.com/oauth2/default）直接發出它們，不需要回退。Okta 只在 oidc.scopes 中請求 groups 範圍且應用程式的群組聲明篩選器允許時才發出 groups；userinfo_fallback 無法填充 IdP 未被要求的聲明。
• Microsoft Entra ID：issuer = https://login.microsoftonline.com/<tenant-id>/v2.0。Entra 發出群組物件 ID 而不是名稱，因此在 managed.policies.match.groups 中使用 GUID，或使用應用程式角色以獲得人類可讀的名稱。如果您的租戶在 roles 而不是 groups 下發出角色，設定 oidc.groups_claim: roles。
• Google Workspace：issuer = https://accounts.google.com。Google 的 id_token 不包含群組。要將基於群組的 allowed_groups 或 managed.policies 與 Google 作為 IdP 一起使用，請配置 oidc.google_groups，它使用具有網域範圍委派的服務帳戶透過 Admin SDK Directory API 查詢每個使用者的群組。沒有它，使用 oidc.allowed_email_domains 進行成員資格閘道和 managed.policies.match.email_domain 進行原則分配。Google 也忽略標準 offline_access 範圍。對於重新整理令牌，設定 oidc.scopes: [openid, profile, email] 和 oidc.extra_auth_params: { access_type: offline, prompt: consent }。

​

部署

• 成本：沒有單獨的許可證或按座位費用。閘道是 claude 二進位檔案的一部分，因此您透過現有的承諾為推理付費，加上它執行的計算。
• 繞過：閘道不強制執行通往模型的唯一路由必須通過它。具有自己認證的開發人員仍然可以直接呼叫提供者，因此關閉該路徑是網路原則決策，例如阻止到 api.anthropic.com 的出口，除了來自閘道。阻止該出口也會破壞 WebFetch 網域安全檢查，它從每個開發人員的機器呼叫 api.anthropic.com。在受管原則中設定 skipWebFetchPreflight: true 以停用它。
• 多個閘道：每個是一個單獨的部署，具有自己的設定，CLI 按閘道主機名儲存信任和認證，因此團隊可以使用不同的閘道而不會衝突。要提供多個 OIDC 發行者，請執行單獨的實例。
• 無伺服器：Cloud Run 可以工作，如果您設定 min-instances: 1 以避免冷 OIDC 發現。Lambda 和 Cloud Functions 不行，因為閘道是長時間執行的 HTTP 伺服器。

• 在除了 provider: anthropic 之外的每個上游上，一旦串流沉默約 15 秒，閘道就會寫入 SSE ping。
• 在 provider: anthropic 上，閘道將回應原封不動地傳遞，包括 Anthropic API 自己的 ping。

​

容器映像

1. 從固定版本下載您的映像架構的 Linux 建置；請參閱 安裝特定版本 以取得下載 URL。
2. 根據 二進位完整性和代碼簽名 中所述，根據版本的 GPG 簽名 manifest.json 驗證它。
3. 將其複製到建置上下文中。

• 基於 glibc 的映像：glibc 建置的唯一動態依賴項是 glibc 庫。基於 Musl 的映像需要 linux-x64-musl 或 linux-arm64-musl 建置加上額外套件；請參閱 Alpine Linux 設定。
• 可寫入的狀態目錄：閘道以任何使用者身份執行，但最小映像沒有可寫入的主目錄。將 CLAUDE_CONFIG_DIR 設定為可寫入的路徑，例如 /tmp/.claude。
• 容器命令：claude gateway --config /etc/claude/gateway.yaml，設定檔案以唯讀方式掛載，祕密作為環境變數提供；閘道在 listen.port 上監聽，預設為 8080。

​

Kubernetes

• 從 ConfigMap 掛載設定，從 Secret 掛載祕密；透過 ${file:/path/to/secret} 或作為環境變數在 YAML 中參考祕密
• 在 Ingress 處終止 TLS 並將 listen.public_url 設定為 Ingress 主機名
• 將就緒探針指向 GET /readyz，將活躍探針指向 GET /healthz

​

Cloud Run

• 將 listen.port 保留在預設值 8080，這與 Cloud Run 的預設 PORT 相符，或設定 port: ${PORT}
• 將 public_url 設定為外部可到達的來源。對於生產，這通常是內部負載平衡器的主機名，因為 /login 拒絕公開地址，而 *.run.app URL 解析為一個，所以單獨的 Cloud Run URL 僅適用於 curl 或瀏覽器煙霧測試。例外是一個網路，其中 *.run.app 透過 Private Service Connect 和 Cloud DNS 私有區域私下解析；在該拓撲中，Cloud Run URL 是有效的 public_url。Google Cloud 實際工作範例涵蓋兩者。
• 將設定掛載為祕密卷
• 設定 min-instances: 1 以避免首次請求時的冷 OIDC 發現

​

將閘道 URL 推送到開發人員機器

​

大規模推出

• 閘道無法看到您的負載平衡器之外。 沒有 listen.trusted_proxies，每個開發人員似乎都來自負載平衡器的地址並共享一個限制。首先設定它。閘道在第一次忽略 X-Forwarded-For 標頭時記錄警告。
• 許多開發人員共享幾個 NAT 或 VPN 出口地址。 即使 trusted_proxies 正確，他們也共享這些地址的限制。提高 rate_limits 以適應。

rate_limits:
  device_authorization: { max: 1000, window_seconds: 600 }
  device_verify: { max: 1000, window_seconds: 600 }

​

操作

​

日誌

• 稽核事件：每個安全相關事件一行 JSON。將 stderr 導管到您的日誌聚合器。 發出的事件包括 config.load、session.mint、session.refresh、device.authorize、device.verify、device.callback、auth.denied、access.denied、access.public_client、inference、managed.serve、desktop_bootstrap.serve、desktop_bootstrap.denied、spend.blocked、admin.denied、admin.limit.upsert 和 admin.limit.delete。欄位因事件而異：
  • 成功的 mint 和 refresh 事件攜帶 sub、email、client_ip 和結果
  • auth.denied 和 access.denied 攜帶原因和用戶端 IP，加上 auth.denied 的請求路徑，因為在這些拒絕時不存在使用者身份。兩個 access.denied 原因改變事件攜帶的內容：
    • xff_unparseable：事件也攜帶無法讀取的 X-Forwarded-For 項目
    • client_ip_unknown：事件不攜帶用戶端 IP，因為連線沒有對等位址，而 access_control 清單已設定
  • access.public_client 攜帶每個程序中第一個從公開位址到達的請求的用戶端 IP，同時 access_control.allow_cidrs 為空。閘道照常提供請求；事件表示閘道可能可從公開網際網路到達。請參閱 access_control 參考，了解什麼算作公開以及建議的允許清單。
  • inference 記錄哪個上游提供了請求以及回應狀態
  • desktop_bootstrap.denied 記錄被拒絕的 Claude Desktop bootstrap 擷取，包含原因（not_configured、policy_not_opted_in 或 no_policy_matched）和使用者的身份
  • admin.denied 記錄被拒絕的管理員 API 驗證嘗試，包含用戶端 IP、方法、路徑和原因，不包含呈現的金鑰資料：當呈現了 x-api-key 但未與任何已設定的金鑰相符時為 invalid_key，當僅呈現了 Authorization 標頭且其未驗證為 admin.admin_groups 中的閘道工作階段時為 bearer_rejected，或當兩個標頭都未呈現時為 no_credentials
• 操作日誌：人類可讀的 [gateway] 前綴行，用於啟動、警告和上游錯誤。CLAUDE_GATEWAY_LOG_LEVEL 環境變數控制詳細程度，接受 debug、info、warn 或 error，預設為 info。在 debug 時，每個登入和重新整理也會記錄 id_token 中的宣告名稱（而非值），加上當 userinfo_fallback 提供任何時的 userinfo 宣告名稱，因此您可以診斷 email_claim 和 groups_claim 設定，而不記錄個人識別資訊。它不影響稽核事件，稽核事件始終被發出。

​

健康狀態

​

並行上游請求

• 新增複本。
• 提高每個複本上的限制。在閘道容器上設定 BUN_CONFIG_MAX_HTTP_REQUESTS 環境變數為 1 到 65535 之間的整數，然後重新啟動容器。

​

中斷行為

• 現有工作階段：持有人令牌使用 JWT 密鑰在本地驗證，工作階段重新整理不接觸存放區，閘道程序仍可提供推論
• 新登入：失敗直到 Postgres 恢復，因為裝置流及其速率限制計數器存在於 Postgres
• 支出限制強制執行：在中斷期間預設失敗開啟，因此推論仍流動；如果您寧願阻止而不是無計量執行，請將其翻轉為失敗關閉
• 就緒性：預設情況下，/readyz 在 Postgres 無法到達時立即報告未就緒，因此每個複本同時失敗其就緒性檢查。在流量僅到達通過檢查的複本的地方，所有流量（包括閘道仍可提供的推論）在 Postgres 恢復前失敗。/healthz 上的活躍性探測在整個過程中保持通過。

​

就緒性寬限期

​

JWT 密鑰輪換

1. 產生新密鑰。將其前置到 session.jwt_secret 陣列。
2. 推出部署。新令牌使用新密鑰簽署；舊令牌仍驗證。
3. 在 ttl_hours 加上邊際後，移除舊密鑰並再次推出。

​

Postgres

​

升級

• 排放視窗：在閘道容器上設定 CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS 環境變數為正整數毫秒數，例如 120000。閘道忽略任何其他形式的值，例如 120s，並保持 25 秒預設
• 您的協調器的寬限期：Kubernetes 上的 terminationGracePeriodSeconds，或 Amazon ECS 上的 stopTimeout

• Amazon ECS on Fargate：stopTimeout 最多允許 120 秒
• Cloud Run：在 SIGTERM 後 10 秒停止實例，因此開啟的串流在那裡最多獲得 10 秒，無論排放視窗是什麼

​

安全

​

資料流

​

威脅模型摘要

• 開發人員持有短期 JWT 而不是原始上游金鑰。CLI 到閘道的腿使用 RFC 8628 設備授予，閘道與 IdP 的授權碼交換在預設配置中執行 PKCE，因此攔截的 IdP 授權碼是無用的。
• 設備驗證頁面強制執行同源 POST 和根據 RFC 8628 §5.1 的每 IP 速率限制。請參閱 使用者代碼暴力破解抵抗。
• 閘道對您的 IdP、您的 OTLP 收集器和 provider: anthropic 上游的請求通過伺服器端請求偽造 (SSRF) 防護，解析 DNS、阻止連結本地和雲端中繼資料地址加上預設環回，並將連接固定到解析的 IP，因此操作員影響的 URL 無法重新導向到雲端中繼資料端點。RFC 1918 私有範圍被刻意允許，因為 IdP 和 OTLP 收集器通常存在於私有 IP 上。對於其他提供者，閘道在載入配置時拒絕命名這些地址或中繼資料主機名的 base_url，提供者的 SDK 隨後連接而不進行 DNS 檢查。 如果您開啟 僅代理出口，該地址檢查會移至您的轉發代理：閘道交付主機名，代理的允許清單必須拒絕這些目的地。 只有當閘道必須到達的東西合法地存在於環回上時，才在閘道的環境中設定 CLAUDE_GATEWAY_ALLOW_LOOPBACK=1，例如本地開發 IdP 或 localhost 上的邊車 OTLP 收集器。該變數放寬每個操作員配置的 URL 的環回阻止，也跳過啟動時檢查 pod 是否可以到達雲端中繼資料端點的警告，因此偏好為收集器提供自己的內部地址。

• 受損的閘道主機：主機既持有上游認證，又向每個連接的開發人員分發 受管設定，因此對閘道配置的控制與對您的 MDM 的控制相當。CLI 的 批准對話框 用於殼層功能設定限制無聲變更，但不替代主機安全。
• 惡意 OIDC 提供者：提供者簽署閘道信任的 id_token，因此它可以聲稱任何身份。審查和保護您的 IdP 是您的責任。

​

使用者代碼暴力破解抵抗

​

合規性態勢

• 資料駐留：閘道自己的資料平面不向 Anthropic 發送任何東西，除非 Anthropic API 是配置的上游；當它是時，您現有的資料處理協議適用於推理路徑。遙測、審計、身份和設定只流向您配置的目的地。
• 主機程序流量：主機程序是 Claude Code CLI。claude gateway 在與 Amazon Bedrock 和 Google Cloud 的 Agent Platform 部署相同的第三方規則下執行，不向 Anthropic 發送任何東西。在 v2.1.227 之前，主機程序發送啟動遙測，例如產品版本和平台，設定容器環境中的 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 會關閉。這些版本也在啟動時發送一個 HEAD 請求，沒有正文或認證，到 https://api.anthropic.com 上的 /api/hello，或在環境設定時到 ANTHROPIC_BASE_URL，除非環境也設定代理變數（例如 HTTPS_PROXY）或 mTLS 用戶端憑證。它們忽略回應，因此在出口防火牆阻止該請求不會影響閘道。
• 用戶端分析：CLI 在簽入到閘道時停用自己的使用分析和錯誤報告。在第一次簽入之前，CLI 仍然向 Anthropic 發送啟動事件，包括在受管設定強制閘道簽入的機器上。要也關閉這些，在強制閘道簽入的相同 用戶端側受管設定 中傳遞 DISABLE_TELEMETRY。
• 錯誤報告：每當 CLI 的模型請求流向 Anthropic 的第一方 API 以外的任何端點（例如 Amazon Bedrock 或自訂 ANTHROPIC_BASE_URL）時，CLI 會關閉錯誤報告。
• 用戶端機器：開發人員的 CLI 仍然向 Anthropic 發送 WebFetch 主機名檢查和版本檢查，除非設定 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 和 skipWebFetchPreflight: true。請參閱 資料使用。
• 調查評分：在簽入到閘道時，CLI 停用 Anthropic 綁定評分上傳以及分析串流，因此不向 Anthropic 發送評分。
• 記錄單共享：在調查的記錄單共享提示上選擇「是」會在 ~/.claude/feedback-bundles/ 下寫入本地檔案，而不是上傳到 Anthropic。
• 用戶端更新：更新檢查與閘道流量分開。透過您自己的分發固定版本，如果筆記型電腦不得提取版本，設定 DISABLE_UPDATES。DISABLE_AUTOUPDATER 只停止背景更新，而 claude update 仍然有效。
• TLS：在生產中透過 HTTPS 提供 public_url，要麼從閘道自己的監聽器透過 listen.tls，要麼從 TLS 終止 ingress 在純 HTTP 副本前面，在兩種情況下都設定 listen.public_url。閘道不拒絕純 HTTP。IdP 必須在生產中提供 HTTPS，Postgres 支援 ?sslmode=require。在您的 ingress 設定 Strict-Transport-Security。
• 漏洞披露：遵循 報告安全問題

​

疑難排解

• Gateway 問題：gateway 的 stderr（針對相關視窗）、您的 gateway.yaml（已隱蔽機密）、gateway 版本（顯示在 / 的登陸頁面和 /managed/settings 上的 x-cc-gateway-version 回應標頭中），以及最近有什麼變更
• 登入問題：開發者執行 claude --debug-file ./claude-debug.txt、重現問題，然後傳送該檔案加上 gateway 針對同一視窗的稽核日誌
• 推論問題：要求的模型、設定的上游，以及 gateway 針對該請求的稽核日誌，其中記錄了哪個上游提供了該請求以及回應狀態

​

相關

• Claude 應用程式閘道概述：快速入門和開發人員連接
• 設定參考：每個 gateway.yaml 選項