Claude Code

Claude apps gateway 部署

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

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 运行要点

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 比