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 不包含组。要在 Google 作为 IdP 时使用基于组的 allowed_groups 或 managed.policies，配置 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 颁发者，请运行单独的实例。
• 无服务器：如果设置 min-instances: 1 以避免冷启动时的 OIDC 发现，Cloud Run 可以正常工作。Lambda 和 Cloud Functions 无法使用，因为网关是一个长时间运行的 HTTP 服务器。

• 在除 provider: anthropic 之外的所有上游上，一旦流静默约 15 秒，网关就会写入一个 SSE ping。
• 在 provider: anthropic 上，网关会原样透传响应，包括 Anthropic API 自身的 ping。

​

为网关选择地址

• 私有地址：将网关置于内部负载均衡器或 VPN 之后，并使用仅解析为私有地址的主机名，例如 RFC 1918 或 CGNAT 100.64.0.0/10。用户的机器可以使用任何地址。私有网络前提条件列出了接受的地址范围。
• 声明的地址块：如果您的内部网络使用您的组织拥有的公共 IPv4 地址空间，请在 gatewayInternalNetworks 托管设置中列出该地址块。网关和用户的机器都必须位于该地址块中。请参阅允许网关使用您拥有的公共地址空间。

​

容器镜像

1. 从固定版本中下载适用于您镜像架构的 Linux 构建版本；下载 URL 请参阅安装特定版本。
2. 按照二进制完整性和代码签名中的说明，根据该版本经过 GPG 签名的 manifest.json 对其进行验证。
3. 将其复制到构建上下文中。

• 基于 glibc 的镜像：glibc 构建版本唯一的动态依赖是 glibc 库。基于 musl 的镜像需要 linux-x64-musl 或 linux-arm64-musl 构建版本，其唯一的动态依赖是 musl。
• 可写的状态目录：网关可以以任何用户身份运行，但精简镜像没有可写的主目录。将 CLAUDE_CONFIG_DIR 设置为可写路径，例如 /tmp/.claude。
• 容器命令：claude gateway --config /etc/claude/gateway.yaml，以只读方式挂载配置文件，并以环境变量的形式提供密钥；网关在 listen.port 上监听，默认为 8080。

​

Kubernetes

• 从 ConfigMap 挂载配置，从 Secret 挂载密钥；在 YAML 中通过 ${file:/path/to/secret} 或以环境变量的形式引用密钥
• 在 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 标头时会记录一条警告。如果负载均衡器应当列入 listen.trusted_proxies，请在更改任何其他内容之前先将其列入。如果开发人员仍然共享一个地址，请提高 rate_limits。
• 许多开发人员共享少量 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）和用户的身份
  • guardrail.trace 记录触发了哪个过滤器，不包含匹配的文本
  • 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 设置而不记录 PII。它不影响审计事件，这些事件总是被发出。

​

以 JSON 格式写入运维日志

{"severity":"INFO","time":"2026-11-04T17:03:21.512Z","message":"claude gateway listening on http://0.0.0.0:8080"}

​

健康

​

并发上游请求

• 添加副本。
• 提高每个副本上的限制。在网关容器上设置 BUN_CONFIG_MAX_HTTP_REQUESTS 环境变量为 1 到 65535 之间的整数，然后重启容器。

​

使 API_TIMEOUT_MS 高于网关的首字节时间

• provider: anthropic：将 API_TIMEOUT_MS 设置为高于您的上游发送其第一个事件所需的最长时间。
• 其他所有上游：将其设置为比您的上游返回响应标头所需的最长时间多出 20 秒以上。网关在这些标头之后约 15 秒发送其第一个 keepalive ping，除非上游的第一个事件更早到达。早于 v2.1.229 的网关不发送 ping，因此在那里请使用 provider: anthropic 规则。

​

使用首字节截止时间更快地重试未得到应答的请求

export CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS=60000

​

中断行为

• 现有会话：持有者令牌使用 JWT 密钥在本地验证，会话刷新不接触存储，网关进程仍然可以提供推理
• 新登录：失败直到 Postgres 恢复，因为设备流及其速率限制计数器存在于 Postgres 中
• 支出限制执行：在中断期间默认失败开放，因此推理仍然流动；如果您宁愿阻止而不是无计量运行，将其翻转为失败关闭
• 就绪：默认情况下，/readyz 在 Postgres 无法访问时立即报告未就绪，因此每个副本一次失败其就绪检查。在流量仅到达通过检查的副本的地方，所有流量，包括网关仍然可以提供的推理，在 Postgres 恢复前失败。/healthz 上的活跃探针在整个过程中继续通过。

​

就绪宽限期

​

JWT 密钥轮换

1. 生成一个新密钥。将其前置到 session.jwt_secret 数组。
2. 滚动部署。新令牌使用新密钥签名；旧令牌仍然验证。
3. 在 ttl_hours 加上一个边距之后，移除旧密钥并再次滚动。

​

Postgres

• 数据库：PostgreSQL 本身，自托管或托管均可，版本为最低版本或更高。仅实现 Postgres 协议的数据库（例如分布式 SQL 数据库）不受支持。
• 地址：store.postgres_url 接受一个主机。如果数据库有多个节点，请使用位于它们前面的地址，例如您的托管服务的端点、负载均衡器或虚拟 IP。设置一个比故障转移所需时间更长的就绪宽限期。

​

确定连接池大小

