# Claude apps gateway 部署

> 官方 Claude apps gateway 的私网部署、OIDC、Kubernetes、Cloud Run、GCP 示例、Postgres、健康检查、升级和缓存透传边界。

URL: https://docs.passion8.cc/docs/claude-code/gateway-cloud-deployment
Language: zh-CN
Publisher: Passion8

Claude apps gateway 是 Anthropic 随 `claude` binary 提供的自托管 gateway。它让开发者用企业 IdP 登录,再把 Claude Code 请求转发到 Anthropic API、Bedrock、Google Cloud Agent Platform、Microsoft Foundry 或 Claude Platform on AWS。它和通用 `ANTHROPIC_BASE_URL` 网关一样处理模型请求,但还承担 SSO、managed settings、spend limits 和 telemetry。




官方要求 gateway 登录入口部署在私网或受控网络中。公开互联网地址会被登录安全检查拒绝,因为 gateway 能向客户端下发会运行命令的策略。




## 什么时候用 Claude apps gateway

| 选择 | 适合 | 不适合 |
| --- | --- | --- |
| Claude apps gateway | 需要 SSO、组策略、managed settings、spend limits、OTLP,并想路由到多个 provider | 无人值守 CI 没有人完成浏览器登录 |
| Passion8 / 自定义 LLM gateway | 已有网关、成本路由、模型池或内部计费 | 需要官方 apps gateway 的 IdP 登录和 managed settings |
| 直连 provider | 小团队、CI、简单 API key 或 cloud IAM | 需要集中预算、统一审计和 per-user attribution |

如果开发者只设置 `ANTHROPIC_BASE_URL` 而没有 gateway credential,本机保存的 claude.ai 登录可能仍作为 credential 使用。使用 `ANTHROPIC_AUTH_TOKEN` 或 apps gateway `/login` 后,账单和限额会落到 gateway 后面的 provider account。

## 部署步骤

| 阶段 | 关键动作 | 验收 |
| --- | --- | --- |
| IdP | 注册 OIDC confidential app,回调 URL 为 `https://<gateway>/oauth/callback` | discovery、email、groups 或 roles claim 正常 |
| 容器 | 使用固定版本的 Linux `claude` binary 构建镜像 | GPG manifest 校验,非 root,有可写 `CLAUDE_CONFIG_DIR` |
| 平台 | Kubernetes、Cloud Run 或自有平台部署 | `/healthz`、`/readyz`、`/.well-known/oauth-authorization-server` 正常 |
| 策略 | 下发 `forceLoginMethod`、`forceLoginGatewayUrl` | 客户端 `/login` 出现 gateway 选项 |
| 运维 | 日志、Postgres、spend limits、升级和密钥轮换 | audit event、OTLP、备份、rollback runbook 可用 |

Kubernetes 和 Cloud Run 都应把 TLS 终止放在前端代理,后端 replica 可以是普通 HTTP。要设置 `listen.public_url` 和 `listen.trusted_proxies`,否则回调 URL、per-IP 限速和 audit IP 都可能不对。

## OIDC 注意点

| IdP | 重点 |
| --- | --- |
| Okta | org authorization server 可能不带 email/groups,需要 `userinfo_fallback` |
| Microsoft Entra ID | groups 常是 Object ID,也可以用 app roles 并把 claim 配成 `roles` |
| Google Workspace | id token 不带 groups,组策略需要 Admin SDK Directory API 或改用 email domain |
| Keycloak / Dex | 确认 `/.well-known/openid-configuration`、authorization-code flow 和 refresh token |

如果 IdP 不支持 refresh token,可以提高 `session.ttl_hours`,但离职或禁用用户的收敛会变慢。

## Kubernetes 运行要点

```yaml title="Deployment 摘要"
containers:
  - name: claude-gateway
    image: registry.example.com/claude-gateway:2.1.x
    command: ["claude", "gateway", "--config", "/etc/claude/gateway.yaml"]
    readinessProbe:
      httpGet:
        path: /readyz
        port: 8080
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
```

建议:

