AWS 企业级 Claude 应用网关部署完整参考

AI 管理员在为其团队部署 Claude Code 和 Claude Desktop 时，需要对身份验证、模型访问、成本归因和支出执行进行集中控制。这些控制可降低运营开销，并在规模层面一致地应用治理策略。

Claude apps gateway 提供了一个自托管的治理层，位于这些应用与 Amazon Bedrock 或 Claude Platform on AWS 之间。

在发布公告的基础上，本文介绍了一个生产级参考部署，涵盖端到端架构、企业部署模式、成本和实施资源。

本节介绍参考部署拓扑，以及请求如何通过网关流动。

Claude apps gateway 随开发人员已在运行的同一 Claude Code CLI 二进制文件一起分发。以 claude gateway --config gateway.yaml 启动后，它以服务器模式运行并在启动时加载其 YAML 配置。在本参考部署中，容器在您虚拟私有云（VPC）内的 AWS Fargate 上运行。如果更适合您现有的架构，同一镜像也可以在 Amazon Elastic Kubernetes Service（Amazon EKS）或 Amazon Elastic Compute Cloud（Amazon EC2）上运行。

参考架构使用以下组件：

计算和状态：每个 AWS Fargate 任务运行一个无状态网关容器。Amazon Relational Database Service（Amazon RDS）for PostgreSQL 存储短期登录状态，包括设备代码和会话。当启用支出限制时，它还存储每用户支出计数器和审计记录。认证状态存储在数据库中，而不是任务中。这意味着任何任务都可以处理任何请求，无需在负载均衡器上设置粘性会话。

入口和私有 DNS：内部 Application Load Balancer 使用 AWS Certificate Manager 证书终止 TLS。Amazon Route 53 私有托管区域将网关解析为可通过 VPN、AWS Direct Connect 或等效私有连接访问的私有 IP 地址。

服务连接：VPC 端点将支持的 AWS 服务流量保留在私有网络内，而 NAT 网关提供其他所需的出口。

上游凭证：网关使用分配给网关任务的 AWS Identity and Access Management（IAM）角色向 Amazon Bedrock 进行身份验证。Claude Platform on AWS API 密钥和其他静态凭证保留在 AWS Secrets Manager 中。上游凭证不会分发给开发人员机器。

运维说明：将负载均衡器空闲超时配置为超过预期的最长无数据间隔。默认值为 60 秒。负载均衡器终止空闲时间超过配置超时的连接。检查延迟的非流式响应和流式块之间的暂停。

图 1：AWS 上 Claude apps gateway 的参考架构

登录（每个会话一次）。平台团队分发的托管设置指向 Claude Code 和 Claude Desktop 的网关私有 URL。当开发人员运行 /login 时，客户端启动 OAuth 2.0 设备授权授权，并打开浏览器通过您的 OpenID Connect（OIDC）身份提供商进行身份验证。浏览器还必须能够访问网关的私有端点，因为网关提供设备验证页面。身份验证后，网关颁发一个短期 bearer 令牌，默认有效期为一小时。随后会话在后台静默刷新。

推理（每次请求）。每个推理请求都携带 bearer 令牌。网关验证令牌、解析开发人员身份和组成员身份、应用匹配策略、评估适用的支出上限，然后将请求路由到 Amazon Bedrock 或 Claude Platform on AWS。响应流式传回客户端。客户端发出使用指标，网关通过 OpenTelemetry Protocol（OTLP）将指标转发到您配置的收集器。这些指标归因于用于策略评估的已认证身份。

有关部署脚本和配置模板，请参阅配套代码库。有关运维指导，请参阅部署指南。有关设备代码验证和令牌生命周期详情，请参阅 Claude apps gateway 文档。

网关解决了五个治理需求，每个需求在以下各节中描述。

1. 身份：SSO 身份验证

网关将身份验证委托给您的 OIDC 身份提供商。开发人员通过浏览器 SSO 登录一次。网关颁发短期令牌并在后台处理静默刷新。网关支持 OIDC 批准的提供商，包括 Okta、Microsoft Entra ID、Auth0、Keycloak 或 Amazon Cognito 等。

这为您提供了集中式 OIDC 身份验证，开发人员机器上无需上游凭证，通过身份提供商移除实现即时注销，以及跨请求的一致性每用户归因，无需自定义检测。

