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

本頁涵蓋執行 Claude 應用程式閘道 的運營方面：在您的身份提供者 (IdP) 中註冊 OAuth 用戶端、將閘道部署為容器，以及日常運營。關於閘道在啟動時讀取的 gateway.yaml 檔案中的每個選項，請參閱 設定參考。 生產部署按順序遵循四個步驟，下面的章節與之相符。前兩個是您做出選擇的地方；後兩個是一旦運行時要查閱的參考資料。

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

如果沿途簽入或啟動失敗，請直接前往 故障排除，該部分根據您看到的錯誤進行索引。

​

身份提供者設定

向任何 OIDC 相容的身份提供者註冊機密 OAuth/OpenID Connect (OIDC) 網路應用程式，使用單一重新導向 URI https://<gateway>/oauth/callback，並將其分配給應該有閘道存取權限的使用者或群組。 任何 OIDC 相容的 IdP 都可以使用：Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、PingFederate 等。IdP 必須滿足三個要求：

• 在生產環境中透過 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 端點提供它們

對於私有 PKI，設定 oidc.ca_cert_pem。 一些提供者以不同方式處理電子郵件和群組聲明：

• 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 }。

如需有關上述未涵蓋的身份提供者的支援，請參閱疑難排解。

​

部署

閘道是單一 Linux 二進位檔案。它水平擴展，因為副本是無狀態的，Postgres 是共享協調層。以您在環境中執行無狀態服務的任何方式執行它。本章節的其餘部分說明映像需要什麼，並為 Kubernetes 和 Cloud Run 提供簡短說明。 閘道設計為在您的網路內執行，因為它持有您的上游認證並充當推理的單一出口點。它可以在您的開發人員和您的 IdP 可以透過 HTTPS 到達的任何地方執行；將其視為任何其他持有生產認證的服務。 除了它執行的位置之外，還有一些決策塑造部署：

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

此處的每個生產拓撲都在純 HTTP 副本前面放置 L7 代理，例如 Ingress、Cloud Run 的前端或 ALB。設定 listen.trusted_proxies 為代理的來源範圍，以便閘道從 X-Forwarded-For 讀取用戶端 IP。閘道只在 TCP 對等體受信任時才遵守標頭；Google Cloud 實際工作範例 為每個拓撲提供具體值。沒有受信任的代理，每個請求似乎都來自代理的 IP，這會將按 IP 速率限制摺疊為一個共享桶，並在審計事件中記錄代理的 IP。

​

容器映像

圍繞標準 Claude Code 版本中的原生 claude 二進位檔案建置您自己的映像：

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

將閘道作為 Deployment 執行，就像任何無狀態服務一樣：

• 從 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 推送到開發人員機器

一旦閘道開始提供服務，透過受管設定、MDM 或直接寫入各個 OS managed-settings.json 將 forceLoginMethod 和 forceLoginGatewayUrl 推送到每個開發人員的機器。沒有這個，/login 顯示標準帳戶選擇器，沒有閘道選項。請參閱 用戶端受管設定 以取得檔案路徑。

​

運營

一旦閘道開始提供流量，日常運營就是讀取其日誌、探測其健康狀況，以及按您的時間表輪換其祕密。下面的小節涵蓋每一個，加上 Postgres 持有的內容以及升級和回滾的行為方式。

​

日誌

閘道向 stderr 寫入兩個流，都是 JSON 友好的：

• 審計事件：每個安全相關事件的單行 JSON。將 stderr 管道傳輸到您的日誌聚合器。發出的事件包括 config.load、session.mint、session.refresh、device.authorize、device.verify、auth.denied、access.denied、inference、managed.serve、spend.blocked 和 admin.denied。欄位因事件而異：
  • 成功的 mint 和 refresh 事件攜帶 sub、email、client_ip 和結果
  • 拒絕事件攜帶原因、路徑和用戶端 IP，因為拒絕時不存在身份
  • inference 記錄哪個上游提供了請求以及回應狀態
  • admin.denied 記錄被拒絕的管理員 API 驗證嘗試，包括原因（invalid_key 或 no_credentials）、用戶端 IP、方法和路徑，不包括呈現的金鑰材料