- config 通过 ConfigMap 或只读 secret volume 挂载。
- OIDC secret、JWT secret、Postgres URL、上游 API key 走 secret manager。
- 使用 workload identity,不要把云厂商长期 Key 放进镜像。
- Ingress 或 internal load balancer 的源地址要写进 `trusted_proxies`。
- Postgres outage 时决定 `/readyz` 是否让负载均衡摘除所有 replica。

## Google Cloud 部署轮廓

官方 GCP 示例把 gateway 部署到 Cloud Run 或 GKE,Postgres 使用 Cloud SQL private IP,secrets 使用 Secret Manager,上游使用 Vertex Agent Platform。

| 组件 | Cloud Run 路径 | GKE 路径 |
| --- | --- | --- |
| Runtime | Cloud Run service,min instances 1 | GKE Deployment |
| 网络 | internal-and-cloud-load-balancing,私有 DNS 或内部 LB | internal Ingress 和 proxy-only subnet |
| 数据库 | Cloud SQL PostgreSQL private IP | Cloud SQL PostgreSQL private IP |
| 身份 | service account 调用 Agent Platform | Workload Identity |
| Secrets | Secret Manager env / file mount | Secret Manager CSI driver |

Cloud Run 的 `*.run.app` 默认解析到公网地址。生产登录通常要放在内部 Application Load Balancer 后,或由网络团队提供 Private Service Connect 和私有 DNS。

## 运行和升级

| 项 | 处理 |
| --- | --- |
| 日志 | stderr 中有 audit events 和 `[gateway]` operational logs |
| 健康检查 | `/healthz` 只看进程活性,`/readyz` 还检查 store |
| Postgres | 保存 device grants、rate limits、spend、admin audit、principal emails |
| JWT secret | 新 secret 放数组第一位,等 TTL 过后再移除旧 secret |
| 升级 | 新 binary 启动时做 schema migration,replica stateless 可滚动 |
| 回滚 | migration append-only,但旧 binary 不认识的新 config key 会失败 |

如果启用 spend limits,Postgres 不只是登录状态,还是预算状态。要做备份、retention 和 fail-open/fail-closed 决策。

## 缓存和协议透传

| 检查 | 为什么影响 5m / 1h |
| --- | --- |
| SSE 不被反向代理缓冲 | Claude Code 依赖流式 tool use 和增量响应 |
| `anthropic-beta` 原样透传 | tool search、context management、1h cache 等能力依赖 beta |
| `system` array 不重写 | attribution block 和 cache key 依赖顺序 |
| `tools` 和 `cache_control` 不剥字段 | MCP、deferred tools 和 prompt cache 依赖 |
| `usage` 保留 cache tokens | 才能看 `cache_read_input_tokens` 和 creation/read 比 |

1 小时 TTL 只有在客户端、gateway 和上游都支持时才成立。否则应明确降级为 5 分钟,并在 telemetry 中标记。

## 官方参考

- [Run Claude Code through a gateway](https://code.claude.com/docs/en/gateways.md)
- [Claude apps gateway deployment and operations](https://code.claude.com/docs/en/claude-apps-gateway-deploy.md)
- [Deploy Claude apps gateway on Google Cloud](https://code.claude.com/docs/en/claude-apps-gateway-on-gcp.md)
- [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway.md)
- [Gateway protocol reference](https://code.claude.com/docs/en/llm-gateway-protocol.md)

## 相关页面



- [网关与协议](https://docs.passion8.cc/docs/claude-code/gateway): Base URL、headers/body、模型发现、attribution 和常见错误。
- [Gateway 运维](https://docs.passion8.cc/docs/claude-code/gateway-operations): OIDC、Postgres、spend limits、模型发现和 Server-managed settings 限制。
- [企业部署总览](https://docs.passion8.cc/docs/claude-code/enterprise-deployment-overview): provider、认证、managed settings、权限和观测的决策顺序。
- [监控与分析](https://docs.passion8.cc/docs/claude-code/monitoring): OpenTelemetry、analytics、traceparent、隐私和 Passion8 观测边界。