网关不维护自己的用户目录。没有需要预创建的账户，也无需配置 SCIM 同步。您的身份提供商分配给用户的组就是网关用于策略匹配的组，一一对应，没有翻译层。完全在您的身份提供商中管理用户和组，网关在下一次会话刷新时获取更改。注销就是从您的身份提供商中删除用户。他们的会话在配置的时间-to-live（默认 1 小时）内过期，无需凭证轮换。

以下示例显示使用 Microsoft Entra ID 配置的网关：

oidc:
  issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
  client_id: ${OIDC_CLIENT_ID}
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [company.com]
  groups_claim: roles

注意：Microsoft Entra ID 默认不包含组或角色声明。如果您的策略使用 match: {groups: [...]} 配合 Entra 应用角色，请在 OIDC 配置中添加 groups_claim: roles。没有此步骤，网关无法解析组成员身份，所有用户只能匹配默认策略。

有关各身份提供商的设置说明，请参阅身份提供商设置指南。以下图片从开发人员的角度展示了登录体验，包括 Claude Code 和 Claude Desktop。

图 2：通过网关进行身份验证

图 3：网关委托给您现有的 OIDC 身份提供商

图 4：在浏览器中授权设备

图 5：通过网关为 Claude Desktop 配置 Amazon Bedrock 推理

2. 策略：集中式模型访问和权限

网关在服务器端强制执行模型访问，并将工具权限作为托管设置分发，按身份提供商组划分范围。您可以在单个 YAML 块中定义每个团队可以使用的模型和功能。策略按声明顺序评估。选择第一个匹配项，然后合并到 match: {} 默认基础上。以 match: {} 策略结束列表。它作为兜底策略，适用于其组不匹配列表中前面特定策略的用户。没有它，未匹配的用户将获得完整目录访问权限。更改在一小时内传播到已连接的客户端，无需开发人员采取任何行动。

Managed:
  policies:
    # 承包商：仅限 Haiku，无网络访问
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-sonnet-5, claude-haiku-4-5]
        enforceAvailableModels: true
      permissions:
        deny: ["WebFetch", "WebSearch"]
    # 工程师：完整模型访问，带护栏
    - match: { groups: [engineers] }
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-5, claude-haiku-4-5]
      permissions:
        allow: [Read, Grep, Bash, Edit]
        deny: ["Read(./.env)", "Read(./secrets/**)"]
    # 兜底：其他每个已认证用户。必须放在最后。
    - match: {}
      cli:
        availableModels: [claude-haiku-4-5, claude-sonnet-5]

注意：在每个策略条目中包含 desktop: {} 以启用 Claude Desktop 客户端。没有它，网关会拒绝匹配该策略的用户的 Desktop 推理请求，即虽然登录成功。

模型访问在服务器端强制执行。一个组成员的组仅授予 Claude Haiku，即使使用修改后的客户端也无法绕过限制。Claude Code 和 Claude Desktop 中的模型选择器仅显示允许的模型。有关完整的策略模式（包括工具权限和托管设置传递），请参阅配置参考。

以下图片展示了策略强制执行的实际效果。

图 6：contractors 组的用户在 Claude Code 中请求 Claude Opus 4.8 时收到 400 错误

图 7：同一用户在 Claude Desktop 中只能访问 Claude Haiku

3. 遥测：每用户使用归因

客户端发出使用指标（claude_code.token.usage、claude_code.cost.usage 和 claude_code.active_time.total），归因于已认证开发人员的身份：用户 ID、电子邮件和组成员身份。

图 8：Claude Code 会话通过网关中继的 OpenTelemetry 指标，由采集器导出到 Amazon CloudWatch

网关通过 OpenTelemetry Protocol (OTLP) 将遥测数据中继到你配置的采集器。支持 OTLP 兼容的后端包括 Datadog、Splunk、Grafana，以及通过 AWS Distro for OpenTelemetry (ADOT) 采集器接入的 Amazon CloudWatch。

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      metrics: true
      logs: false
      traces: false

日志和追踪是可选接入的，因为它们可能包含源代码和提示内容。大多数部署从仅启用指标开始，这样可以在不暴露敏感数据的情况下提供每位用户的成本和使用量明细。更多信息请参阅 Claude apps gateway 配置页面。

