前言¶
把 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 全託管平臺的三類資源展開，與官方產品定義一致：
- Services：通過穩定 HTTP 端點對外服務，無狀態實例按指標自動擴縮，也可承接事件與函數類場景。
- Jobs：可並行、可手動觸發或按計劃執行，運行至完成。
- 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。
