AI Skills
cloud-run-basics

cloud-run-basics

热门

管理 Cloud Run 服务、任务和工作者池。当您需要部署响应 HTTP 请求的应用程序（服务）、运行事件触发或定时任务（任务），或处理始终在线的基于拉取的背景处理（工作者池）时使用。

1.5万Star
1201Fork
更新于 2026/7/29
获取 Skill源代码

相关 Skills

nuxt5367sherpa-onnx-tts38万homelab-pihole-dns24万
SKILL.md
readonly只读
name
cloud-run-basics
description

管理 Cloud Run 服务、任务和工作者池。当您需要部署响应 HTTP 请求的应用程序（服务）、运行事件触发或定时任务（任务），或处理始终在线的基于拉取的背景处理（工作者池）时使用。

Cloud Run 基础

Cloud Run 是一个全托管的应用程序平台，用于在 Google 高度可扩展的基础设施上运行您的代码、函数或容器。它抽象了基础设施管理，提供三种主要资源类型：

  1. 服务： 响应发送到唯一且稳定端点的 HTTP 请求，使用无状态实例，根据多种关键指标自动扩缩，同时也能响应事件和函数。
  2. 任务： 执行可并行化的任务，这些任务可以手动或按计划执行，并运行至完成。
  3. 工作者池： 处理始终在线的后台工作负载，例如基于拉取的工作负载，如 Kafka 消费者、Pub/Sub 拉取队列或 RabbitMQ 消费者。

前提条件

  1. 启用 Cloud Run Admin API 和 Cloud Build API：

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

  2. 如果您的项目受到域名限制组织策略 限制 未经验证的调用，您需要按照 测试私有服务 中的说明访问已部署的服务。

所需角色

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

  • Cloud Run 管理员 (roles/run.admin) 在项目上
  • Cloud Run 源代码开发者 (roles/run.sourceDeveloper) 在项目上
  • 服务账号用户 (roles/iam.serviceAccountUser) 在服务身份上
  • 日志查看器 (roles/logging.viewer) 在项目上

除非您覆盖此行为，否则 Cloud Build 会自动使用 Compute Engine 默认服务账号作为默认 Cloud Build 服务账号来构建您的源代码和 Cloud Run 资源。

为了让 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 标志，部署命令将尝试从源代码部署。

从源代码部署

有两种不同的方式从源代码部署服务：

  • 从源代码构建部署（默认）：此选项使用 Google Cloud 的构建包和 Cloud Build 自动从您的源代码构建容器镜像，无需在您的机器上安装 Docker 或设置构建包或 Cloud Build。默认情况下，Cloud Run 使用 Cloud Build 提供的默认机器类型。

    • 要启用自动基础镜像更新从源代码部署，请运行以下命令：

      gcloud run deploy SERVICE_NAME --source . \
--base-image BASE_IMAGE \
--automatic-updates \
--quiet

      Cloud Run 仅支持使用 Google Cloud 构建包基础镜像 的自动基础镜像。

      • 要使用 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

或者，使用部署命令：

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）中的容器镜像。

您只应考虑使用 Docker Hub 部署流行的容器镜像，例如 Docker 官方镜像 或 Docker 赞助的 OSS 镜像。为了获得更高的可用性，Google 建议使用 Artifact Registry 远程仓库 部署这些 Docker Hub 镜像。

要部署容器镜像，请运行以下命令：

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 标志，部署命令将尝试从源代码部署。

等待部署完成。成功完成后，Cloud Run 会显示一条成功消息以及已部署工作者池的修订版信息。

从源代码部署工作者池

您可以使用单个 gcloud CLI 命令 gcloud run worker-pools deploy 并带上 --source 标志，将新的工作者池或工作者池修订版直接从源代码部署到 Cloud Run。

如果您不提供 --image 或 --source 标志，部署命令默认为源代码部署。

在后台，此命令使用 Google Cloud 的构建包 和 Cloud Build 自动从您的源代码构建容器镜像，无需在您的机器上安装 Docker 或设置构建包或 Cloud Build。默认情况下，Cloud Run 使用 Cloud Build 提供的默认机器类型。

要从源代码部署工作者池，请运行以下命令：

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

将 WORKER_POOL_NAME 替换为您想要的工作者池名称。

部署失败时的处理方法：

  1. IAM/权限错误： 阅读 iam-security.md。
  2. 启动时崩溃/健康检查失败： 立即使用 gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20 获取日志以找到确切的运行时错误。
  3. 原生依赖错误（Node/Python）： 如果使用 --no-build，请切换到 --source .（构建包）以正确为 Linux 编译原生扩展。

参考目录

  • 核心概念：服务 vs. 任务 vs. 工作者池、资源模型以及服务的自动扩缩行为。

  • CLI 用法：用于部署和管理的必要 gcloud run 命令。

  • 客户端库：使用 Google Cloud 客户端库与 Cloud Run 交互。

  • MCP 用法：使用 Cloud Run 远程 MCP 服务器。

  • 基础设施即代码：用于服务、任务、工作者池和 IAM 绑定的 Terraform 示例。

  • IAM 与安全：角色、服务身份以及入站/出站控制。

  • 网络最佳实践与成本优化：成本优化策略、Direct VPC Egress、IP 地址和端口耗尽策略、性能吞吐量调优以及 MTU 设置。

如果您需要这些参考资料中未找到的产品信息，请使用开发者知识 MCP 服务器的 search_documents 工具。