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 发行者，运行单独的实例。
• 无服务器：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 设置而不记录 PII。它不影响审计事件，这些事件总是被发出。

​

健康

​

并发上游请求

• 添加副本。
• 提高每个副本上的限制。在网关容器上设置 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 检查。 如果您打开 仅代理出口，该地址检查会移到您的转发代理：网关交付主机名，代理的允许列表必须拒绝这些目的地。 仅当网关必须合法到达的某些内容存在于本地环回时（例如本地开发 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。
• 漏洞披露：遵循 报告安全问题

​

故障排除

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

​

相关

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