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

claw cloud run 部署小白教程

TL;DR:本文用最少命令讲清 claw cloud run 部署流程:准备权限、构建镜像、发布服务、验证访问,并列出新手常见报错。

开始前你需要准备

做「claw cloud run 部署」前,先备齐账号、项目、代码和配置,后面报错才好判断是权限、账单还是参数问题。

  1. 项目和账单:用能登录 GCP 控制台的账号打开项目,没有就新建;确认结算账号有效且已绑定。Cloud Run 有免费额度也要可计费;常见坑是项目能打开但没绑账单。
  2. gcloud 和三项信息:Windows 或不想装 gcloud,就用自带 gcloud 的 Cloud Shell;macOS/Linux 可按官网装。抄下项目编号或 ID、服务名、区域;编号不是项目名,服务名用小写和连字符,区域选定后少改。

在 Cloud Shell 或 macOS/Linux 终端整块复制执行,按提示输入:会登录、输入三项、查账单,并给当前账号补 Cloud Run、镜像仓库、日志查看和启用服务权限。缺了会 permission denied 或日志空白;输出里要有 billingEnabled: true。

gcloud version
gcloud auth login
printf "项目编号或 ID: "; read PROJECT_ID
printf "服务名(回车 claw): "; read SERVICE_NAME
SERVICE_NAME=${SERVICE_NAME:-claw}
printf "区域(回车 asia-east1): "; read REGION
REGION=${REGION:-asia-east1}
gcloud config set project "$PROJECT_ID"
gcloud config set run/platform managed
gcloud config set run/region "$REGION"
gcloud projects describe "$PROJECT_ID"
gcloud beta billing projects describe "$PROJECT_ID"
ACCOUNT=$(gcloud config get-value account)
MEMBER="user:$ACCOUNT"
case "$ACCOUNT" in *gserviceaccount.com) MEMBER="serviceAccount:$ACCOUNT";; esac
for ROLE in roles/run.admin roles/artifactregistry.admin roles/logging.viewer roles/serviceusage.serviceUsageAdmin; do gcloud projects add-iam-policy-binding "$PROJECT_ID" --member="$MEMBER" --role="$ROLE"; done
gcloud services enable run.googleapis.com artifactregistry.googleapis.com logging.googleapis.com
echo "PROJECT_ID=$PROJECT_ID SERVICE_NAME=$SERVICE_NAME REGION=$REGION"
  • claw 材料:准备源码目录或可用镜像,以及数据库地址、APP_SECRET、第三方 Key。部署时作为环境变量传入,别写进源码、Dockerfile 或 Git。
  • 易踩坑:数据库地址要带端口和库名并允许云端访问;账单或权限报错就找项目 Owner,别反复重试。

整体思路

claw cloud run 部署 就是:把 claw 目录打成平台能跑的镜像,交给 Cloud Run 托管;平台只认镜像,所以无需购买 VM、配置 SSH,也别登录机器改文件,重启会丢。全程以控制台和 gcloud 为准。

在 claw 目录执行,按提示选项目:

gcloud init
gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com
gcloud run deploy claw --source . --region asia-east1 --port 8080 --set-env-vars CLAW_ENV=prod --allow-unauthenticated

首次创建服务并接流量;部署只盯四个开关:

  • 区域:选离用户近的,换区常要重建资源。
  • 端口:要和程序监听一致;只听 127.0.0.1 会打不开。
  • 环境变量:键名照 claw 文档写,密钥别明文塞。
  • 访问权限:公网服务才开放,内部系统用 IAM。

每次修改生成新版本。为防坏版本影响用户,先发带 try 标签、不接正式流量的版本:

gcloud run deploy claw --source . --region asia-east1 --port 8080 --set-env-vars CLAW_ENV=prod --allow-unauthenticated --tag try --no-traffic

控制台点 try 测试地址,页面、接口、日志正常,确认无误后,再复制下面命令,把访问流量切到新版本:

gcloud run services update-traffic claw --region asia-east1 --to-latest

小白常见坑:目录错、项目错、变量或端口写错,常是“部署成功但打不开”。先看控制台日志和 gcloud 报错,比猜服务器快。

详细步骤一:准备项目与权限

