+86 189 8218 1436 周一至五 10:00-22:00

小白教程:部署到cloud run

TL;DR:用示例容器讲清部署到cloud run 的全流程:准备、构建、发布、验证和排错,零基础也能照做。

开始前你需要准备

部署到cloud run 前,准备一个可结算(已绑定结算账号)的 GCP 项目,在 IAM 里确认自己有项目所有者或编辑者权限。记下项目 ID 与打算使用的区域,如 asia-east1;项目 ID 是小写字符串,不是项目名称。没结算或权限不够,开 API、部署常报 403 或账单错误;区域忘了,服务容易建到别处。

最省心用 Cloud Shell,已预装并初始化 gcloud,可跳过安装块;Linux 电脑或 VM 终端若提示找不到命令,再安装并初始化,脚本一路回车:

curl https://sdk.cloud.google.com | bash
export PATH="$HOME/google-cloud-sdk/bin:$PATH"
gcloud init

下面登录账号、固定项目和区域,避免选错;同时开通 Cloud Run Admin API、Cloud Build API、Artifact Registry API,并准备一个简单 HTTP 应用目录。三者分别负责运行、打包、存镜像,缺一个都会卡住:

gcloud auth login
read -p "请输入项目 ID(不是项目名称):" PROJECT_ID
read -p "请输入区域,例如 asia-east1:" REGION
gcloud config set project "$PROJECT_ID"
gcloud config set run/region "$REGION"
gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com
mkdir -p hello-cloud-run && cd hello-cloud-run
  • 目录里后面放能返回 HTTP 响应的简单代码即可;别把文件散在桌面,也别写死端口,Cloud Run 会用 PORT 环境变量告诉程序监听哪里。
  • 给小白的定心丸:不必自己买服务器,也不要先纠结域名、负载均衡和 SSH。先用 Cloud Run 给的默认 HTTPS 地址跑通,再考虑绑定域名和更漂亮的架构。

整体思路

先记住一句话:Cloud Run 是托管容器服务。你给平台能响应 HTTP 请求的代码和 Dockerfile,它负责启动、按流量伸缩和打补丁;不用自己买服务器、装环境。部署到cloud run,就是把容器交给 Google 跑,并拿到网址。

主流程只有五步:

  1. 写应用。
  2. 构建镜像。
  3. 上传镜像到仓库。
  4. 部署到cloud run。
  5. 拿到网址并验证。

本文使用 Cloud Build 在云端构建、上传镜像,因为构建发生在云端,能减少本地 Docker 和 Linux 环境差异,少踩“我这边能跑”的坑。把每次发布都理解为一个新修订:出错时先看日志,再回滚或重新部署;避免直接改线上服务器,否则改动会被覆盖,也难追踪。小白还要注意:应用必须监听 $PORT 并绑定 0.0.0.0,别写死 8080;项目、区域或权限没配好,网址可能 403。

在 Cloud Shell 进入含代码和 Dockerfile 的目录后,复制执行:

gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com --quiet
gcloud run deploy hello-run --source . --region asia-east1 --platform managed --allow-unauthenticated --quiet
gcloud run services logs read hello-run --region asia-east1 --limit 20 --quiet

--source . 会让 Cloud Build 构建、上传镜像再部署;终端显示的 Service URL 就是网址,复制到浏览器能打开即验证成功。失败时先跑最后一条看日志,再回滚或修好重新部署。

详细步骤一:准备示例应用

先在本机建一个干净目录,后面打包镜像、部署到cloud run都在这个目录里操作。下面命令会一次创建最简单的 Web 服务 server.js、package.json 和根目录的 Dockerfile,直接整段复制即可。

