---

name: cloudrun-development description: CloudBase Run backend development rules (Function mode/Container mode). Use this skill when deploying backend services that require long connections, multi-language support, custom environments, AI agent development, or migrating existing/GitHub apps that need VPC access to MySQL/PostgreSQL/Redis. Also use when diagnosing CloudRun container deploy failures (deploy_failed, readiness/probe failed, image won't start, docker.io pull loops) or a deploy stuck behind a running deploy task. For stateless HTTP services, prefer HTTP cloud functions. version: 2.34.8 alwaysApply: false

Sibling skills (local only)

Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.

If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.

Cross-cutting protocols (required before writing HTTP handlers or deploying images):

• Sensitive Runtime Data Protection: ../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md
• Deployment Gate: ../cloudbase-platform/references/protocols/deployment-gate.md

CloudBase Run Development

Activation Contract

Use this first when

• The task is to initialize, run, deploy, inspect, or debug a CloudBase Run service.
• The request needs a long-lived HTTP service, SSE, WebSocket, custom system dependencies, or container-style deployment.
• The task is to create or run an Agent service on CloudBase Run.
• The task migrates an existing / GitHub / third-party backend that uses classic DATABASE_URL / TCP database clients.
• The service requires a stable independent process (long connections, custom runtime, VPC database access) — see the 「云托管 vs HTTP 云函数」 decision section below. A Dockerfile alone is not a strong trigger.

Read before writing code if

• You still need to choose between Function mode and Container mode.
• The prompt mentions queryCloudRun, manageCloudRun, Dockerfile, service domains, or public/private access.
• The app depends on MySQL, PostgreSQL, Redis, or other VPC-private resources over TCP → 先做数据库访问方式决策（SDK/网关优先，见下方「数据库访问方式决策门」）；确认必须 TCP 直连后 → also read references/vpc-and-database.md.
• You are choosing between CloudRun and HTTP cloud functions for a stateless HTTP service.
• The service calls CloudBase resources (PG app.rdb(), NoSQL, storage, functions) through an SDK → 先过「计算资源访问 CloudBase 的凭证决策门」：凭证谁签发、怎么注入、怎么吊销，都必须在写代码之前定下来。
• Container deploy fails (deploy_failed, Pod not ready, readiness/probe failed, third-party imageUrl won't stay up) → also read references/image-deploy-troubleshooting.md and follow the Container deploy failure SOP below. Do not start by raising InitialDelaySeconds.

Then also read

• Cloud functions instead of CloudRun -> ../cloud-functions/SKILL.md
• Agent SDK and AG-UI specifics -> ../cloudbase-agent/SKILL.md
• Web authentication for browser callers -> ../auth-web-cloudbase/SKILL.md
• Existing app + TCP database networking -> references/vpc-and-database.md
• Container image deploy failure / probe / deploy_failed -> references/image-deploy-troubleshooting.md
• Service calls CloudBase resources through an SDK (credential source / injection / revocation) -> ../cloud-functions/references/http-function-credentials.md

Do NOT use for

• Simple Event Function or HTTP Function workflows that fit the function model better.
• Frontend-only projects with no backend service.
• Database-schema design tasks.

Common mistakes / gotchas

• Choosing CloudRun when the request only needs a normal cloud function.
• Forgetting to listen on the platform-provided PORT in Container mode — and its mirror image in Function mode: calling app.listen() there, where the framework already owns the port and the second bind dies with EADDRINUSE.
• Guessing the credential environment variable name. @cloudbase/node-sdk reads CLOUDBASE_APIKEY; an invented name (for example TCB_API_KEY) is silently ignored and only shows up later as "no credentials at runtime".
• Copying a server credential out of the local client login state (auth.json, .cloudbase/) and injecting it into a deployed service. Issue the key with manageAppAuth(action="createApiKey", keyType="api_key") instead, so it has an owner, a rotation path, and a keyId you can revoke. See ../cloud-functions/references/http-function-credentials.md.
• Treating CloudRun as stateful app hosting and storing important state on local disk.
• Assuming local run is available for Container mode.
• Opening public access by default when the scenario only needs private or mini-program internal access.
• Deploying an existing app with DATABASE_URL / MySQL / PostgreSQL / Redis but omitting serverConfig.VpcConf — deploy appears to succeed, then runtime DB connections fail.
• 新应用部署默认选 TCP 直连数据库 — 能用 SDK/网关访问的数据（PG app.rdb()、NoSQL、storage）不需要 VpcConf 也不需要数据库账号密码；仅迁移类应用（经典驱动/ORM 无法替换）才走 TCP 直连 + VpcConf。见「数据库访问方式决策门」。
• Confusing OpenAccessTypes (how users reach the service) with VpcConf (how the service reaches VPC databases).
• Deploying to an environment that has not initialized CloudRun — CreateCloudRunServer on an environment with no 大租户 record silently lands in the legacy 小租户 path, creating wrong small-tenant services/versions. Always ensure the environment is initialized first (manageCloudRun(action="initEnv"), tcbr) before the first deploy. manageCloudRun(action="deploy") now blocks new-service creation on uninitialized environments with guidance.
• Using the legacy tcb CloudRun API (CreateCloudBaseRunResource / DescribeCloudBaseRunResource / DeleteCloudBaseRunResource) — these are deprecated 小租户 open APIs and are blocked in callCloudApi. CloudRun always goes through tcbr (CreateCloudRunEnv / CreateCloudRunServer). Query a single environment's base info / whether CloudRun is enabled with DescribeEnvBaseInfo (EnvId required) — use manageCloudRun(action="initEnv") to open and queryCloudRun(action="envStatus") to poll status; query the environment list / resource info with DescribeCloudRunEnvs (EnvId optional filter).
• Deploying httpbin / request-echo images or returning req.headers / process.env — CloudBase may inject x-cloudbase-context (base64 temporary credentials). Echoing it leaks account cloud access. Follow ../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md.
• Seeing readiness probe failed / deploy_failed and immediately raising InitialDelaySeconds — the probe window is already ~N+150s; crash loops and loopback binds are not slow-start. Follow the Container deploy failure SOP.
• Deploying a third-party image without reading its run docs — missing Cmd, bind-address env, or VolumesConf looks identical to a probe failure.
• Calling getDeployLog for imageUrl deploys — that is CODING build log; use getProcessLog.
• Treating startup banners as proof the service is healthy — pull getProcessLog twice and compare; a repeated boot sequence is a restart loop.

Minimal checklist

• Choose Function mode or Container mode explicitly.
• Confirm the environment has CloudRun initialized before the first deploy — a brand-new environment must call CreateCloudRunEnv (tcbr) first; never CreateCloudRunServer on an uninitialized environment (it falls back to the legacy 小租户 path). manageCloudRun(action="deploy") validates this automatically and blocks new services on uninitialized environments. When blocked, first call manageCloudRun(action="initEnv", envId=...) (异步开通) and poll queryCloudRun(action="envStatus") until Status=normal, or reconsider an HTTP cloud function to bypass CloudRun entirely.
• Confirm whether the service should be public, VPC-only, or mini-program internal (ingress).
• If the app uses TCP databases/caches, resolve and set VpcConf (egress / private network) before deploy — see references/vpc-and-database.md.
• Keep the service stateless and externalize durable data.
• Settle the credential path for every CloudBase SDK call before writing code — a server API Key issued through manageAppAuth(action="createApiKey") and injected via EnvParams, never a key copied out of the local client login state.
• Use absolute paths for every local project path.
• Confirm handlers never echo x-cloudbase-context, full headers, or credential env vars; do not deploy httpbin-style reflectors.
• For third-party images, complete the five-item docs checklist (Cmd / port / bind env / volume / health) before deploy.

Overview

Use CloudBase Run when the task needs a deployed backend service rather than a short-lived serverless function.

云托管 vs HTTP 云函数（按需求选，不按文件选）

核心原则：HTTP 云函数优先。只有需求真正需要云托管时才用云托管；有 Dockerfile 不等于必须上云托管。

HTTP 云函数更合适（优先）：

• 无状态 HTTP 服务，监听 PORT/9000，只做「请求进来 → 处理 → 响应」的响应式逻辑
• 短生命周期请求，无长连接需求（SSE/WebSocket 之外的普通 API、CRUD、转发）
• 不需要自定义系统依赖 / 多语言运行时，标准 runtime 足够
• 部署更快、费用更低（按请求计费，可缩容到 0）、无需初始化云托管环境
• 有 Dockerfile 但服务本质是无状态 HTTP → 优先 HTTP 云函数（HTTP Function / Custom Image HTTP Function），不必上云托管

云托管才需要（只有以下之一才选云托管）：

• 长连接：WebSocket、SSE 长连接、服务端推送
• 自定义系统依赖 / 任意语言运行时 / 需要稳定独立进程
• VPC 内数据库 / Redis 访问（VpcConf 私有网络连通）
• Agent 服务（Function mode CloudRun）
• 迁移已有 / GitHub / 第三方应用，或需要常驻进程

决策示例： 一个带 Dockerfile 的 Go/Python HTTP API，无长连接、无自定义运行时、不碰 VPC 数据库 → 选 HTTP 云函数而不是云托管；同一份代码若有 WebSocket 长连接 → 才选云托管。

数据库访问方式决策门（部署前必答：SDK 优先，TCP 直连兜底）

核心原则：能用 CloudBase SDK/网关访问的数据，一律优先 SDK 路径。 TCP 直连会引入 VPC、安全组、数据库账号密码三件套，全是部署后才暴露的问题（ETIMEDOUT、安全组拦截、密码注入），能不碰就不碰。

优先：SDK / 网关路径（无需 VpcConf、无需数据库账号密码）

• CloudBase PG → app.rdb()（js-sdk v3 / node-sdk，走 PG HTTP 网关；详见 ../postgresql-development-cloudbase/SKILL.md）
• NoSQL → app.database()；对象存储 → app.storage
• 新应用 / CloudBase 原生数据 → 数据层直接按 SDK 路径设计，部署时完全不需要 VPC 配置；若只用到这些数据面，还可结合上一节的「HTTP 云函数优先」进一步免掉云托管

仅当以下情况才走 TCP 直连（须完成 references/vpc-and-database.md 全流程）：

• 迁移已有 / GitHub / 第三方应用，数据层是经典驱动或 ORM（mysql2、pg、Prisma、SQLAlchemy、WordPress / Ghost 等），改造成 SDK 的成本高或用户明确要求保留
• 需要 SDK 不覆盖的能力（特定 SQL 方言、存储过程、Redis 原生协议等）

决策动作： 扫描到 DATABASE_URL / DB 依赖信号时，先停下来回答「这个数据访问能不能换成 SDK/网关」，再决定是否进入 VPC checklist——不要默认按 TCP 直连方案往下走。

计算资源访问 CloudBase 的凭证决策门（部署前必答）

核心原则：SDK 路径免掉的是数据库账号密码，不是 CloudBase 资源访问凭证。 服务代码要调 CloudBase 资源（PG app.rdb() / NoSQL / storage / functions）时，先把凭证来源定下来，再写代码、再部署。

三件事必须先答：

1. 谁签发 — CloudBase 服务端 API Key：manageAppAuth(action="createApiKey", keyType="api_key", keyName="<service>-<env>")，或 CLI tcb env apikey create my-key -e env-xxx。不要从本地客户端登录态（auth.json / .cloudbase/）里取一把来用。
2. 怎么注入 — 经 serverConfig.EnvParams 注入 CLOUDBASE_APIKEY（@cloudbase/node-sdk 自动读取该变量；显式字段是 accessKey）。变量名以官方为准，不要自造。改环境变量时保留已有键值，不要整份覆盖。
3. 怎么吊销 — 每个服务一把专用 key，记录 keyName 与轮换负责人；下线或轮换时 manageAppAuth(action="deleteApiKey", keyId=...) 并重新部署。轮换后旧实例里残留的副本不会报错，只会静默失效。

不要假设云托管容器已自动带上可用的 CloudBase 凭证 —— 部署后用一次真实的 SDK 读取验证（验证两次以上，不要只看进程起没起来）。完整步骤、Manager SDK 的腾讯云密钥对路径、环境变量合并的安全写法见 ../cloud-functions/references/http-function-credentials.md。

api_key 是环境级凭证：可绕过 RLS，单环境签发数量有限。不要给每个服务灌同一把 —— 任一实例失陷即整环境失陷。

When CloudRun is a better fit

• Long connections: WebSocket, SSE, server push
• Long-running request handling or persistent service processes
• Custom runtime environments or system libraries
• Arbitrary languages or frameworks
• Stable external service endpoints with elastic scaling
• AI Agent deployment on Function mode CloudRun
• Migrating existing containerized or multi-language apps that need VPC access to databases

Mode selection

| Dimension | Function mode | Container mode | | --- | --- | --- | | Best for | Fast start, Node.js service patterns, built-in framework, Agent flows | Existing contai