4. 路由：具备故障转移的推理

网关按声明顺序将推理请求路由到一个或多个上游，在上游不可用、限流或超时时自动故障转移。跨提供商故障转移可能会改变适用的服务条款和数据处理地理区域。

你可以使用以下上游类型配置组合：

upstreams:
  # Amazon Bedrock（使用 ECS task role，无静态密钥）
  - name: bedrock-east
    provider: bedrock
    region: us-east-1
    auth: {}
  # 第二个区域的 Amazon Bedrock 用于故障转移
  - name: bedrock-west
    provider: bedrock
    region: us-west-2
    auth: {}
  # AWS 上的 Claude Platform（跨提供商回退）
  - name: claude-platform
    provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_01ABCDEFGHIJKLMN
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}

部署模式章节展示了如何组合这些构建块以应对常见场景。完整的上游配置和提供商特定的身份验证选项请参阅 upstreams 参考文档。

5. 消费上限：按用户预算执行

AWS Budgets 和 AWS Cost Explorer 提供账户级可见性及周期性聚合，适用于组织层面的成本治理。网关在这些工具之外补充了推理发生前的内联执行能力，并提供每位开发者的使用量明细。

消费上限在三个层级设置：组织级默认值、按组设置、按用户覆盖。用户级覆盖优先，其次是限制最严格的适用组上限，最后是组织默认值。如果任何层级都未设置上限，则消费无限制。当开发者达到其上限时，网关立即返回 HTTP 429。计数器在每个周期（每日、每周或每月）开始时自动重置。

# 组织级默认值：每位开发者每月 $500（金额以美分计，USD）
curl -X POST https://<gateway>/v1/organizations/spend_limits \
  -H "x-api-key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":{"type":"organization"},"amount":"50000","period":"monthly"}'

# 特定组的更严格上限：承包商每天 $10
curl -X POST https://<gateway>/v1/organizations/spend_limits \
  -H "x-api-key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":{"type":"rbac_group","rbac_group_id":"contractors"},"amount":"1000","period":"daily"}'

# 单个用户即时停用：上限设为零
curl -X POST https://<gateway>/v1/organizations/spend_limits \
  -H "x-api-key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":{"type":"user","user_id":"<oidc-sub>"},"amount":"0","period":"daily"}'

消费上限与模型访问控制是分开的。一个组可能拥有 Opus、Sonnet 和 Haiku 的访问权限。上限管理的是该访问权限的成本，而不是可用模型的种类。

管理员工作流：上限完全通过 Admin API 管理，没有管理员 UI。平台团队通常会自动化这一流程——在部署流水线中用脚本从签入的配置文件同步限制，或通过 Terraform 调用 API。GET /v1/organizations/spend_limits/effective 端点显示每位开发者的生效上限和周期至今的消费量，用于报表。

需要注意的局限性：消费是根据令牌计数按挂牌价格估算的。它是一个实时熔断器，而非账单。承诺使用折扣和协商费率不会反映在内。如果数据库不可用，消费执行默认会失败打开（fail open），允许推理继续进行。需要严格预算执行的组织可以设置 fail_closed_on_error: true 来阻止请求。权威账单请与 Amazon Bedrock 调用日志或 AWS Cost and Usage Report 进行对账。完整的 Admin API 参考和执行机制请参阅消费上限文档。

图 9：用户请求在达到每日消费上限时被 429 错误拒绝

如何部署网关取决于你组织的结构、流量模式和管理要求。没有单一正确的架构。

将所有 Claude 使用集中到网关可以简化配额管理，并在单一位置进行成本归属和策略执行。上线通常很即时：新开发者加入身份提供商组后即可获得访问权限。权衡是网关成为平台团队运营的共享基础设施，而需要原生 Amazon Bedrock 特性的工作负载无法通过它路由。

直接在专用账户中运行 Amazon Bedrock 可以为每个团队提供隔离的配额、无共享依赖，并可访问完整的 Amazon Bedrock 功能集。直接 Amazon Bedrock 部署可以使用 IAM 角色并保留集中计费和审计数据。权衡是失去网关的按开发者身份验证、策略、遥测和消费控制。

大多数组织以某种形式组合使用这两种方式。以下模式展示从单团队设置到多账户架构的常见配置。从最接近你当前环境的模式开始，随着使用量增长而演进。

