cloud-run-basics

Name: cloud-run-basics
Author: google

Cloud Run 基礎

Cloud Run 是一個全託管的應用程式平台，可在 Google 高度可擴展的基礎架構上執行您的程式碼、函式或容器。它抽象化了基礎架構管理，提供三種主要資源類型：

服務： 回應傳送至唯一且穩定端點的 HTTP 請求，使用無狀態執行個體，並根據多種關鍵指標自動調整規模，同時也能回應事件和函式。
任務： 執行可並行化的任務，這些任務會手動執行或依排程執行，並執行至完成。
工作者集區： 處理常駐的背景工作負載，例如拉取式工作負載，例如 Kafka 消費者、Pub/Sub 拉取佇列或 RabbitMQ 消費者。

先決條件

啟用 Cloud Run Admin API 和 Cloud Build API：

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

如果您的專案受到網域限制的組織政策限制未經驗證的呼叫，您需要按照測試私人服務中的說明存取已部署的服務。

必要角色

您需要以下角色才能部署 Cloud Run 資源：

專案的 Cloud Run 管理員 (roles/run.admin)
專案的 Cloud Run 原始碼開發人員 (roles/run.sourceDeveloper)
服務身分識別的服務帳戶使用者 (roles/iam.serviceAccountUser)
專案的日誌檢視者 (roles/logging.viewer)

除非您覆寫此行為，否則 Cloud Build 會自動使用 Compute Engine 預設服務帳戶作為建構原始碼和 Cloud Run 資源的預設 Cloud Build 服務帳戶。

為了讓 Cloud Build 建構您的原始碼，請授予 Cloud Build 服務帳戶專案的 Cloud Run 建構者 (roles/run.builder) 角色：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder \
    --quiet

將 PROJECT_ID 替換為您的 Google Cloud 專案 ID，並將 SERVICE_ACCOUNT_EMAIL_ADDRESS 替換為 Cloud Build 服務帳戶的電子郵件地址。

部署 Cloud Run 服務

您可以使用容器映像檔部署服務，或使用單一 Google Cloud CLI 命令直接從原始碼部署。

重要規則： 任何部署的程式碼都必須監聽 0.0.0.0（而非 127.0.0.1），並使用注入的 $PORT 環境變數（預設為 8080），否則會在啟動時崩潰。

部署容器映像檔到 Cloud Run

Cloud Run 在部署期間匯入您的容器映像檔。只要容器映像檔被服務版本使用，Cloud Run 就會保留此副本。當新的 Cloud Run 執行個體啟動時，不會從容器儲存庫中拉取容器映像檔。

支援的容器映像檔

您可以直接使用儲存在 Artifact Registry 或 Docker Hub 中的容器映像檔。Google 建議使用 Artifact Registry，因為 Docker Hub 映像檔會被快取最多一小時。

您可以透過設定 Artifact Registry 遠端儲存庫，使用來自其他公開或私人儲存庫（例如 JFrog Artifactory、Nexus 或 GitHub Container Registry）的容器映像檔。

您只應考慮使用 Docker Hub 部署熱門的容器映像檔，例如 Docker 官方映像檔或 Docker 贊助的 OSS 映像檔。為了提高可用性，Google 建議使用 Artifact Registry 遠端儲存庫部署這些 Docker Hub 映像檔。

若要部署容器映像檔，請執行以下命令：

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

請替換以下內容：

SERVICE_NAME：您要部署的服務名稱。服務名稱必須為 49 個字元或更少，且在每個區域和專案中必須是唯一的。如果服務尚不存在，此命令會在部署期間建立服務。您可以完全省略此參數，但如果省略，系統會提示您輸入服務名稱。
IMAGE_URL：容器映像檔的參考，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。如果您使用 Artifact Registry，則必須已建立儲存庫 REPO_NAME。URL 的格式為 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。請注意，如果您未提供 --image 旗標，deploy 命令將嘗試從原始碼部署。

從原始碼部署

有兩種不同的方式可以從原始碼部署服務：