开始 claw cloud run 部署前,先把“谁在操作、操作哪个项目、资源放哪里”定死。后面命令都会读这份默认配置,能避免把镜像推到旧账号、把服务发到测试项目。建议用 Cloud Shell;每个代码块整段复制,遇到提示就按中文粘贴,只有区域提示可直接回车。

  1. 登录并确认对象。先列出账号和项目再手动选一次。Project ID 通常是小写英文加数字,不是页面上的中文项目名;输出里的 account、project、name 都要核对,看到 ACTIVE 才算当前账号,多人共用电脑时别看到 * 就以为是自己。

    gcloud auth login
    gcloud auth list
    read -p "粘贴上面要用的账号: " ACCOUNT
    gcloud config set account "$ACCOUNT"
    gcloud projects list
    read -p "粘贴上面要用的 Project ID: " PROJECT_ID
    gcloud config set project "$PROJECT_ID"
    gcloud config get-value account
    gcloud config get-value project
    gcloud projects describe "$PROJECT_ID" --format="table(name,projectId,lifecycleState)"
    gcloud config list
  2. 开通服务并选近的区域。Cloud Run 负责跑服务,Artifact Registry 负责存镜像。区域不是新建出来的,只能选 GCP 已有位置;大陆用户可先试 asia-east1,慢再换 asia-northeast1。两者放同区域,部署更快,也少踩跨区传输和费用坑。仓库名 claw-run 后面推送镜像还会用到。若提示未绑定结算,先找管理员。

    PROJECT_ID=$(gcloud config get-value project)
    gcloud services enable run.googleapis.com artifactregistry.googleapis.com --project="$PROJECT_ID"
    read -p "输入离你近的区域,回车默认 asia-east1: " REGION
    REGION=${REGION:-asia-east1}
    gcloud config set run/region "$REGION"
    gcloud config set artifacts/location "$REGION"
    gcloud artifacts repositories describe claw-run --location="$REGION" --project="$PROJECT_ID" >/dev/null 2>/dev/null || gcloud artifacts repositories create claw-run --repository-format=docker --location="$REGION" --description="claw cloud run 部署镜像仓库" --project="$PROJECT_ID"
  3. 查权限并补缺。脚本会检查部署、以服务账号发布、写镜像、读日志四类角色,缺哪项就补哪项。公司账号可能从群组继承权限,脚本看不到不代表一定没有;如果补权限报 forbidden,把账号和报错给项目管理员,别反复重试。

    PROJECT_ID=$(gcloud config get-value project)
    ACCOUNT=$(gcloud config get-value account)
    if [[ "$ACCOUNT" == *gserviceaccount.com ]]; then MEMBER="serviceAccount:$ACCOUNT"; else MEMBER="user:$ACCOUNT"; fi
    CURRENT=$(gcloud projects get-iam-policy "$PROJECT_ID" --flatten="bindings[].members" --format="csv[no-heading](bindings.members,bindings.role)" | grep -F "$MEMBER," | cut -d, -f2 || true)
    for ROLE in roles/run.admin roles/iam.serviceAccountUser roles/artifactregistry.writer roles/logging.viewer; do
      if echo "$CURRENT" | grep -qx "$ROLE"; then echo "已有 $ROLE"; else if gcloud projects add-iam-policy-binding "$PROJECT_ID" --member="$MEMBER" --role="$ROLE" >/dev/null; then echo "已补 $ROLE"; fi; fi
    done

详细步骤二:构建并推送镜像

先进入 claw 项目根目录,复制整块执行。它会补上 Gunicorn 依赖,生成启动脚本、忽略规则和 Dockerfile;原有 requirements.txt 只追加不覆盖,别手动清空。脚本用 PORT 决定监听地址;ENV PORT=8080 只是本地默认,Cloud Run 注入的 PORT 会覆盖它,所以别再写死 5000、8080。

# 在 claw 项目根目录执行;原有 requirements.txt 不会被覆盖
grep -q '^gunicorn' requirements.txt 2>/dev/null || echo 'gunicorn==22.0.0' >> requirements.txt

cat > start.sh <<'EOF'
#!/bin/sh
: "${PORT:=8080}"
exec gunicorn --bind "0.0.0.0:$PORT" claw:app
EOF
chmod +x start.sh

cat > .dockerignore <<'EOF'
.env
*.key
.git
__pycache__/
EOF

cat > Dockerfile <<'EOF'
FROM python:3.12-slim
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PORT=8080
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["./start.sh"]
EOF

为什么这样写?RUN pip install 负责依赖,CMD 负责启动命令,--bind "0.0.0.0:$PORT" 负责监听端口;必须监听 0.0.0.0,只听 127.0.0.1 外部请求进不来。小白常见坑是把 ${PORT} 放进数组式 CMD,那样不会被 shell 展开,所以这里放到 start.sh 读取。

接着构建并推送到 Artifact Registry。若第一次用,命令会自动拉起初始化向导,按提示登录并选项目即可;仓库已存在也不会中断。Cloud Build 会读当前目录的 Dockerfile,构建后推到 IMAGE 地址。版本号同时放进镜像名路径和标签,下次改成 v1.0.1 即可;别总用 latest,出问题时才知道该回滚到哪一版。

export PROJECT_ID="$(gcloud config get-value project 2>/dev/null)"
if [ -z "$PROJECT_ID" ] || [ "$PROJECT_ID" = "(unset)" ]; then gcloud init; export PROJECT_ID="$(gcloud config get-value project 2>/dev/null)"; fi
export REGION="asia-east1"
export REPO="claw-repo"
export SERVICE="claw"
export VERSION="v1.0.0"
export IMAGE="$REGION-docker.pkg.dev/$PROJECT_ID/$REPO/$SERVICE-$VERSION:$VERSION"

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com
gcloud artifacts repositories create "$REPO" 
  --repository-format=docker --location="$REGION" 
  --description="claw images" 2>/dev/null || true
