Claude Gateway on GCP：从参考部署到生产化检查清单

examples/gateway/gcp是本项目里最接近平台工程的一组样例。它展示如何把 Claude Gateway 部署到 Google Cloud并使用 Agent Platform 作为上游模型入口同时引入身份认证、数据库、密钥管理和托管配置下发。这个目录不是开箱即用的生产方案而是参考部署。它的价值在于把关键组件和部署顺序明确写出来方便平台团队按自己的网络、安全和运维标准改造。参考架构GCP 示例覆盖的组件包括Cloud Run 或 GKE用于运行claude gateway。Cloud SQL for PostgreSQL用作 Gateway store。Secret Manager用于保存 JWT、OIDC client secret、Postgres URL 等敏感信息。Google Workspace OIDC用于开发者登录和身份识别。Agent Platform也就是 Vertex AI 上游用于访问 Claude 模型。Terraform用于创建基础设施并管理配置。gateway.yaml.example是配置入口。它定义监听地址、public_url、OIDC、Session、Store、Upstreams、Telemetry、Managed policies、Admin API 和模型目录等部分。public_url 是部署中的关键点配置模板中特别强调listen.public_url。它会影响 IdP 的redirect_uri、OIDC discovery document 和 gateway token issuer不能依赖客户端可控的 Host header 推导。Cloud Run 的run.appURL 通常在第一次部署后才确定因此示例采用两阶段思路第一次用占位值完成基础部署拿到真实 URL 后再回填public_url重新发布配置并部署。Google OAuth Client 中注册的回调地址也必须与这个 host 对应。这个细节很重要。身份系统中 URL 不一致通常会导致登录失败如果错误地信任客户端转发头还可能引入安全问题。OIDC、Session 与 StoreOIDC 部分默认面向 Google Workspace。配置中包含issuer、client_id、client_secret、allowed_email_domains和 scopes。对于 Google模板还说明了 refresh token 相关参数以及 group-based RBAC 需要 Admin SDK Directory API 才能获取 Workspace groups。Session 使用jwt_secret和ttl_hours。模板建议密钥至少 32 字节并支持数组形式做密钥轮换。Store 使用 PostgreSQL并且是必需项。Gateway 没有 store 会拒绝启动。GCP 示例中 Postgres URL 通常来自 Cloud SQL 私网地址并通过 Secret Manager 注入。Upstream把模型访问统一到服务端upstreams示例使用provider: vertex指定 region、project_id并依赖 Cloud Run Service Account 或 GKE Workload Identity 进行 ADC 认证。这种方式避免在开发者本地分发静态云密钥。模型访问权限集中在 Gateway 运行身份上开发者通过 OIDC 登录 Gateway再由 Gateway 控制模型、策略和审计。模板还预留了多个 upstream 的扩展方式。团队可以按地域、模型可用性或故障转移需求配置多个上游。Managed policies 与遥测Gateway 不只是代理请求。配置中还预留了managed.policies可以根据邮箱域名或 group 匹配下发 CLI 托管设置。例如不同团队可使用不同模型列表或者统一拒绝读取.env和secrets目录。Telemetry 部分支持把 CLI 的 OTLP/HTTP 数据转发到 OpenTelemetry Collector并在服务端补充user.id、user.email和user.groups。这对平台团队做使用分析、成本治理和问题排查很有价值。需要注意的是日志和 trace 可能包含 Bash 命令或工具输入生产环境应明确评估隐私和合规要求后再开启。Terraform 的两阶段部署terraform/README.md说明 Terraform 会创建 Artifact Registry、VPC、Private Services Access、Cloud SQL、Secret、Cloud Run 等资源但不会替你构建和推送镜像。因此部署分成两阶段先 targeted apply 创建 Artifact Registry 仓库。下载 Claude Code linux-x64 release校验 sha256构建并推送 Docker 镜像。再执行完整terraform apply。这个设计避免 Terraform 直接承担镜像构建职责也让制品校验和发布过程更透明。生产团队可以把第二步替换为自己的 CI/CD 流程但仍保留相同的镜像标签和 Terraform 输入。私有访问与网络边界Terraform 示例默认使用 internal-only ingress。文档中明确指出Claude Code 的/login只接受私有地址上的 Gateway host因此公网上的 Cloud Run ingress 不能直接满足客户端登录场景。如果团队要让企业内网访问 internal-only Cloud Run需要配套Google APIs 的 Private Service Connect endpoint。针对run.app的 Cloud DNS private zone。从办公网络到 VPC endpoint 的 Cloud VPN 或 Interconnect 路由。这些通常属于网络团队或 hub project 管理范围示例模块不会自动创建。试点时可以从 VPC 内部完成 OAuth bootstrap生产化时则应把私有访问链路作为前置条件。生产化检查清单落地前至少检查以下事项gateway.yaml中没有残留REPLACE_ME。public_url与 OAuth redirect URI 完全一致。Secret Manager 中的 JWT、OIDC、Postgres、Admin key 等密钥有轮换策略。Cloud SQL 开启 deletion protection并明确备份和恢复策略。Cloud Run 或 GKE 的服务账号只拥有必要权限。Terraform state 使用远端 backend并防止提交到 Git。Telemetry 的 metrics、logs、traces 开关符合隐私要求。managed.policies中的模型列表和权限规则经过安全审查。私有访问链路已经由网络团队验证。参考部署的正确使用方式这个 GCP 目录不应该被直接复制到生产环境后就长期运行。更合适的方式是把它当成一份可执行架构说明先跑通最小链路再逐步替换为组织内标准的镜像构建、Secret 管理、网络接入、监控告警和变更流程。当 Claude Code 的使用规模从个人扩展到团队时Gateway 是把模型入口、身份、权限、遥测和策略集中起来的关键组件。本项目给出的 GCP 示例正好提供了从试点到平台化的落地起点。