mkdir cloud-run-demo && cd cloud-run-demo
cat > server.js <<'EOF'
const http=require('http');
const port=Number(process.env.PORT);
if(!port) throw new Error('PORT 未设置');
http.createServer(function(req,res){res.end('部署到 Cloud Run 成功!');}).listen(port,'0.0.0.0');
EOF
cat > package.json <<'EOF'
{"name":"cloud-run-demo","private":true,"scripts":{"start":"node server.js"}}
EOF
cat > Dockerfile <<'EOF'
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
COPY server.js ./
CMD ["npm","start"]
EOF

为什么这样写:server.js 访问时只返回“部署到 Cloud Run 成功!”,部署后浏览器看到这行字,就说明访问结果正常。代码用 process.env.PORT 读取端口,并监听 0.0.0.0;Cloud Run 会临时注入 PORT,容器必须监听所有网卡,平台才能把请求转进来。

  • 常见坑:不要绑定 127.0.0.1,也不要写死 8080;否则本地看似能跑,线上容易超时或访问被拒。
  • Dockerfile:选轻量基础镜像 node:20-alpine,复制清单后 npm install 安装依赖,再复制代码,最后用 CMD 启动服务;文件必须放在目录根部。
  • 不会写代码:优先照抄上面固定模板;也可参考 Cloud Run 官方示例,只改返回文字和 package.json 的 name 服务名,端口逻辑按本模板保留,别把 Dockerfile 放进子目录。

详细步骤二:构建镜像并上传

先给镜像找个「仓库」存起来。我们用 Artifact Registry 建一个 Docker 仓库,区域务必和后面 Cloud Run 选一致(比如都用 asia-east1),跨区拉取会变慢,还容易多产生一笔跨区流量费。下面整段直接复制执行即可,项目 ID 会自动获取,不用你手填:

export REGION="asia-east1"
export PROJECT_ID=$(gcloud config get-value project)
export REPO="cloudrun-repo"
export IMAGE="my-app"

gcloud artifacts repositories create $REPO --repository-format=docker --location=$REGION

gcloud builds submit --tag $REGION-docker.pkg.dev/$PROJECT_ID/$REPO/$IMAGE

gcloud builds submit --tag 会把当前目录的 Dockerfile 交给 Cloud Build 打包并自动上传,本地连 Docker 都不用装。留意 --tag 后面这串地址:固定由区域、项目、仓库、镜像名四段拼成,也就是 区域-docker.pkg.dev/项目/仓库/镜像名。新手最常在这儿漏掉 -docker.pkg.dev 或打错项目名,等下一步部署到cloud run才报「找不到镜像」。现在就把它完整存进记事本,部署时原样引用,千万别重敲。

万一终端飘红别慌,先点开提示里的 Cloud Build 日志,从下往上翻,重点查三处:

  1. Dockerfile 不在当前目录(命令得在它所在文件夹跑);
  2. 依赖安装失败(漏了锁文件或网络超时);
  3. 启动命令没监听 PORT 环境变量就退出了。

改完重跑上面那条 builds submit 就会覆盖旧镜像,不用先删旧版,很安全。

详细步骤三:部署到cloud run

镜像准备好后执行下面命令:它把镜像交给 Cloud Run 建服务并分配 HTTPS 网址;服务名、区域可先用,镜像地址不同只改 --image 后那串,别漏参数,照抄执行即可。

gcloud run deploy web --image gcr.io/$(gcloud config get-value project)/web:latest --region asia-east1 --allow-unauthenticated

首次看到启用 API、允许公开调用等提示,输入 y 回车即可。–allow-unauthenticated 表示允许公开访问;内部系统可先不加,再用 IAM 授权指定账号,免得后台被全网看到。

小白先让内存、并发、最大实例、环境变量都默认,够用且少踩坑;只确认容器端口由平台通过 PORT 注入,程序监听 PORT,别写死 8080 或只听 127.0.0.1,否则常见 502、启动超时。

完成后复制输出的 HTTPS 网址,如 https://xxx.run.app;这就是本次部署到cloud run 的访问入口,别把镜像地址当网址。

验证结果