從原始碼部署並建構（預設）：此選項使用 Google Cloud 的 buildpacks 和 Cloud Build，自動從您的原始碼建構容器映像檔，而無需在您的機器上安裝 Docker 或設定 buildpacks 或 Cloud Build。預設情況下，Cloud Run 使用 Cloud Build 提供的預設機器類型。
- 若要從原始碼部署並啟用自動基礎映像檔更新，請執行以下命令：
```
gcloud run deploy SERVICE_NAME --source . \
--base-image BASE_IMAGE \
--automatic-updates \
--quiet
```
  Cloud Run 僅支援使用 Google Cloud 的 buildpacks 基礎映像檔的自動基礎映像檔。
  - 若要使用 Dockerfile 從原始碼部署，請執行以下命令：
```
 gcloud run deploy SERVICE_NAME --source . --quiet
```
```
當您提供 Dockerfile 時，Cloud Build 會在雲端中執行它，並部署服務。
```
從原始碼部署但不建構（預覽版）：此選項直接將成品部署到 Cloud Run，跳過 Cloud Build 步驟。這可以實現快速的部署時間。若要從原始碼部署但不建構，請執行以下命令：
```
gcloud beta run deploy SERVICE_NAME \
 --source APPLICATION_PATH \
 --no-build \
 --base-image=BASE_IMAGE \
 --command=COMMAND \
 --args=ARG \
 --quiet
```
請替換以下內容：
- SERVICE_NAME：您的 Cloud Run 服務名稱。
- APPLICATION_PATH：您的應用程式在本機檔案系統中的位置。
- BASE_IMAGE：您要為應用程式使用的執行階段基礎映像檔。例如，us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24。您也可以使用僅限作業系統的基礎映像檔（例如 osonly24）部署預先編譯的二進位檔，而無需設定其他語言特定的執行階段元件。
- COMMAND：容器啟動時執行的命令。
- ARG：您傳送給容器命令的引數。如果您使用多個引數，請將每個引數指定在單獨的行上。
如需從原始碼部署但不建構的範例，請參閱從原始碼部署但不建構的範例。

建立並執行 Cloud Run 任務

若要建立新任務，請執行以下命令：

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

或者，使用 deploy 命令：

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

請替換以下內容：

JOB_NAME：您要建立的任務名稱。如果您省略此參數，執行命令時系統會提示您輸入任務名稱。
IMAGE_URL：容器映像檔的參考，例如 us-docker.pkg.dev/cloudrun/container/job:latest。
可選地，將 OPTIONS 替換為以下任何旗標：
- --tasks：接受大於或等於 1 的整數。預設值為 1；最大值為 10,000。每個任務都會獲得環境變數 CLOUD_RUN_TASK_INDEX（值介於 0 到任務數減 1 之間）以及 CLOUD_RUN_TASK_COUNT（即任務數）。
- --max-retries：失敗任務的重試次數。一旦任何任務超過此限制，整個任務就會被標記為失敗。例如，如果設定為 1，則失敗的任務將重試一次，總共嘗試兩次。預設值為 3。接受 0 到 10 的整數。
- --task-timeout：接受持續時間，例如 "2s"。預設值為 10 分鐘；最大值為 168 小時（7 天）。對於使用 GPU 的任務，最大可用逾時為 1 小時。
- --parallelism：可以並行執行的最大任務數。預設情況下，任務將盡快並行啟動。
- --execute-now：如果設定，則在建立任務後立即開始執行任務。相當於依序呼叫 gcloud run jobs create 和 gcloud run jobs execute。
除了上述選項之外，您還可以指定更多設定，例如環境變數或記憶體限制。

如需建立任務時可用選項的完整清單，請參閱 gcloud run jobs create 命令列文件。

等待任務建立完成。成功完成後，您會看到成功訊息。

若要執行現有任務，請執行以下命令：

gcloud run jobs execute JOB_NAME --quiet

如果您希望命令等待執行完成，請執行以下命令：

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

請替換以下內容：

JOB_NAME：任務的名稱。
REGION：可以找到資源的區域。例如 europe-west1。或者，設定 run/region 屬性。

部署工作者集區

您可以使用容器映像檔部署 Cloud Run 工作者集區，或直接從原始碼部署。

部署容器映像檔

您可以指定帶有標籤（例如 us-docker.pkg.dev/my-project/container/my-image:latest）或確切摘要（例如 us-docker.pkg.dev/my-project/container/my-image@sha256:41f34ab970ee...）的容器映像檔。

支援的容器映像檔

您可以直接使用儲存在 Artifact Registry 或 Docker Hub 中的容器映像檔。Google 建議使用 Artifact Registry，因為 Docker Hub 映像檔會被快取最多一小時。

