genmedia-for-commerce 基础设施部署指南:Cloud Run 与 Agent Runtime 双目标 Terraform 实践

原创2026-09-15 10:40:141,757 阅读
文章标签:示例工程AI Agent人工智能AI 技能

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 个文件,职责划分非常清晰:

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 是本项目最值得研读的部分,它围绕三类身份做最小权限绑定:

  1. 默认 Compute Engine SA(*-compute@developer.gserviceaccount.com):gcloud run deploy --source 构建时由 Cloud Build 使用,授予 storage.objectAdmin、artifactregistry.writer、logging.logWriter;
  2. 专用 Cloud Run SA(genmedia-cloudrun):运行时身份,授予 aiplatform.user(调用 AI 平台/Agent Engine)、storage.objectAdmin(读写媒体桶)、logging.logWriter、iam.serviceAccountUser;
  3. 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。

五、上手建议与注意事项

  1. 先跑 Agent Runtime 再跑 Cloud Run:如果只是验证 agent 对话能力,make deploy-agent-engine 无需 Docker、链路最短;需要 VTO、spinning 等 REST 端点或前端时再补 Cloud Run 部署。
  2. make setup-infra 只跑一次:它负责创建仓库、服务与 IAM 绑定,后续迭代部署(deploy-cloudrun)会通过 Cloud Build 覆盖镜像,无需重复执行。
  3. config.env 是单一事实来源:Makefile 通过 TF_VARS 宏将其同步为 Terraform 变量,务必先 cp config.env.example config.env 并填写,否则 setup-infra 会直接报错退出。
  4. 鉴权默认是 IAM 模式:--no-allow-unauthenticated 意味着需要具备相应 IAM 权限的调用方才能访问;需要浏览器直接访问时再评估 IAP(auth_mode = "iap")方案。
  5. 资源配额不可随意调小:媒体生成场景默认 32Gi 内存 / 8 CPU / 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,理解本指南中的变量映射与资源依赖,都能让部署过程完全透明可控。

登录后查看全文
adk-recipes