2026/9/17 5:08:00
FEATURED · 精选文章 
agents-cli Cloud Run 部署基础设施详解Terraform 服务配置、Dockerfile 构建、会话类型与网络入口控制【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli本文围绕 agents-cli 的 Cloud Run 部署参考文档展开系统讲解脚手架生成的 Cloud Run Terraform 配置实例伸缩、并发、会话亲和、单阶段uvDockerfile 构建、FastAPI 服务入口与路由、三类会话后端In-memory / Cloud SQL / Agent Runtime的接入方式以及 ingress 与 IAP 网络安全策略。读完本文后你可以准确理解每个脚手架参数的默认值与源码依据并能在生产环境按源码级细节调整 Cloud Run 部署配置。前提本文所有配置均假设项目已通过/google-agents-cli-scaffold技能即agents-cli scaffold create/agents-cli scaffold enhance完成脚手架生成。若项目尚未 scaffold请先完成脚手架再阅读下文。一、Cloud Run Terraform 服务配置伸缩与资源默认值agents-cli 在脚手架时会将 Cloud Run 基础设施写入deployment/terraform/single-project/service.tf以及 CI/CD 场景下的cicd/service.tf变体。仓库中的模板文件位于 service.tf其中关键的伸缩与资源配置如下resources { limits { cpu 1 memory 4Gi } } max_instance_request_concurrency 8 scaling { min_instance_count 1 max_instance_count 10 } session_affinity true需要重点理解的四个配置项cpu/memory资源限额默认cpu 1、memory 4Gi。注意这里的cpu_idleCPU 分配策略由 Cloud Run 平台根据请求是否活跃决定计费方式——Cloud Run 在请求处理期间计费 CPU空闲时scale-to-zero 场景可配置CPU_ALLOCATION_MODE决定是否持续占用 CPU。min_instance_count冷启动规避模板中固定为1意味着生产部署始终保留一个温实例避免冷启动延迟。与之对应agents-cli deploy命令的--min-instances默认值是0默认 scale-to-zero即agents-cli deploy直接部署时开发/演示 agent 可以缩容到零而 Terraform 生成的配置则钉在1以保障生产可用性。max_instance_request_concurrency单实例并发默认8。单个 uvicorn 进程通过事件循环并发处理请求吞吐量来自并发度与水平扩容而非多 worker 进程。session_affinity会话亲和/粘性路由默认true将同一会话的请求路由到同一实例保证多轮对话状态的一致性。此外模板中还包含一条关键的lifecycle声明# This lifecycle block prevents Terraform from overwriting the container image when its # updated by Cloud Run deployments outside of Terraform (e.g., via CI/CD pipelines) lifecycle { ignore_changes [ template[0].containers[0].image, ] }从源码结构看这段注释明确了设计意图容器镜像由agents-cli deploy/ CI/CD 流水线更新lifecycle.ignore_changes防止terraform apply把镜像回滚到模板中的占位值us-docker.pkg.dev/cloudrun/container/hello。规格参数的耦合调整避免 OOM参考文档指向/google-agents-cli-deploy技能中的 Sizing a deployment 一节其核心结论在 SKILL.md 中有完整表述这里一并继承横向扩展而非纵向扩展容器只跑一个 async 进程吞吐来自--concurrency与--max-instances只有 profiling 显示事件循环或同步工具调用是 CPU 瓶颈时才提高--cpu。内存约束并发度每个并发请求在等待模型期间都会驻留完整工作集上下文窗口、历史、RAG 分片、响应缓冲区峰值内存 ≈ 基础内存 concurrency × 单请求内存。只提高--concurrency而不提高--memory是 OOM 的首要原因。默认并发偏保守8是为内存密集型RAG/多模态agent 设置的保护值轻量 agent 压测后可提升到 16–32。示例——4 倍吞吐要同步放大所有参数# 4x throughput: scale every param, not just one agents-cli deploy --cpu 4 --concurrency 16 --memory 16Gi --max-instances 20配合脚手架自带的压测tests/load_test/仓库模板见 load_test 目录驱动负载观察最大延迟与内存/OOM 重启再决定调参方向——最大延迟高 → 提高并发OOM → 加内存或降并发。二、Dockerfile基于 uv 的单阶段构建脚手架生成的 Python 项目使用单阶段构建依赖管理交给uv。模板文件见 DockerfileFROM python:3.12-slim RUN pip install --no-cache-dir uv0.8.13 WORKDIR /code COPY ./pyproject.toml ./README.md ./uv.lock* ./ COPY ./app ./app RUN uv sync --frozen ARG AGENT_VERSION0.0.0 ENV AGENT_VERSION${AGENT_VERSION} EXPOSE 8080 CMD [uv, run, uvicorn, app.fast_api_app:app, --host, 0.0.0.0, --port, 8080]逐行要点配置说明FROM python:3.12-slim基础镜像 Python 3.12 精简版单阶段构建pip install uv0.8.13版本钉死的uv保证构建可复现COPY ./pyproject.toml ./uv.lock*先拷贝依赖声明与锁文件利用构建缓存RUN uv sync --frozen按uv.lock精确安装依赖--frozen禁止改写锁文件EXPOSE 8080声明 8080 端口与 Cloud Run 的--port对应CMD uv run uvicorn ...单进程 uvicorn 监听0.0.0.0:8080值得注意的一个可选分支当项目通过--agent-gateway参数agents-cli create ... --agent-gateway或agents-cli scaffold enhance . --agent-gateway开启 Agent Gateway 支持时模板会在 Dockerfile 中追加ARG AGENT_GATEWAY_ROOT_CERTIFICATES及 CA 信任配置SSL_CERT_FILE、REQUESTS_CA_BUNDLE、GRPC_DEFAULT_SSL_ROOTS_FILE_PATH用于在出站流量经 egress gateway 做 TLS 解密检查时信任网关根证书。如果你的项目没有这段内容说明未启用 Agent Gateway。三、FastAPI 服务入口与路由每个脚手架生成的 Python 项目都以uvicorn app.fast_api_app:app在 8080 端口提供服务。具体暴露哪些路由取决于框架需查看项目根目录的app/fast_api_app.py。ADK 项目的路由面以仓库中的 ADK 模板 fast_api_app.py 为例其结构是contextlib.asynccontextmanager async def lifespan(app: FastAPI) - AsyncIterator[None]: from {{cookiecutter.agent_directory}}.agent import app as adk_app from {{cookiecutter.agent_directory}}.agent import root_agent runner Runner( appadk_app, session_serviceservices.get_session_service(), artifact_serviceservices.get_artifact_service(), auto_create_sessionTrue, ) app.state.runner runner app.state.agent_app_name adk_app.name await attach_a2a_routes( app, agentroot_agent, runnerrunner, task_storeInMemoryTaskStore(), rpc_pathf/a2a/{adk_app.name}, ) yield app: FastAPI get_fast_api_app( agents_dirAGENT_DIR, webTrue, artifact_service_uriservices.ARTIFACT_SERVICE_URI, allow_originsallow_origins, session_service_uriservices.SESSION_SERVICE_URI, otel_to_cloudotel_to_cloud, lifespanlifespan, )从源码可以确认 ADK 项目部署后提供ADK HTTP 面get_fast_api_app(webTrue, ...)挂载/run_sse、/apps/...等 ADK 流式 API 路由A2A 路由attach_a2a_routes挂载/a2a/{app_name}JSON-RPC agent card——A2A 内建于每个 ADK agentlifespan中的共享服务Runner使用services.get_session_service()/services.get_artifact_service()即下文第四节讨论的会话服务解析逻辑。另外ALLOW_ORIGINS环境变量可配置 CORS 允许的来源逗号分隔默认None即不开启自定义 CORS。四、会话类型In-memory / Cloud SQL / Agent Runtime参考文档给出的三类会话类型对照表如下会话接线是 ADK 脚手架行为但其使用的 Cloud SQL 基础设施与框架无关类型配置方式适用场景In-memory默认shared://session由app_utils/services.py解析为内存实现仅限本地开发实例重启即丢失Cloud SQL脚手架时传--session-type cloud_sql生产级持久化会话Postgres 15IAM 认证Agent Runtime托管 Agent Engine 会话agentengine://{resource_name}使用 Agent Runtime 作为会话后端时参考文档特别指出cloud_sql/agent_platform_sessions的具体会话 URI 如今是在app_utils/services.py内部构建的而不是在fast_api_app.py中。仓库模板 services.py 印证了这一设计文件顶部注册了两个进程级共享 URISESSION_SERVICE_URI shared://session、ARTIFACT_SERVICE_URI shared://artifact通过get_service_registry()注册到 ADK 的服务注册表使 ADK web 路由、A2A 路径与 reasoning_engine 适配器共享同一实例——在任一路由面上创建的会话对其它路由面可见。Cloud SQL 分支session_type cloud_sql时生成从环境变量DB_USER/DB_NAME/DB_PASS/INSTANCE_CONNECTION_NAME读取连接信息URL 编码后拼出 Unix socket 连接串走/cloudsql挂载点session_service_uri ( fpostgresqlasyncpg://{encoded_user}:{encoded_pass} f/{db_name}?host/cloudsql/{encoded_instance} )若环境变量缺失则优雅降级为InMemorySessionService。Agent Platform 会话分支session_type agent_platform_sessions通过agentplatformSDK 按display_name查找或自动创建 engine返回agentengine://{engine.resource_name}URIUSE_IN_MEMORY_SESSIONtrue时降级内存。默认分支优先读SESSION_SERVICE_URI环境变量其次若平台注入了GOOGLE_CLOUD_AGENT_ENGINE_ID则构造VertexAiSessionService否则回退InMemorySessionService。Cloud SQL 基础设施Terraform 自动配置Cloud SQL 的实例、数据库与 Unix socket 卷挂载全部由service.tf生成见 service.tf 的session_type cloud_sql条件块resource google_sql_database_instance session_db { name ${var.project_name}-db database_version POSTGRES_15 region var.region settings { tier db-custom-1-3840 backup_configuration { enabled false } # Enable IAM authentication database_flags { name cloudsql.iam_authentication value on } } }配套资源还包括random_password16 位随机口令、google_secret_manager_secretsecret_version口令入 Secret Manager、google_sql_user数据库用户。容器侧则通过volumes { cloud_sql_instance { ... } }挂载 Cloud SQL Unix socket并以volume_mounts挂到/cloudsql同时注入INSTANCE_CONNECTION_NAME、DB_PASSSecret Manager 引用、DB_NAME、DB_USER环境变量。手动部署警告若绕过 Terraform 直接使用gcloud run deploy --add-cloudsql-instances必须手动授予运行时服务账号roles/cloudsql.client角色否则连接会因授权错误失败。Terraform 管理的部署会自动处理该角色绑定。gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --memberserviceAccount:YOUR_RUNTIME_SA_EMAIL \ --roleroles/cloudsql.client五、网络与入口流量控制Ingress 默认值与收紧方式模板中默认入口为INGRESS_TRAFFIC_ALL公网可访问resource google_cloud_run_v2_service app { ingress INGRESS_TRAFFIC_ALL ... }需要收紧时修改service.tf中的ingress取值取值含义INGRESS_TRAFFIC_ALL默认公网入口INGRESS_TRAFFIC_INTERNAL_ONLY仅 VPC 内访问INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER内部 GCLB外部流量经全局负载均衡器IAPIdentity-Aware ProxyIAP 可通过部署开关直接启用仅适用于 Cloud Run 目标agents-cli deploy --iap从 cmd_deploy.py 源码可以看到--iap被声明为is_flagTrue、defaultFalse的选项帮助文本为 Enable Identity-Aware Proxy (Cloud Run)构造gcloud命令时若该标志为真则追加--iap参数。要点IAP 由deploy 标志配置而不是生成的 Terraform 变量——因此service.tf中看不到 IAP 配置启用后无需改任何代码即可要求请求携带 Google 身份认证用户/群组授权需在 Cloud Console 的 IAP 设置中管理。VPC ConnectorVPC connector默认不配置。若 agent 需要访问 VPC 内的私有资源私有 Cloud SQL、内部 API 等需要自行在自定义 Terraform 中添加 VPC egress 配置参见references/terraform-patterns.md的自定义基础设施模式。其它网络相关能力补充回滚Cloud Run 支持基于 revision 的即时流量切换回滚gcloud run revisions listgcloud run services update-traffic无需新提交未认证测试脚手架默认--no-allow-unauthenticated直接curl已部署服务时 403 属预期行为需携带Authorization: Bearer $(gcloud auth print-identity-token)请求头。六、部署验证与日志排查部署后可用agents-cli run --url service-url直接对已部署的 Cloud Run 服务发起带认证、会话与流式处理支持的请求更深入的测试自定义头、会话复用、压测参见同技能的references/testing-deployed-agents.md仓库路径 testing-deployed-agents.md。常见问题速查摘自 SKILL.md 故障排查表与 Cloud Run 强相关项问题解决方案冷启动太慢将 Cloud Run Terraform 配置中min_instance_count设为 0Cloud Run 503检查资源限额内存/CPU提高max_instance_count或查看容器崩溃日志Cloud SQL 连接失败 / 403手动部署时确认运行时服务账号已授roles/cloudsql.client部署失败或 agent 无响应查 Cloud Logginggcloud logging read resource.typecloud_run_revision AND resource.labels.service_nameSERVICE --projectPROJECT --limit50刚授完 IAM 角色仍 403IAM 传播非即时等待几分钟再重试不要反复重复授权小结Cloud Run 作为 agents-cli 三大部署目标之一另两个为 Agent Runtime 与 GKE其脚手架模板在仓库中集中在 cloud_run 部署目标目录 下按python/go/java/typescript分语言提供single-project与cicd两套 Terraform 变体。核心事实可以归纳为资源默认值cpu1、memory4Gi、concurrency8、min1/max10实例、session_affinitytrue全部可在 service.tf 中查看与修改构建python:3.12-slim 钉版uv的单阶段 Dockerfileuv sync --frozen保证可复现服务面uvicorn app.fast_api_app:app监听 8080ADK 项目额外提供/run_sse、/apps/...与/a2a/{app_name}路由会话内存默认/ Cloud SQLPostgres 15 IAM 认证 Secret Manager Unix socket 卷/ Agent Engineagentengine://三选一URI 解析集中在app_utils/services.py网络默认公网 ingress可收紧为 VPC 内部IAP 由agents-cli deploy --iap一键启用VPC connector 需自定义 Terraform。如需完整部署流程flag 全表、CI/CD 流水线、Secret Manager 接入、服务账号架构请继续阅读同目录的 SKILL.md 与 terraform-patterns.md。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
agents-cli Cloud Run 部署基础设施详解：Terraform 服务配置、Dockerfile 构建、会话类型与网络入口控制
agents-cli Cloud Run 部署基础设施详解Terraform 服务配置、Dockerfile 构建、会话类型与网络入口控制【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli本文围绕 agents-cli 的 Cloud Run 部署参考文档展开系统讲解脚手架生成的 Cloud Run Terraform 配置实例伸缩、并发、会话亲和、单阶段uvDockerfile 构建、FastAPI 服务入口与路由、三类会话后端In-memory / Cloud SQL / Agent Runtime的接入方式以及 ingress 与 IAP 网络安全策略。读完本文后你可以准确理解每个脚手架参数的默认值与源码依据并能在生产环境按源码级细节调整 Cloud Run 部署配置。前提本文所有配置均假设项目已通过/google-agents-cli-scaffold技能即agents-cli scaffold create/agents-cli scaffold enhance完成脚手架生成。若项目尚未 scaffold请先完成脚手架再阅读下文。一、Cloud Run Terraform 服务配置伸缩与资源默认值agents-cli 在脚手架时会将 Cloud Run 基础设施写入deployment/terraform/single-project/service.tf以及 CI/CD 场景下的cicd/service.tf变体。仓库中的模板文件位于 service.tf其中关键的伸缩与资源配置如下resources { limits { cpu 1 memory 4Gi } } max_instance_request_concurrency 8 scaling { min_instance_count 1 max_instance_count 10 } session_affinity true需要重点理解的四个配置项cpu/memory资源限额默认cpu 1、memory 4Gi。注意这里的cpu_idleCPU 分配策略由 Cloud Run 平台根据请求是否活跃决定计费方式——Cloud Run 在请求处理期间计费 CPU空闲时scale-to-zero 场景可配置CPU_ALLOCATION_MODE决定是否持续占用 CPU。min_instance_count冷启动规避模板中固定为1意味着生产部署始终保留一个温实例避免冷启动延迟。与之对应agents-cli deploy命令的--min-instances默认值是0默认 scale-to-zero即agents-cli deploy直接部署时开发/演示 agent 可以缩容到零而 Terraform 生成的配置则钉在1以保障生产可用性。max_instance_request_concurrency单实例并发默认8。单个 uvicorn 进程通过事件循环并发处理请求吞吐量来自并发度与水平扩容而非多 worker 进程。session_affinity会话亲和/粘性路由默认true将同一会话的请求路由到同一实例保证多轮对话状态的一致性。此外模板中还包含一条关键的lifecycle声明# This lifecycle block prevents Terraform from overwriting the container image when its # updated by Cloud Run deployments outside of Terraform (e.g., via CI/CD pipelines) lifecycle { ignore_changes [ template[0].containers[0].image, ] }从源码结构看这段注释明确了设计意图容器镜像由agents-cli deploy/ CI/CD 流水线更新lifecycle.ignore_changes防止terraform apply把镜像回滚到模板中的占位值us-docker.pkg.dev/cloudrun/container/hello。规格参数的耦合调整避免 OOM参考文档指向/google-agents-cli-deploy技能中的 Sizing a deployment 一节其核心结论在 SKILL.md 中有完整表述这里一并继承横向扩展而非纵向扩展容器只跑一个 async 进程吞吐来自--concurrency与--max-instances只有 profiling 显示事件循环或同步工具调用是 CPU 瓶颈时才提高--cpu。内存约束并发度每个并发请求在等待模型期间都会驻留完整工作集上下文窗口、历史、RAG 分片、响应缓冲区峰值内存 ≈ 基础内存 concurrency × 单请求内存。只提高--concurrency而不提高--memory是 OOM 的首要原因。默认并发偏保守8是为内存密集型RAG/多模态agent 设置的保护值轻量 agent 压测后可提升到 16–32。示例——4 倍吞吐要同步放大所有参数# 4x throughput: scale every param, not just one agents-cli deploy --cpu 4 --concurrency 16 --memory 16Gi --max-instances 20配合脚手架自带的压测tests/load_test/仓库模板见 load_test 目录驱动负载观察最大延迟与内存/OOM 重启再决定调参方向——最大延迟高 → 提高并发OOM → 加内存或降并发。二、Dockerfile基于 uv 的单阶段构建脚手架生成的 Python 项目使用单阶段构建依赖管理交给uv。模板文件见 DockerfileFROM python:3.12-slim RUN pip install --no-cache-dir uv0.8.13 WORKDIR /code COPY ./pyproject.toml ./README.md ./uv.lock* ./ COPY ./app ./app RUN uv sync --frozen ARG AGENT_VERSION0.0.0 ENV AGENT_VERSION${AGENT_VERSION} EXPOSE 8080 CMD [uv, run, uvicorn, app.fast_api_app:app, --host, 0.0.0.0, --port, 8080]逐行要点配置说明FROM python:3.12-slim基础镜像 Python 3.12 精简版单阶段构建pip install uv0.8.13版本钉死的uv保证构建可复现COPY ./pyproject.toml ./uv.lock*先拷贝依赖声明与锁文件利用构建缓存RUN uv sync --frozen按uv.lock精确安装依赖--frozen禁止改写锁文件EXPOSE 8080声明 8080 端口与 Cloud Run 的--port对应CMD uv run uvicorn ...单进程 uvicorn 监听0.0.0.0:8080值得注意的一个可选分支当项目通过--agent-gateway参数agents-cli create ... --agent-gateway或agents-cli scaffold enhance . --agent-gateway开启 Agent Gateway 支持时模板会在 Dockerfile 中追加ARG AGENT_GATEWAY_ROOT_CERTIFICATES及 CA 信任配置SSL_CERT_FILE、REQUESTS_CA_BUNDLE、GRPC_DEFAULT_SSL_ROOTS_FILE_PATH用于在出站流量经 egress gateway 做 TLS 解密检查时信任网关根证书。如果你的项目没有这段内容说明未启用 Agent Gateway。三、FastAPI 服务入口与路由每个脚手架生成的 Python 项目都以uvicorn app.fast_api_app:app在 8080 端口提供服务。具体暴露哪些路由取决于框架需查看项目根目录的app/fast_api_app.py。ADK 项目的路由面以仓库中的 ADK 模板 fast_api_app.py 为例其结构是contextlib.asynccontextmanager async def lifespan(app: FastAPI) - AsyncIterator[None]: from {{cookiecutter.agent_directory}}.agent import app as adk_app from {{cookiecutter.agent_directory}}.agent import root_agent runner Runner( appadk_app, session_serviceservices.get_session_service(), artifact_serviceservices.get_artifact_service(), auto_create_sessionTrue, ) app.state.runner runner app.state.agent_app_name adk_app.name await attach_a2a_routes( app, agentroot_agent, runnerrunner, task_storeInMemoryTaskStore(), rpc_pathf/a2a/{adk_app.name}, ) yield app: FastAPI get_fast_api_app( agents_dirAGENT_DIR, webTrue, artifact_service_uriservices.ARTIFACT_SERVICE_URI, allow_originsallow_origins, session_service_uriservices.SESSION_SERVICE_URI, otel_to_cloudotel_to_cloud, lifespanlifespan, )从源码可以确认 ADK 项目部署后提供ADK HTTP 面get_fast_api_app(webTrue, ...)挂载/run_sse、/apps/...等 ADK 流式 API 路由A2A 路由attach_a2a_routes挂载/a2a/{app_name}JSON-RPC agent card——A2A 内建于每个 ADK agentlifespan中的共享服务Runner使用services.get_session_service()/services.get_artifact_service()即下文第四节讨论的会话服务解析逻辑。另外ALLOW_ORIGINS环境变量可配置 CORS 允许的来源逗号分隔默认None即不开启自定义 CORS。四、会话类型In-memory / Cloud SQL / Agent Runtime参考文档给出的三类会话类型对照表如下会话接线是 ADK 脚手架行为但其使用的 Cloud SQL 基础设施与框架无关类型配置方式适用场景In-memory默认shared://session由app_utils/services.py解析为内存实现仅限本地开发实例重启即丢失Cloud SQL脚手架时传--session-type cloud_sql生产级持久化会话Postgres 15IAM 认证Agent Runtime托管 Agent Engine 会话agentengine://{resource_name}使用 Agent Runtime 作为会话后端时参考文档特别指出cloud_sql/agent_platform_sessions的具体会话 URI 如今是在app_utils/services.py内部构建的而不是在fast_api_app.py中。仓库模板 services.py 印证了这一设计文件顶部注册了两个进程级共享 URISESSION_SERVICE_URI shared://session、ARTIFACT_SERVICE_URI shared://artifact通过get_service_registry()注册到 ADK 的服务注册表使 ADK web 路由、A2A 路径与 reasoning_engine 适配器共享同一实例——在任一路由面上创建的会话对其它路由面可见。Cloud SQL 分支session_type cloud_sql时生成从环境变量DB_USER/DB_NAME/DB_PASS/INSTANCE_CONNECTION_NAME读取连接信息URL 编码后拼出 Unix socket 连接串走/cloudsql挂载点session_service_uri ( fpostgresqlasyncpg://{encoded_user}:{encoded_pass} f/{db_name}?host/cloudsql/{encoded_instance} )若环境变量缺失则优雅降级为InMemorySessionService。Agent Platform 会话分支session_type agent_platform_sessions通过agentplatformSDK 按display_name查找或自动创建 engine返回agentengine://{engine.resource_name}URIUSE_IN_MEMORY_SESSIONtrue时降级内存。默认分支优先读SESSION_SERVICE_URI环境变量其次若平台注入了GOOGLE_CLOUD_AGENT_ENGINE_ID则构造VertexAiSessionService否则回退InMemorySessionService。Cloud SQL 基础设施Terraform 自动配置Cloud SQL 的实例、数据库与 Unix socket 卷挂载全部由service.tf生成见 service.tf 的session_type cloud_sql条件块resource google_sql_database_instance session_db { name ${var.project_name}-db database_version POSTGRES_15 region var.region settings { tier db-custom-1-3840 backup_configuration { enabled false } # Enable IAM authentication database_flags { name cloudsql.iam_authentication value on } } }配套资源还包括random_password16 位随机口令、google_secret_manager_secretsecret_version口令入 Secret Manager、google_sql_user数据库用户。容器侧则通过volumes { cloud_sql_instance { ... } }挂载 Cloud SQL Unix socket并以volume_mounts挂到/cloudsql同时注入INSTANCE_CONNECTION_NAME、DB_PASSSecret Manager 引用、DB_NAME、DB_USER环境变量。手动部署警告若绕过 Terraform 直接使用gcloud run deploy --add-cloudsql-instances必须手动授予运行时服务账号roles/cloudsql.client角色否则连接会因授权错误失败。Terraform 管理的部署会自动处理该角色绑定。gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --memberserviceAccount:YOUR_RUNTIME_SA_EMAIL \ --roleroles/cloudsql.client五、网络与入口流量控制Ingress 默认值与收紧方式模板中默认入口为INGRESS_TRAFFIC_ALL公网可访问resource google_cloud_run_v2_service app { ingress INGRESS_TRAFFIC_ALL ... }需要收紧时修改service.tf中的ingress取值取值含义INGRESS_TRAFFIC_ALL默认公网入口INGRESS_TRAFFIC_INTERNAL_ONLY仅 VPC 内访问INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER内部 GCLB外部流量经全局负载均衡器IAPIdentity-Aware ProxyIAP 可通过部署开关直接启用仅适用于 Cloud Run 目标agents-cli deploy --iap从 cmd_deploy.py 源码可以看到--iap被声明为is_flagTrue、defaultFalse的选项帮助文本为 Enable Identity-Aware Proxy (Cloud Run)构造gcloud命令时若该标志为真则追加--iap参数。要点IAP 由deploy 标志配置而不是生成的 Terraform 变量——因此service.tf中看不到 IAP 配置启用后无需改任何代码即可要求请求携带 Google 身份认证用户/群组授权需在 Cloud Console 的 IAP 设置中管理。VPC ConnectorVPC connector默认不配置。若 agent 需要访问 VPC 内的私有资源私有 Cloud SQL、内部 API 等需要自行在自定义 Terraform 中添加 VPC egress 配置参见references/terraform-patterns.md的自定义基础设施模式。其它网络相关能力补充回滚Cloud Run 支持基于 revision 的即时流量切换回滚gcloud run revisions listgcloud run services update-traffic无需新提交未认证测试脚手架默认--no-allow-unauthenticated直接curl已部署服务时 403 属预期行为需携带Authorization: Bearer $(gcloud auth print-identity-token)请求头。六、部署验证与日志排查部署后可用agents-cli run --url service-url直接对已部署的 Cloud Run 服务发起带认证、会话与流式处理支持的请求更深入的测试自定义头、会话复用、压测参见同技能的references/testing-deployed-agents.md仓库路径 testing-deployed-agents.md。常见问题速查摘自 SKILL.md 故障排查表与 Cloud Run 强相关项问题解决方案冷启动太慢将 Cloud Run Terraform 配置中min_instance_count设为 0Cloud Run 503检查资源限额内存/CPU提高max_instance_count或查看容器崩溃日志Cloud SQL 连接失败 / 403手动部署时确认运行时服务账号已授roles/cloudsql.client部署失败或 agent 无响应查 Cloud Logginggcloud logging read resource.typecloud_run_revision AND resource.labels.service_nameSERVICE --projectPROJECT --limit50刚授完 IAM 角色仍 403IAM 传播非即时等待几分钟再重试不要反复重复授权小结Cloud Run 作为 agents-cli 三大部署目标之一另两个为 Agent Runtime 与 GKE其脚手架模板在仓库中集中在 cloud_run 部署目标目录 下按python/go/java/typescript分语言提供single-project与cicd两套 Terraform 变体。核心事实可以归纳为资源默认值cpu1、memory4Gi、concurrency8、min1/max10实例、session_affinitytrue全部可在 service.tf 中查看与修改构建python:3.12-slim 钉版uv的单阶段 Dockerfileuv sync --frozen保证可复现服务面uvicorn app.fast_api_app:app监听 8080ADK 项目额外提供/run_sse、/apps/...与/a2a/{app_name}路由会话内存默认/ Cloud SQLPostgres 15 IAM 认证 Secret Manager Unix socket 卷/ Agent Engineagentengine://三选一URI 解析集中在app_utils/services.py网络默认公网 ingress可收紧为 VPC 内部IAP 由agents-cli deploy --iap一键启用VPC connector 需自定义 Terraform。如需完整部署流程flag 全表、CI/CD 流水线、Secret Manager 接入、服务账号架构请继续阅读同目录的 SKILL.md 与 terraform-patterns.md。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
