cloud-run-basics

Cloud Run 基础知识

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

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

归属信息

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属信息。对于直接在终端中执行的命令（绝不在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-run-basics)" ，并在 User-Agent 标头中附加 agent-skills/1.0 (skill:cloud-run-basics)。

前提条件

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

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

2. 如果你的项目受域名限制组织政策约束，且该政策禁止未通过身份验证的调用，则需要按照测试私有服务中的说明访问已部署的服务。

所需角色

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

• 项目中的 Cloud Run Admin (roles/run.admin)
• 项目中的 Cloud Run Source Developer (roles/run.sourceDeveloper)
• 服务身份上的 Service Account User (roles/iam.serviceAccountUser)
• 项目中的 Logs Viewer (roles/logging.viewer)

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

要让 Cloud Build 构建源代码，请向 Cloud Build 服务账号授予项目中的 Cloud Run Builder (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 服务

你可以使用容器映像将服务部署到 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 映像会被 缓存，最长可达 1 小时。

你可以通过设置 Artifact Registry 远程 仓库，使用其他公共或私有注册表（例如 JFrog Artifactory、Nexus 或 GitHub Container Registry）中的容器映像。

对于部署热门容器映像（例如 Docker 官方 映像或 Docker 赞助的 OSS 映像），才应考虑使用 Docker Hub。为提高可用性，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

也可以使用部署命令：

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 属性。

部署 worker pool

你可以使用容器映像部署 Cloud Run worker pool，也可以直接从源代码部署。

部署容器映像

你可以指定带标签的容器映像（例如， 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 映像会被缓存，最长可达 1 小时。

你可以通过设置 Artifact Registry 远程 存储库，使用其他公共或私有注册表（例如 JFrog Artifactory、Nexus 或 GitHub Container Registry）中的容器映像。

仅在部署热门容器映像（例如 Docker 官方 映像或 Docker 赞助的 OSS 映像）时，才应考虑使用 Docker Hub。为提高可用性，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 标志，deploy 命令会尝试从源代码部署。

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

从源代码部署工作池

你可以使用一条 gcloud CLI 命令直接从源代码向 Cloud Run 部署新的工作池或工作池修订版本：gcloud run worker-pools deploy，并使用 --source 标志。

如果未提供 --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 替换为你希望使用的工作池名称。

部署失败时的处理方法：

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

参考目录

• 核心概念：服务、作业与工作池的区别、资源模型，以及服务的自动扩缩行为。

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

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

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

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

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

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

如果这些参考资料中没有你需要的产品信息，请使用 Developer Knowledge MCP 服务的 search_documents 工具。