genmedia-for-commerce 基础设施部署指南:Cloud Run 与 Agent Runtime 双目标 Terraform 实践
genmedia-for-commerce 基础设施部署指南:Cloud Run 与 Agent Runtime 双目标 Terraform 实践
本指南以 ADK 示例项目 genmedia-for-commerce 的 infra/README.md 为骨架,系统讲解如何为"电商媒体生成智能体"(ADK agent + REST API + MCP server + React 前端)在 Google Cloud 上落地基础设施。你将掌握 make deploy 与 make deploy-agent-engine 两条部署路径的取舍、Terraform 各资源文件的职责与参数含义,以及从 agents-cli scaffold enhance 到手工 terraform apply 的完整实操流程。
一、两种部署目标:先想清楚要部署什么
genmedia-for-commerce 不是单一的 agent,而是一个由 ADK 智能体、REST API(VTO 虚拟试穿、spinning 旋转展示等)、MCP server 和 React 前端组成的完整应用。因此 infra/ 目录同时承载了两套部署语义,部署文档 将它们划分为两个目标:
| 对比维度 | Cloud Run(make deploy) |
Agent Runtime(make deploy-agent-engine) |
|---|---|---|
| 部署内容 | 完整应用:ADK agent + REST API + MCP server + React 前端 | 仅 ADK agent(会话式对话接口) |
| 打包方式 | 使用 Dockerfile 构建容器,gcloud run deploy --source . |
无需 Dockerfile,源码直接打包上传 |
| 适用场景 | 完整应用部署、自定义基础设施、事件驱动工作负载 | 托管基础设施、极简运维、纯 agent 部署 |
| 入口模块 | genmedia4commerce/fast_api_app.py |
genmedia4commerce/agent_engine_app.py |
| 关键限制 | — | REST API 端点(VTO、spinning 等)不包含在内,仍需要 Cloud Run 支撑 |
Cloud Run 路径的入口 fast_api_app.py 是一个"三合一"组合应用:通过 adk 的 get_fast_api_app 挂载 ADK agent API(chat、sessions 等),通过 mcp_server 路由暴露 REST 端点,再托管前端静态文件——这解释了为什么它代表"完整应用"。
二、两种上手路径:CLI 脚手架 vs 手工 Terraform
文档推荐的路径是使用 agents-cli 自动完成基础设施与 CI/CD 的搭建:
# 在项目根目录执行
agents-cli scaffold enhance . --cicd-runner github_actions
该命令会自动生成 GitHub Actions CI/CD 流水线所需的资源与配置。若你想完全掌控每一步,也可以跳过脚手架,手工执行 Terraform。无论选择哪条路径,底层的 Terraform 配置都位于 infra/terraform/ 目录,两者殊途同归。
手工部署的完整命令链
仓库的 Makefile 已将手工流程封装为四个目标,可对照阅读:
# 1. 一次性初始化基础设施(创建 Artifact Registry、Cloud Run、IAM 绑定)
make setup-infra
# 2. 预览将要发生的变更(等价于 terraform plan)
make tf-plan
# 3. 全量部署到 Cloud Run(完整应用,通过 Cloud Build 构建镜像)
make deploy-cloudrun
# 4. 仅将 ADK agent 部署到 Agent Runtime(源码直传,无容器)
make deploy-agent-engine
# 5. 清理基础设施
make tf-destroy
其中 setup-infra 的实现值得注意:它先校验 config.env 存在,设置 gcloud 项目,然后通过一段 TF_VARS 宏把 config.env 中的 PROJECT_ID、DEFAULT_REGION、SERVICE_NAME、MEMORY、CPU、TIMEOUT、CONCURRENCY、MIN_INSTANCES、MAX_INSTANCES 导出为 TF_VAR_* 环境变量,再执行 terraform init && terraform apply。这意味着你只需要维护一份 config.env,Terraform 变量会自动与之同步,无需重复编辑 terraform.tfvars。
三、Terraform 资源清单与逐文件解读
infra/terraform/ 共包含 8 个文件,职责划分非常清晰:
- main.tf:provider 与 API 启用
- variables.tf:全部输入变量及默认值
- cloudrun.tf:Cloud Run v2 服务
- iam.tf:服务账号与角色绑定
- artifact_registry.tf:Docker 镜像仓库
- storage.tf:媒体存储桶
- outputs.tf:部署产物输出
- terraform.tfvars.example:变量填写模板
3.1 provider 与 API 预启用(main.tf)
main.tf 要求 Terraform >= 1.0.0,同时声明 hashicorp/google 与 hashicorp/google-beta 两个 provider(均要求 >= 5.0.0),后者用于 IAP、service identity 等 beta 特性。最关键的是它会一次性启用 11 个 GCP API:
compute、cloudbuild、run、artifactregistry、aiplatform、
iap、cloudresourcemanager、storage、vision、iam、telemetry
这些 API 与部署链路一一对应:run 托管 Cloud Run、artifactregistry 承载镜像、aiplatform 支撑 Agent Engine 与 AI 推理、vision 服务视觉相关的 VTO/分类能力、iap 用于身份代理鉴权、telemetry 对接遥测日志。disable_on_destroy = false 意味着销毁基础设施时不会顺带停用 API。
3.2 输入变量与默认值(variables.tf)
variables.tf 定义了全部参数,结合 terraform.tfvars.example 可直接套用:
| 变量 | 默认值 | 说明 |
|---|---|---|
project_id |
无(必填) | GCP 项目 ID |
region |
us-central1 |
Cloud Run / Cloud Build 区域 |
service_name |
genmedia-for-commerce |
Cloud Run 服务名,同时派生仓库名 |
memory |
32Gi |
Cloud Run 内存配额(媒体生成负载较重) |
cpu |
8 |
CPU 配额 |
timeout |
3600 |
请求超时(秒),长耗时生成任务需要大值 |
concurrency |
7 |
单实例最大并发请求数 |
min_instances |
2 |
最小实例数(保证冷启动可控) |
max_instances |
10 |
最大实例数(弹性上限) |
模板文件同时给出两个可选配置:auth_mode(取值 none / iam / iap,默认 iam)用于选择鉴权模式;iap_access_domain 可在使用 IAP 时对整个域名放行。使用时按注释操作即可:
cp terraform.tfvars.example terraform.tfvars
# 编辑 terraform.tfvars,至少填入 project_id
3.3 Cloud Run v2 服务定义(cloudrun.tf)
cloudrun.tf 创建 google_cloud_run_v2_service.main,关键设计点:
ingress = "INGRESS_TRAFFIC_ALL":允许所有流量入口;- 缩放在
min_instance_count/max_instance_count之间弹性伸缩; image初始为占位符gcr.io/cloudrun/placeholder,实际镜像由 Cloud Build 在部署时替换——因此lifecycle块声明了ignore_changes = [template, client, client_version, invoker_iam_disabled],避免terraform apply回滚 Cloud Build 写入的镜像与模板;- 注入
PROJECT_ID与LOCATION两个环境变量; cpu_idle = false等价于关闭 CPU 节流(对应--no-cpu-throttling),确保长耗时生成任务期间 CPU 不被回收;- 使用专用服务账号
google_service_account.cloudrun.email运行。
3.4 双服务账号的 IAM 设计(iam.tf)
iam.tf 是本项目最值得研读的部分,它围绕三类身份做最小权限绑定:
- 默认 Compute Engine SA(
*-compute@developer.gserviceaccount.com):gcloud run deploy --source构建时由 Cloud Build 使用,授予storage.objectAdmin、artifactregistry.writer、logging.logWriter; - 专用 Cloud Run SA(
genmedia-cloudrun):运行时身份,授予aiplatform.user(调用 AI 平台/Agent Engine)、storage.objectAdmin(读写媒体桶)、logging.logWriter、iam.serviceAccountUser; - AI Platform 服务代理:通过
google_project_service_identity.aiplatform获取通用 AI Platform 服务账号,并显式授予 Reasoning Engine 服务代理(gcp-sa-aiplatform-re)storage.objectAdmin,这是 Agent Engine 运行时访问媒体文件的必要条件。
这种"构建身份 / 运行身份 / 平台服务代理"三层分离的模式,是生产级 agent 部署的安全基线。
3.5 镜像仓库与媒体桶(artifact_registry.tf / storage.tf)
artifact_registry.tf 创建 ${service_name}-repo 的 DOCKER 格式仓库,并内置清理策略 keep-recent:保留最近 10 个版本镜像,防止存储无限膨胀。
storage.tf 创建 ${project_id}-genmedia-for-commerce-media-payloads 桶,承载用户上传与 AI 输出媒体;开启 uniform_bucket_level_access = true(统一桶级访问控制),force_destroy = false 保护数据不被误删。
3.6 部署产物输出(outputs.tf)
outputs.tf 暴露 5 个关键输出:service_url(Cloud Run 访问地址)、project_id、region、service_name、artifact_registry_repo(形如 ${region}-docker.pkg.dev/${project_id}/${repo})以及 cloudrun_service_account,供 CI/CD 流水线消费。
四、Makefile 部署目标的执行细节
infra/README.md 提到的两个目标在 Makefile 中均有完整实现,可结合源码理解其差异:
make deploy:先用uv export导出依赖到genmedia4commerce/app_utils/.requirements.txt,再调用genmedia4commerce.app_utils.deploy,以genmedia4commerce/agent_engine_app的agent_engine对象为入口部署到 Agent Runtime;支持AGENT_IDENTITY=true启用每 agent 独立 IAM 身份(Preview),并可用SECRETS="KEY=SECRET_ID,..."注入密钥。make deploy-agent-engine:是deploy的资源定制版,额外通过--cpu=8 --memory=32Gi --min-instances=2 --max-instances=10 --container-concurrency=7显式声明与 Terraform 默认值一致的资源配额,并额外打包startup_scripts目录(内含 OpenCV 修复脚本 fix_opencv.sh)。make deploy-cloudrun:走gcloud run deploy --source .,参数与 Terraform 变量一一对应(--memory/--cpu/--timeout/--concurrency/--min-instances/--max-instances),绑定genmedia-cloudrun@$PROJECT_ID.iam.gserviceaccount.com,--no-allow-unauthenticated默认拒绝匿名访问,--no-cpu-throttling与 Terraform 的cpu_idle=false呼应;传入USE_IAP=true时追加--iap。
五、上手建议与注意事项
- 先跑 Agent Runtime 再跑 Cloud Run:如果只是验证 agent 对话能力,
make deploy-agent-engine无需 Docker、链路最短;需要 VTO、spinning 等 REST 端点或前端时再补 Cloud Run 部署。 make setup-infra只跑一次:它负责创建仓库、服务与 IAM 绑定,后续迭代部署(deploy-cloudrun)会通过 Cloud Build 覆盖镜像,无需重复执行。config.env是单一事实来源:Makefile 通过TF_VARS宏将其同步为 Terraform 变量,务必先cp config.env.example config.env并填写,否则setup-infra会直接报错退出。- 鉴权默认是 IAM 模式:
--no-allow-unauthenticated意味着需要具备相应 IAM 权限的调用方才能访问;需要浏览器直接访问时再评估 IAP(auth_mode = "iap")方案。 - 资源配额不可随意调小:媒体生成场景默认
32Gi内存 /8CPU /3600s超时,是模型推理与图像后处理的合理基线;贸然缩小可能导致 OOM 或请求超时。
六、小结
genmedia-for-commerce 的 infra/ 目录演示了 ADK 项目"一基座双目标"的部署范式:一套 Terraform 配置同时支撑 Cloud Run(完整应用)与 Agent Runtime(纯 agent)两条路径,通过 IAM 三层身份隔离、Artifact Registry 镜像保留策略、统一桶级访问控制等设计满足生产要求。无论你通过 agents-cli scaffold enhance 自动生成 CI/CD,还是手工执行 make setup-infra + make deploy-cloudrun,理解本指南中的变量映射与资源依赖,都能让部署过程完全透明可控。