• 運營日誌：人類可讀的 [gateway] 前綴行，用於啟動、警告和上游錯誤。CLAUDE_GATEWAY_LOG_LEVEL 環境變數控制詳細程度，接受 info、warn 或 error，預設為 info。它不影響審計事件，這些事件始終被發出。

​

健康

閘道提供 GET /healthz 作為活躍探針，GET /readyz 作為就緒探針；/readyz 驗證存儲是否可到達。兩者都豁免於 access_control.allow_cidrs，因此探針在鎖定的監聽器上保持工作。 OAuth 發現文件位於 /.well-known/oauth-authorization-server 也只在配置載入、OIDC 發現、上游用戶端構造和 Postgres 遷移全部成功後才傳回 200，因此它也充當端到端啟動檢查。 執行中的閘道也在 <public_url>/protocol 提供它接受的路徑和請求形狀的描述，與您執行的版本相符。內容在版本之間不穩定。

​

中斷行為

如果 Postgres 宕機，閘道本身繼續為已簽入的開發人員提供服務，新的簽入失敗。開發人員是否實際保持工作取決於您的協調器如何處理就緒：

• 現有會話：持有人令牌使用 JWT 祕密在本地驗證，會話重新整理不接觸存儲，閘道程序仍然可以提供推理
• 新簽入：失敗直到 Postgres 恢復，因為設備流及其速率限制計數器存在於 Postgres 中
• 支出限制執行：在中斷期間預設失敗開放，因此推理仍然流動；如果您寧願阻止也不願無計量執行，請將其翻轉為失敗關閉
• 就緒：/readyz 在中斷期間報告未就緒，因此在就緒上閘門流量的協調器一次從輪換中移除每個副本。在該拓撲中，所有流量，包括閘道仍然可以提供的推理，在負載平衡器處失敗，直到 Postgres 恢復。/healthz 上的活躍探針保持通過，因此副本不會重新啟動。如果您寧願已簽入的開發人員在存儲中斷期間保持工作，請將就緒探針指向 /healthz；成本是新簽入失敗對仍然報告就緒的副本。

如果您的 IdP 宕機，現有會話工作直到 ttl_hours，新登入和重新整理失敗。如果您的 IdP 有頻繁的維護窗口，設定更長的 ttl_hours。

​

JWT 祕密輪換

分三個步驟輪換簽名祕密，以便現有會話保持有效：

1. 生成新祕密。將其前置到 session.jwt_secret 陣列。
2. 滾動部署。新令牌使用新祕密簽名；舊令牌仍然驗證。
3. 在 ttl_hours 加上邊距後，移除舊祕密並再次滾動。

輪換也是在它們過期之前強制會話退出的唯一方法：持有人令牌根據 JWT 祕密在本地驗證，因此沒有按會話撤銷。直接替換祕密，不在陣列中保留舊祕密，一次使每個未完成的會話無效。對於個別離職，在您的 IdP 中取消配置使用者；他們的會話在 ttl_hours 內結束。

​

Postgres

閘道持有五個表，全部由其啟動時遷移建立： 30 秒迴圈過期 kv 行超過其 TTL，每小時掃描在支出表上強制保留窗口，因此沒有任何東西無限增長。沒有 支出限制 配置，只有 kv 被寫入。如果您的安全原則禁止應用程式角色的 DDL，預先建立這些表和 _migrations，使用管理員角色，並授予應用程式角色 SELECT, INSERT, UPDATE, DELETE 在每個上。 使用支出限制，丟失的資料庫意味著丟失支出追蹤和上限，不僅僅是開發人員重新登入，因此執行定期備份。要立即清除一個已離職的開發人員，而不是等待保留，直接執行 DELETE FROM principal_emails WHERE principal = '<sub>'；這移除唯一持有其電子郵件、名稱和群組的表。spend 和 admin_audit 行僅參考偽匿名 OIDC sub。

​

升級