先别急着改代码,按下面顺序验一遍:先看外部能不能访问,再看平台状态,最后用命令和日志对账,能少走很多弯路。

  1. 打开网址:在 Cloud Run 服务页顶部复制 https://... 到浏览器。能看到「部署成功」或你的首页,就说明容器已经启动,并且能从公网响应请求。别用 localhost;若显示 403,多半是没允许未登录访问。
  2. 看控制台:进入 GCP 控制台的「Cloud Run → 服务」,点开该服务,确认状态是「就绪」。再核对最新修订、区域,并切到「日志/请求日志」,这里能看出刚才那次访问有没有进来。别只看绿色勾,区域对不上会找错地方。
  3. 用命令核对:把下面前两行换成自己的服务名和区域,整段复制执行。输出里重点找 URL、Image、Last updated on,分别对应网址、镜像和发布时间,和控制台看到的应一致。
SERVICE_NAME="my-service"
REGION="asia-east1"
gcloud run services describe "$SERVICE_NAME" --region "$REGION"

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name="$SERVICE_NAME"" --limit 20

最后一条是在读访问记录;也可以在控制台日志页看。重点确认没有 403、Permission denied,也没有 Container failed to start、崩溃重启;看到 200/304 基本就稳了。坑:区域要写部署时的区域,如 asia-east1,不是可用区;服务名也不是项目 ID。命令报错先检查这两项和当前项目。

常见坑与解决办法

  1. 报错提示 API 未启用或权限不足时:部署到 Cloud Run 要按报错回到控制台“API 和服务”开通对应 API,并让管理员在 IAM 补齐 Cloud Run Admin、Cloud Build 和 Artifact Registry 相关角色。因为发布、构建、存镜像分开管,少开一个就卡;能看项目不等于能部署,只加一个角色也常不够。命令行可一次开通:
    gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com
  2. 访问返回 403 时:检查部署是否加了 --allow-unauthenticated,或给调用者授予 Cloud Run Invoker 角色。Cloud Run 默认不公开,浏览器打开也算未登录;部署成功却打不开,多半是这个。练习服务可公开授权:
    gcloud run services add-iam-policy-binding hello-service --region asia-east1 --member allUsers --role roles/run.invoker
  3. 服务反复重启或网关超时时:多半是代码没监听 0.0.0.0 和 PORT。Cloud Run 按 PORT 转发,监听 127.0.0.1 或写死 8080 会超时;看日志后按日志修正监听地址与启动命令。本地能跑不代表云端能跑:
    gcloud run services logs read hello-service --region asia-east1 --limit 50
  4. 镜像拉取失败时:核对镜像地址、区域和仓库权限,不要把测试镜像名误写成旧版本。完整路径里项目、仓库、标签差一点就拉错;私有仓库没授权也拉不动。小白常复制旧教程命令,代码更新了,云端还在找旧镜像。
  5. 练习结束后:删除 Cloud Run 服务或在控制台关闭结算,避免忘记清理产生持续费用。空闲时请求费可能很低,但镜像仓库、构建记录、日志还会留着;别关掉网页就以为资源停了。按示例服务名可删:
    gcloud run services delete hello-service --region asia-east1 --quiet

常见问题(FAQ)

不会 Linux 命令,也能部署到cloud run 吗?

可以,先用 Cloud Shell 和控制台,按教程复制命令,不必登录 VM。

一定要在本地安装 Docker 吗?

不必,Cloud Build 能按 Dockerfile 构建镜像,先理解镜像是运行包即可。

部署后打开网址显示 403 怎么办?

检查是否允许未认证访问,或给账号授予 Cloud Run Invoker 角色。

为什么本地能跑,线上却启动失败?

常见原因是没监听 0.0.0.0 和 PORT,按日志修正启动参数。

部署到cloud run 会不会很贵?

按请求和资源计费,练习后删除服务或关闭项目结算更稳妥。

不想自己折腾 GCP?我们提供云平台代维护、上云迁移与账单代付服务,一对一技术支持。

查看代维服务 →

发表评论