模式 A：单团队，单一 AWS 区域

适用于：评估网关的团队或单一开发组位于单一区域的组织。

最小化部署：一个位于 us-east-1 的 Amazon Bedrock 上游、一个组织级每日消费上限、所有开发者享有相同的模型访问。从此开始，在用例需要时再增加复杂性。

图 10：单一账户和区域中的单团队，具有组织级的每日、每周和每月上限

模式 B：多团队分级访问

适用于：多个团队需要不同模型访问级别和消费上限的组织。身份提供商的组驱动差异化策略：

平台工程：Opus + Sonnet + Haiku，每日 $50。

应用开发者：Sonnet + Haiku，每日 $20。

承包商：仅限 Haiku，每日 $5，拒绝网络工具。

组限制由每位开发者单独继承，不作为团队预算共享。Admin API 按开发者报告消费并附带组元数据，因此团队总计必须单独汇总。平台团队可以在部署流水线中用脚本从签入的配置文件同步限制。

图 11：单一账户和区域中的多个团队，具有团队级的每日、每周和每月上限

模式 C：混合 Amazon Bedrock + AWS 上的 Claude Platform

适用于：希望以 Amazon Bedrock 为首选上游、以 AWS 上的 Claude Platform 作为溢出容量的组织。请注意，跨提供商故障转移可能会改变适用的服务条款和数据处理地理区域。

upstreams:
  - name: claude-platform
    provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_01ABCDEFGHIJKLMN
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}
  - name: bedrock
    provider: bedrock
    region: us-east-1
    auth: {}

请求首先发送到 Amazon Bedrock。只有在限流或中断时，网关才会回退到 AWS 上的 Claude Platform。

图 12：单一账户中的多个上游，使用 Amazon Bedrock 和 AWS 上的 Claude Platform 进行故障转移

模式 D：开发者工具用网关，应用直接使用 Amazon Bedrock

适用于：开发者工具需要治理（SSO、消费上限、遥测）但生产应用直接调用 Amazon Bedrock（具有隔离配额和原生特性）的组织。

图 13：生产工作负载保留在专用 Amazon Bedrock 账户上，使用 Amazon Bedrock Knowledge Bases、Agents 和 Flows 等网关不代理的原生特性

模式 E：多账户（共享服务）

适用于：中央平台团队运营网关，各个业务单元在独立账户中拥有自己的 Amazon Bedrock 访问权限的组织。

账单会落入各个团队自己的账户。网关根据模型配置将请求路由到正确的上游。

图 14：跨多个账户的多个团队，Amazon Bedrock 消费按账户独立计费

网关部署在一个共享服务账户中。每个业务单元的 Amazon Bedrock 使用量会单独记入其对应的 AWS 账户。网关本身不会在不同上游之间原生扮演不同的 IAM 角色。多账户路由需要在上游配置中明确传入凭证。将这些凭证存储在 AWS Secrets Manager 中并按计划轮换。长期有效的访问密钥是安全性和运营上的重大权衡。建议引入一个外部流程，定期将短期 AWS Security Token Service（AWS STS）凭证刷新到网关的运行环境中，以降低风险暴露。

Claude apps gateway 为平台团队提供了一个统一的控制点，用于管理 AWS 上的 Claude Code 和 Claude Desktop。一套容器、一个 YAML 配置文件，五大能力：SSO 身份认证、分组级模型策略、用户级遥测、多区域路由与故障转移，以及消费上限。

不按席位收费。使用 Amazon Bedrock 作为上游时，不会再有开发数据离开你的 AWS 账户。开发者运行的是他们已经熟悉的相同 claude 二进制文件。初次登录后，网关对他们完全透明。

要开始使用，请克隆配套的 GitHub 仓库并选择两条路径之一。两者都会部署相同的 Amazon ECS Fargate：内部 ALB、Amazon RDS for PostgreSQL、ECR、Secrets Manager、IAM 任务角色，以及 ADOT 遥测采集器。选择幂等的 setup.sh 脚本可以获得对每一步 AWS 调用的完整可见性，或者使用 AWS Cloud Development Kit（AWS CDK）堆栈以获得托管的生命周期管理。配置详情请参阅 claude apps gateway 文档。