副本是無狀態的，因此滾動重新啟動在任何時間都是安全的。閘道在啟動時執行架構遷移，這意味著部署新二進位檔案自我遷移資料庫。如果資料庫角色無法執行 DDL，預先建立架構，包括 _migrations 表，種子為當前版本；否則啟動失敗，嘗試 CREATE TABLE。 遷移是僅附加的，因此回滾到知道較少遷移的先前二進位檔案是安全的；它忽略額外的行。回滾也根據較舊二進位檔案的架構重新驗證 YAML，因此採用較新版本引入的金鑰的配置在較舊版本上啟動失敗。在回滾之前移除新金鑰。 因為您在自己的映像中固定閘道的版本，新 Claude Code 版本中的修復，包括安全修復，只有在您更新固定並重新部署時才會到達您的部署。將閘道包含在您用於持有生產認證的其他服務的相同修補週期中。

​

安全

本章節回答安全審查提出的問題：什麼資料流經閘道以及它流向何處、設計防禦的攻擊，以及哪些答案屬於合規性問卷。

​

資料流

​

威脅模型摘要

閘道位於您的網路周邊內，但個別開發人員筆記型電腦不被視為受信任。設計以三種方式考慮這一點：

• 開發人員持有短期 JWT 而不是原始上游金鑰。CLI 到閘道的腿使用 RFC 8628 設備授予，閘道與 IdP 的授權碼交換在預設配置中執行 PKCE，因此攔截的 IdP 授權碼是無用的。
• 設備驗證頁面強制執行同源 POST 和根據 RFC 8628 §5.1 的每 IP 速率限制。請參閱 使用者代碼暴力破解抵抗。
• 出站請求通過伺服器端請求偽造 (SSRF) 防護，解析 DNS、阻止連結本地和雲端中繼資料地址加上預設環回，並將連接固定到解析的 IP，因此操作員影響的 URL（例如 IdP 和 OTLP 目的地）無法重新導向到雲端中繼資料端點。RFC 1918 私有範圍被刻意允許，因為 IdP 和 OTLP 收集器通常存在於私有 IP 上。對於針對環回 IdP 或收集器的本地開發，在閘道的環境中設定 CLAUDE_GATEWAY_ALLOW_LOOPBACK=1；在生產中保持未設定。

如果您新增自己的出口控制，閘道必須在使用工作負載身份等實例中繼資料認證時到達中繼資料伺服器。 兩個威脅超出範圍，因為它們是您的基礎設施要保護的：

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

​

使用者代碼暴力破解抵抗

開發人員在 /device 驗證頁面中輸入的 user_code 是從 20 字元字母表中抽取的 8 個字元，產生 20⁸ 或約 2.56×10¹⁰ 個組合，並在 10 分鐘後過期。 閘道在設備授予端點上應用按 IP 速率限制，可透過 rate_limits 配置。如果許多開發人員從單一共享公司 NAT 地址簽入，請提高限制。限制僅適用於簽入流程，不適用於推理。

​

合規性態勢

• 資料駐留：閘道自己的資料平面不向 Anthropic 發送任何東西，除非 Anthropic API 是配置的上游；當它是時，您現有的資料處理協議適用於推理路徑。遙測、審計、身份和設定只流向您配置的目的地。
• 主機程序流量：主機程序是 Claude Code CLI，可以向 Anthropic 發送啟動分析和更新檢查。對於嚴格出口部署，在閘道的容器環境中設定 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1。
• 用戶端分析：CLI 在簽入到閘道時停用自己的使用分析，錯誤報告在第三方 API 表面上預設關閉。
• 用戶端機器：開發人員的 CLI 仍然向 Anthropic 發送 WebFetch 主機名檢查和版本檢查，除非設定 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 和 skipWebFetchPreflight: true。請參閱 資料使用。
• 調查評分：閘道認證停用 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。
• 漏洞披露：遵循 報告安全問題

​

故障排除

如有問題和反饋，請使用 Claude Code 支援，或在 Claude Code GitHub 儲存庫 上開啟問題。報告問題時，請包括：

• 閘道問題：相關窗口的閘道 stderr、您的 gateway.yaml（祕密已編輯）、閘道版本（顯示在 / 的登陸頁面和 /managed/settings 上的 x-cc-gateway-version 回應標頭中），以及最近變更的內容
• 登入問題：開發人員執行 claude --debug-file ./claude-debug.txt、重現，並發送該檔案加上相同窗口的閘道審計日誌
• 推理問題：請求的模型、配置的上游，以及請求的閘道審計日誌，記錄哪個上游提供了它以及回應狀態

​

相關

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