启用 API

启用演练使用的服务 API：

gcloud services enable \
aiplatform.googleapis.com \
artifactregistry.googleapis.com \
sqladmin.googleapis.com \
secretmanager.googleapis.com \
iamcredentials.googleapis.com \
iam.googleapis.com \
compute.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
container.googleapis.com

所需的 API 取决于部署路径：

• compute 和 servicenetworking：私有 IP Cloud SQL 路径所需
• run：仅限 Cloud Run
• container：仅限 GKE

创建服务账户并授予 IAM

网关作为专用服务账户运行，有权调用 Google Cloud 的 Agent Platform。它通过 VPC 使用密码用户访问 Cloud SQL，因此不需要 Cloud SQL IAM 角色：

gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"
SA="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--member="serviceAccount:${SA}" --role="roles/aiplatform.user" --condition=None

然后在 Model Garden 中为项目启用 Claude 模型；模型发布到特定区域，因此请检查每个模型卡。

构建镜像并将其推送到 Artifact Registry

根据容器镜像要求构建镜像，使用 linux-x64 glibc 二进制文件，然后推送：

gcloud artifacts repositories create claude-gateway \
--repository-format=docker --location="$REGION"
gcloud auth configure-docker "${REGION}-docker.pkg.dev" --quiet

# Cloud Run 需要 linux/amd64。--provenance=false 避免 buildx OCI
# 镜像索引被 Cloud Run 拒绝。
docker build --platform=linux/amd64 --provenance=false \
-t "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>" .
docker push "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>"

为 PostgreSQL 配置 Cloud SQL

通过私有服务访问在 VPC 上创建实例，使其没有公共 IP；这也满足强制执行 constraints/sql.restrictPublicIp 的项目：

VPC=cc-gateway-vpc
gcloud compute networks create "$VPC" --subnet-mode=custom
gcloud compute networks subnets create cc-gateway-subnet \
--network="$VPC" --region="$REGION" --range=10.0.0.0/24

# 私有服务访问：每个 VPC 一次
gcloud compute addresses create "google-managed-services-${VPC}" \
--global --purpose=VPC_PEERING --prefix-length=16 --network="$VPC"
gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges="google-managed-services-${VPC}" --network="$VPC"

gcloud sql instances create claude-gateway-db \
--database-version=POSTGRES_16 --tier=db-g1-small --region="$REGION" \
--network="projects/${PROJECT_ID}/global/networks/${VPC}" --no-assign-ip
gcloud sql databases create claude_gateway --instance=claude-gateway-db
PGPASS="$(openssl rand -hex 24)"
gcloud sql users create gateway --instance=claude-gateway-db --password="$PGPASS"

PRIVATE_IP="$(gcloud sql instances describe claude-gateway-db \
--format='value(ipAddresses[0].ipAddress)')"
GATEWAY_POSTGRES_URL="postgres://gateway:${PGPASS}@${PRIVATE_IP}:5432/claude_gateway?sslmode=require"

Cloud Run 或 GKE 运行时必须在此 VPC 上或路由到此 VPC。

编写 gateway.yaml

upstreams 块使用 auth: {} 指向 Google Cloud 的 Agent Platform，因此网关通过运行时服务账户的应用默认凭证进行身份验证。有关每个字段，请参阅配置参考。

两个 listen 字段描述网关的前端：

• public_url：外部 https:// 源，对于任何非环回绑定都是必需的；请参阅 listen 参考。网关仅从此值构建 IdP redirect_uri 和其发现文档，从不从 X-Forwarded-* 标头构建。
• trusted_proxies：前端的源范围。网关仅在 TCP 对等体在此列表中时才遵守 X-Forwarded-For，然后遍历链越过受信任的跳跃，因此按 IP 登录速率限制和审计事件记录开发者 IP 而不是负载均衡器的 IP。

设置 trusted_proxies 以匹配您的前端。类 gce 的外部 GKE Ingress 未列出：它配置一个公共转发规则地址，/login 私有网络检查拒绝该地址。

下面的示例使用内部负载均衡器前置 Cloud Run 的值。

listen:
host: 0.0.0.0
port: 8080
public_url: https://claude-gateway.internal.example.com
trusted_proxies: [169.254.0.0/16, <your-proxy-only-subnet-cidr>]

oidc:
issuer: https://accounts.google.com
client_id: <your-oauth-client-id>
client_secret: ${OIDC_CLIENT_SECRET}           # GKE: ${file:/secrets/oidc-client-secret}
allowed_email_domains: [example.com]
# Google 忽略 offline_access；这些产生刷新令牌：
scopes: [openid, profile, email]
extra_auth_params: { access_type: offline, prompt: consent }

session:
jwt_secret: ${GATEWAY_JWT_SECRET}              # GKE: ${file:/secrets/jwt-secret}

store:
postgres_url: ${GATEWAY_POSTGRES_URL}          # GKE: ${file:/secrets/postgres-url}

upstreams:
- provider: vertex
region: <your-region>                        # 必须匹配 $REGION
project_id: <your-project>
auth: {} # 通过运行时服务账户的 ADC

在 Secret Manager 中存储密钥

创建四个密钥并向 claude-gateway 服务账户授予 roles/secretmanager.secretAccessor：

密钥到达容器的方式因路径而异：

• 在 GKE 上，它们通过 Secret Manager CSI 驱动程序作为文件挂载，gateway.yaml 引用 ${file:/secrets/...}。
• 在 Cloud Run 上，它无法将多个密钥挂载到一个目录中，gateway.yaml 作为文件挂载，其他三个作为环境变量注入，因此 gateway.yaml 改为引用 ${GATEWAY_JWT_SECRET}、${OIDC_CLIENT_SECRET} 和 ${GATEWAY_POSTGRES_URL}。

部署

gcloud run deploy claude-gateway \
--image="${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>" \
--region="$REGION" \
--service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com" \
--min-instances=1 \
--max-instances=8 \
--timeout=3600 \
--ingress=internal \
--network="$VPC" --subnet=cc-gateway-subnet --vpc-egress=private-ranges-only \
--set-secrets=/etc/claude/gateway.yaml=gateway-config:latest,GATEWAY_JWT_SECRET=gateway-jwt-secret:latest,OIDC_CLIENT_SECRET=gateway-oidc-client-secret:latest,GATEWAY_POSTGRES_URL=gateway-postgres-url:latest \
--no-invoker-iam-check

gcloud container clusters update <cluster> --region="$REGION" \
--workload-pool="${PROJECT_ID}.svc.id.goog"
# 在标准集群上，现有节点池也需要 GKE_METADATA；
# Autopilot 默认启用此功能。
gcloud container node-pools update <pool> --cluster=<cluster> \
--region="$REGION" --workload-metadata=GKE_METADATA

kubectl create namespace claude-gateway
kubectl create serviceaccount gateway -n claude-gateway

gcloud iam service-accounts add-iam-policy-binding \
"claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com" \
--role roles/iam.workloadIdentityUser \
--member "serviceAccount:${PROJECT_ID}.svc.id.goog[claude-gateway/gateway]"

kubectl annotate serviceaccount gateway -n claude-gateway \
iam.gke.io/gcp-service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com"

将网关 URL 推送到开发者机器

网关现在正在运行，但开发者在网关 URL 在其机器上之前无法从 /login 到达它。通过 MDM 将完整的托管设置片段部署到每个设备，具有 forceLoginMethod、forceLoginGatewayUrl 和 parentSettingsBehavior: "merge" 选择加入。登录选择器中没有网关选项供开发者手动选择。