gcloud auth configure-docker "$REGION-docker.pkg.dev" --quiet
gcloud builds submit --tag "$IMAGE"

最后提醒:API Key、数据库密码、Token 都不要写进 Dockerfile、requirements.txt、代码或 .env 后一起打包;.dockerignore 只是防止误复制,换成别的密钥文件名也要加进去。镜像层可以被拉取者查看,删文件也抹不掉历史。敏感值留到部署阶段,用 Cloud Run 环境变量或 Secret Manager 设置。

详细步骤三:发布服务与配置访问

在 Cloud Shell 整段复制执行:它已登录 gcloud,少一步授权坑;命令自动取当前项目,用刚推送的 claw/claw:latest 在 asia-east1 建服务 claw。区域要和镜像仓库一致,不然最容易拉不到镜像;上一节路径不同只改 IMAGE,区域不同再改 REGION。

PROJECT_ID="$(gcloud config get-value project)"
REGION="asia-east1"
SERVICE="claw"
IMAGE="${REGION}-docker.pkg.dev/${PROJECT_ID}/claw/claw:latest"
APP_KEY="$(openssl rand -hex 32)"
DATABASE_URL="sqlite:////tmp/claw.db"
CALLBACK_URL="https://example.invalid/callback"

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

gcloud run deploy "${SERVICE}" 
  --image "${IMAGE}" 
  --region "${REGION}" 
  --platform managed 
  --memory 512Mi 
  --timeout 60s 
  --max-instances 3 
  --concurrency 20 
  --set-env-vars "APP_KEY=${APP_KEY},DATABASE_URL=${DATABASE_URL},CALLBACK_URL=${CALLBACK_URL}" 
  --no-allow-unauthenticated 
  --quiet

SERVICE_URL="$(gcloud run services describe "${SERVICE}" --region "${REGION}" --format='value(status.url)')"
CALLBACK_URL="${SERVICE_URL}/callback"

gcloud run services update "${SERVICE}" 
  --region "${REGION}" 
  --update-env-vars "CALLBACK_URL=${CALLBACK_URL},APP_KEY=${APP_KEY},DATABASE_URL=${DATABASE_URL}" 
  --quiet

gcloud run services add-iam-policy-binding "${SERVICE}" 
  --region "${REGION}" 
  --member="allUsers" 
  --role="roles/run.invoker" 
  --quiet

echo "访问地址:${SERVICE_URL}"

512Mi、60 秒、3 实例、并发 20 是故意从小规格起步:并发太高易撑爆内存,不限实例数账单也难控,验证过再调大;超时也别设太久,卡住会占着实例。--no-allow-unauthenticated 让部署阶段先不公网可访问,也避免卡在 y/N 提示,后面再按需要放行。

变量要存进服务,留在终端不算。脚本先放临时回调,拿到地址后用 update 回填 CALLBACK_URL,连 APP_KEY、DATABASE_URL 一起重新部署;回调写旧域名常让登录校验失败。APP_KEY 用随机串,别写 123456,重新部署沿用同一个,否则旧会话会失效。sqlite:////tmp/claw.db 只够试跑,/tmp 重启即清空,正式换 Cloud SQL 地址再 update。

  • 若是后台接口,删掉 add-iam-policy-binding 几行,别开放未登录,先用管理员身份验;遇组织政策禁止 allUsers 也先保持关闭。
  • 复制最后输出的「访问地址」,下一步用它打开页面验证。

验证结果

先复制 Cloud Run 详情里的“网址”,新标签打开。首页或健康检查返回 200、ok、healthy 才算正常;因为端口、启动命令或检查路径写错,服务也可能建出来。空白页、403、404、转圈不算过。

再看控制台:状态就绪、日志无连续启动后退出、超时、权限或数据库报错,最新修订流量为 100%。确认无反复重启,也防测到旧版;别把冷启动慢当崩溃。

接着用 gcloud 查列表,默认表格有服务名、区域、网址和最近部署时间,逐项对上;时间没变,多半部署错项目、区域或服务。

gcloud run services list

最后手机关 Wi-Fi 访问一次,或让同事换网络打开同一 https 地址,排除本机缓存、代理、hosts、SSH 通道影响。别发 localhost;手机 403 多是未开放未认证访问或入口限制。

常见坑与解决办法

常见问题(FAQ)

没有自己的域名可以完成 claw cloud run 部署吗?

可以,Cloud Run 会提供默认访问地址,先测试成功再绑定域名。

一定要会写容器配置吗?

不一定,可用现成模板,但至少要确认启动命令和监听端口正确。

部署后页面打不开先查什么?

先查服务日志、端口、环境变量和访问权限,通常能定位八成问题。

新手怎样避免产生意外费用?

默认按请求计费,先设预算提醒并限制实例数,适合低成本试用。

可以直接用 VM 代替 Cloud Run 吗?

可以,但 Cloud Run 更省心,不必长期维护服务器和补丁。

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

查看代维服务 →

发表评论