您可以透過設定 Artifact Registry 遠端儲存庫，使用來自其他公開或私人儲存庫（例如 JFrog Artifactory、Nexus 或 GitHub Container Registry）的容器映像檔。

若要部署容器映像檔，請執行以下命令：

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

請替換以下內容：

WORKER_POOL_NAME：您要部署的工作者集區名稱。如果工作者集區尚不存在，此命令會在部署期間建立工作者集區。您可以完全省略此參數，但如果省略，系統會提示您輸入工作者集區名稱。
IMAGE_URL：包含工作者集區的容器映像檔參考，例如 us-docker.pkg.dev/cloudrun/container/worker-pool:latest。請注意，如果您未提供 --image 旗標，deploy 命令會嘗試從原始碼部署。

等待部署完成。成功完成後，Cloud Run 會顯示成功訊息以及已部署工作者集區的版本資訊。

從原始碼部署工作者集區

您可以使用單一 gcloud CLI 命令 gcloud run worker-pools deploy 搭配 --source 旗標，直接從原始碼將新的工作者集區或工作者集區版本部署到 Cloud Run。

如果您未提供 --image 或 --source 旗標，deploy 命令預設會進行原始碼部署。

在幕後，此命令使用 Google Cloud 的 buildpacks 和 Cloud Build，自動從您的原始碼建構容器映像檔，而無需在您的機器上安裝 Docker 或設定 buildpacks 或 Cloud Build。預設情況下，Cloud Run 使用 Cloud Build 提供的預設機器類型。

若要從原始碼部署工作者集區，請執行以下命令：

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

將 WORKER_POOL_NAME 替換為您想要的工作者集區名稱。

部署失敗時的處理方式：

IAM/權限錯誤： 請參閱 iam-security.md。
啟動時崩潰 / 健康檢查失敗： 立即使用 gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20 擷取日誌，以找出確切的執行階段錯誤。
原生相依性錯誤（Node/Python）： 如果使用 --no-build，請切換為 --source .（Buildpacks），以便為 Linux 正確編譯原生擴充功能。

參考目錄

核心概念：服務 vs. 任務 vs. 工作者集區、資源模型以及服務的自動調整行為。
CLI 使用方式：用於部署和管理的必要 gcloud run 命令。
用戶端程式庫：使用 Google Cloud 用戶端程式庫與 Cloud Run 互動。
MCP 使用方式：使用 Cloud Run 遠端 MCP 伺服器。
基礎架構即程式碼：服務、任務、工作者集區和 IAM 繫結的 Terraform 範例。
IAM 與安全性：角色、服務身分識別以及輸入/輸出控制。
網路最佳實務與成本最佳化：成本最佳化策略、Direct VPC Egress、IP 位址與連接埠耗盡策略、效能輸送量調整以及 MTU 設定。

如果您需要這些參考資料中未提供的產品資訊，請使用 Developer Knowledge MCP 伺服器的 search_documents 工具。

您可能也喜歡

claude-automation-recommender

33Kdevops-cloud

分析程式碼並推薦適合的 Claude Code 自動化方案（包含 Hooks、Subagents、Skills、Plugins 以及 MCP Servers）。當使用者詢問自動化推薦、希望最佳化 Claude Code 設定、提到要改善 Claude Code 工作流程、詢問如何為專案首次建置 Claude Code，或想瞭解應該使用哪些 Claude Code 功能時使用。

anthropics

獲取

context-mode

20Kdevops-cloud

Use context-mode tools (ctx_execute, ctx_execute_file) instead of Bash/cat when processing large outputs. Triggers: "analyze logs", "summarize output", "process data", "parse JSON", "filter results", "extract errors", "check build output", "analyze dependencies", "process API response", "large file analysis", "page snapshot", "browser snapshot", "DOM structure", "inspect page", "accessibility tree", "Playwright snapshot", "run tests", "test output", "coverage report", "git log", "recent commits", "diff between branches", "list containers", "pod status", "disk usage", "fetch docs", "API reference", "index documentation", "call API", "check response", "query results", "find TODOs", "count lines", "codebase statistics", "security audit", "outdated packages", "dependency tree", "cloud resources", "CI/CD output". Also triggers on ANY MCP tool output that may exceed 20 lines. Subagent routing is handled automatically via PreToolUse hook.