• 副本：统计同时运行的最大数量。从您的自动扩展最大值开始，如果您不使用自动扩展，则从副本数开始，再加上滚动更新在停止旧副本之前启动的额外副本。在使用默认设置的 Amazon ECS 上以及在 Cloud Run 上，额外副本可能与原数量一样多。
• 剩余连接：取数据库的 max_connections，然后减去数据库保留的连接以及其他客户端持有的连接。PostgreSQL 保留 superuser_reserved_connections，默认为三个。托管服务可能保留更多，因此请查看其文档。

• 数据库：提高其 max_connections
• 副本：运行更少的副本，或让您的编排器在滚动更新中启动更少的额外副本
• 连接池：降低 store.max_connections，但在启用支出限制时，请使其足够大以满足每个副本的负载。否则支出检查可能在等待连接时超时，网关会记录 spend check failed: spend precheck timed out。

​

升级

• 排空窗口：在网关容器上设置 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 检查。 如果您打开 仅代理出口，该地址检查会移到您的转发代理：网关交付主机名，代理的允许列表必须拒绝这些目的地。 仅当网关必须合法到达的某些内容存在于本地环回时（例如本地开发 IdP 或 localhost 上的 sidecar OTLP 收集器），在网关的环境中设置 CLAUDE_GATEWAY_ALLOW_LOOPBACK=1。该变量为每个操作员配置的 URL 放宽本地环回块，也跳过启动时警告，该警告检查 pod 是否可以到达云元数据端点，因此更倾向于为收集器提供其自己的内部地址。

• 受损的网关主机：主机既持有上游凭证，又向每个连接的开发者分发 托管设置，因此对网关配置的控制与对您的 MDM 的控制相当。CLI 的 批准对话框 用于 shell 能力设置限制无声更改，但不替代主机安全。
• 恶意 OIDC 提供商：提供商签署网关信任的 id_tokens，因此它可以声称任何身份。审查和保护您的 IdP 是您的责任。

​

用户代码暴力破解抵抗

​

合规性态势

• 数据驻留：网关自己的数据平面除非 Anthropic API 是配置的上游，否则不向 Anthropic 发送任何内容；当它是时，您现有的数据处理协议适用于推理路径。遥测、审计、身份和设置仅去往您配置的目的地。
• 主机进程流量：主机进程是 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 终止入口在普通 HTTP 副本前面，在两种情况下都设置 listen.public_url。网关不拒绝普通 HTTP。IdP 必须在生产中提供 HTTPS，Postgres 支持 ?sslmode=require。在您的入口处设置 Strict-Transport-Security。
• 漏洞披露：遵循 报告安全问题

​

插件市场请求

• 市场列表：不包含该市场的 strictKnownMarketplaces 允许列表，或指明该市场的 blockedMarketplaces 条目
• 环境变量：在托管的 env 块 中将 CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL 设置为 "1"

​

故障排除

• 网关问题：相关时间窗口内网关的 stderr、您的 gateway.yaml（已隐藏密钥）、网关版本（显示在 / 的登陆页面和 /managed/settings 的 x-cc-gateway-version 响应头中），以及最近的更改
• 登录问题：开发者运行 claude --debug-file ./claude-debug.txt、重现问题，然后发送该文件以及同一时间窗口内网关的审计日志
• 推理问题：请求的模型、配置的上游服务，以及该请求的网关审计日志，其中记录了由哪个上游提供服务以及响应状态

​

登录后请求头过大

• 网关版本早于 v2.1.284：升级网关
• 设置了 limits.max_request_header_bytes：提高该值或删除该键
• 以上均不适用，或之后仍出现 431：让您的 IdP 发出更少的组。身份提供者设置介绍了 Okta、Microsoft Entra ID 和 Google Workspace 如何提供组

• oidc.allowed_groups：决定谁可以登录
• admin.admin_groups：决定谁可以使用其网关会话调用管理 API
• managed.policies 中的 match.groups：决定哪个策略适用于开发者
• 上游上的 groups：决定哪些上游为开发者提供服务
• rbac_group 支出上限：决定哪些组上限适用于开发者

​

长时间思考导致代理超时

• 第一个请求：一个流，它传送首个响应事件 message_start，然后在 Claude 思考期间仅发送 ping。在默认设置下，Claude Code 会在约 12.5 分钟后结束该流。
• 其余 10 个：同一个请求，以非流式方式发送并随后重试，默认总共发送 10 次。它们不会收到 ping，因此较慢的回复会触发代理的超时。

​

确认原因

Error streaming, falling back to non-streaming mode: Stream idle timeout - no chunks received

​

选择值

​

通过策略下发该值

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_STREAM_IDLE_TIMEOUT_MS: "1800000"

​

Anthropic API 上游上的长时间思考

• 长时间请求：一个流，它传送 message_start，然后在 Claude 思考期间仅发送 ping。在默认设置下，Claude Code 会在约 20 分钟后结束它；提高该变量后，结束时间会相应推迟。
• 错误：Claude Code 随后以非流式方式发送的请求。每个请求都会因网关返回的 502 而失败；如果代理的超时时间短于网关的等待时间，则会因代理的 504 而失败。该等待时间即 timeouts.upstream_ttfb_ms，此修复无需提高它。

​

相关

• Claude 应用网关概述：快速入门和开发者连接
• 配置参考：每个 gateway.yaml 选项