前言¶

把 HTTP API、定时批处理或常驻拉取型后台跑在 Google Cloud 上，常见路径是查文档、拼 gcloud 参数、再对照 IAM 与镜像来源。Cloud Run 同时提供 Service、Job、Worker pool 三类资源，命令和前置条件并不完全一样；在 Cursor 等 Agent 里口述「帮我部署」，模型也容易漏掉监听地址、$PORT 或构建账号权限这类硬性要求。

下面介绍 Google 官方仓库中的 cloud-run-basics Skill：把 Cloud Run 的概念、前置 API/角色，以及三类资源的部署与排错步骤写进 SKILL.md，供 Agent 在需要时按规程执行。

这是什么¶

cloud-run-basics 是 google/skills 仓库里的一条 Agent Skill（metadata 版本 1.0.0，分类 Serverless）。它面向 Agent Skills 生态：以说明文档而非可执行代码，教 AI 助手何时、如何操作 Cloud Run。

官方 description 概括为：管理 Cloud Run services、jobs 与 worker pools——部署响应 HTTP 的应用（services）、手动或按计划执行的任务（jobs）、以及 Kafka/Pub/Sub pull/RabbitMQ 等拉取型常驻后台（worker pools）。

Skill 本体路径：skills/cloud/cloud-run-basics。同仓库还有 references/（核心概念、CLI、IAM、Terraform、MCP 等），Skill 正文会指向这些参考页。

核心功能¶

Skill 正文围绕 Cloud Run 全托管平台的三类资源展开，与官方产品定义一致：

1. Services：通过稳定 HTTP 端点对外服务，无状态实例按指标自动扩缩，也可承接事件与函数类场景。
2. Jobs：可并行、可手动触发或按计划执行，运行至完成。
3. Worker pools：常驻后台，适合 pull 型负载（如 Kafka consumer、Pub/Sub pull、RabbitMQ consumer）。

除概念外，Skill 还固化了一组实操内容（均来自官方 SKILL.md）：

• 前置条件：启用 Cloud Run Admin API 与 Cloud Build API；列出部署所需的 IAM 角色，以及为 Cloud Build 默认服务账号授予 roles/run.builder 的绑定命令。
• Service 部署：容器镜像部署、从源码部署（buildpacks / Dockerfile）、以及 Preview 的 --no-build 源码直部署参数说明。
• Job：gcloud run jobs create / deploy、execute 及常用 flags（--tasks、--max-retries、--task-timeout、--parallelism、--execute-now 等）。
• Worker pool：gcloud run worker-pools deploy（镜像或 --source .）。
• 部署失败排查：IAM、启动崩溃与日志查询、原生依赖与 --no-build 的取舍。

对做 Agent 后端的同学，Serverless 常用来承接工具调用或轻量 API；该 Skill 把 Google 推荐的 CLI 路径和关键约束写在一起，减少 Agent 自行「猜命令」的空间。

安装与启用¶

Skill 随 google/skills 整包分发，官方安装方式为 skills.sh 所文档化的 CLI：

npx skills add google/skills

按提示选择要安装的 Skill（可只选 cloud-run-basics）、目标 Agent，以及作用域（项目或全局）。环境若无 npx，需先安装带 npm/npx 的 Node.js。

更新已安装 Skill：

npx skills update

社区索引（如 awesome-agent-skills）将 Cursor、Claude Code、Codex、GitHub Copilot 等列为兼容 Agent；各平台具体挂载方式以各自文档为准。google/skills 仓库统一通过 npx skills add 完成选择与配置，本文不展开未在官方仓库写明的产品内路径。

安装后，在对话中描述 Cloud Run 部署或运维意图即可；Agent 应在匹配到「管理 Cloud Run / 部署无服务器应用」类任务时加载该 Skill 并按其中步骤操作（仍需本机已配置 gcloud 与有效 GCP 项目权限）。

典型用法¶

以下示例均摘自 Skill 官方正文，替换占位符后在已授权项目中执行。

1. 启用 API¶

gcloud services enable run.googleapis.com cloudbuild.googleapis.com --quiet

2. 部署 Cloud Run Service（容器镜像）¶

gcloud run deploy SERVICE_NAME \
    --image IMAGE_URL \
    --region us-central1 \
    --allow-unauthenticated \
    --quiet

IMAGE_URL 示例：us-docker.pkg.dev/cloudrun/container/hello:latest。Skill 建议使用 Artifact Registry；Docker Hub 镜像存在缓存时效，生产环境更推荐通过 Artifact Registry remote repository 拉取。

硬性规则（Skill 标注为 CRITICAL）： 进程必须监听 0.0.0.0（不能仅监听 127.0.0.1），并使用注入的环境变量 $PORT（默认 8080），否则实例会在启动阶段失败。

3. 从源码部署 Service（含 Dockerfile）¶

gcloud run deploy SERVICE_NAME --source . --quiet

目录中存在 Dockerfile 时，由 Cloud Build 在云端构建并部署。若使用 buildpacks 且需自动基础镜像更新，可使用 --base-image 与 --automatic-updates（仅支持 Google buildpacks 基础镜像）。

4. 创建并执行 Job¶

创建：

gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS --quiet

或：

gcloud run jobs deploy JOB_NAME --image IMAGE_URL OPTIONS --quiet

执行已有 Job：

gcloud run jobs execute JOB_NAME --quiet

需要等待执行结束：

gcloud run jobs execute JOB_NAME --wait --region=REGION --quiet

5. 部署 Worker pool¶

镜像方式：

gcloud run worker-pools deploy WORKER_POOL_NAME --image IMAGE_URL --quiet

源码方式：

gcloud run worker-pools deploy WORKER_POOL_NAME --source . --quiet

6. 启动失败时查日志¶

Skill 建议在健康检查失败时立即拉取日志，例如：

gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20

更细的 IAM、网络与成本说明见 Skill 目录下的 references/ 文件；产品文档缺口时，正文还提到可通过 Developer Knowledge MCP 的 search_documents 检索。

适用场景与注意¶

适合谁

• 已在用或计划用 Google Cloud，希望 Agent 按官方步骤完成 Cloud Run 三类资源的创建与执行。
• 团队把 Agent 工具服务、批处理或消息消费部署到 Serverless，需要统一「API 启用 → 角色 → gcloud 命令 → 排错」话术。

使用注意

• Skill 是操作指南，不替代 GCP 计费、组织策略与网络安全策略；若项目限制未认证调用，需按 Cloud Run 文档测试私有服务访问方式。
• 部署依赖 Cloud Build 时，必须为构建用服务账号授予 roles/run.builder（Skill 给出了 gcloud projects add-iam-policy-binding 模板）。
• --no-build 源码部署属于 Preview，参数较多，适合熟悉 runtime base image 的场景；Node/Python 原生依赖编译问题，Skill 建议改回 --source . 走 buildpacks。
• Service 名称在同一 region 与 project 内唯一且不超过 49 字符；Job 的 --tasks 上限为 10000，--task-timeout 最长 168 小时（GPU 任务最长 1 小时）。

结尾¶

cloud-run-basics 把 Cloud Run 的三类资源、CLI 部署路径和常见故障处理写进 Agent 可读的 Skill，适合作为「在 GCP 上落地无服务器后端」时的官方参照。安装入口为 npx skills add google/skills，Skill 源码与参考文档见：https://github.com/google/skills/tree/main/skills/cloud/cloud-run-basics。