开始前你需要准备
做「claw cloud run 部署」前,先备齐账号、项目、代码和配置,后面报错才好判断是权限、账单还是参数问题。
- 项目和账单:用能登录 GCP 控制台的账号打开项目,没有就新建;确认结算账号有效且已绑定。Cloud Run 有免费额度也要可计费;常见坑是项目能打开但没绑账单。
- 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;每个代码块整段复制,遇到提示就按中文粘贴,只有区域提示可直接回车。
-
登录并确认对象。先列出账号和项目再手动选一次。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 -
开通服务并选近的区域。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" -
查权限并补缺。脚本会检查部署、以服务账号发布、写镜像、读日志四类角色,缺哪项就补哪项。公司账号可能从群组继承权限,脚本看不到不代表一定没有;如果补权限报 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?我们提供云平台代维护、上云迁移与账单代付服务,一对一技术支持。
