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). For stateless HTTP services, prefer HTTP cloud functions.
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). For stateless HTTP services, prefer HTTP cloud functions.
version
2.33.0
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
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 → also read references/vpc-and-database.md.
You are choosing between CloudRun and HTTP cloud functions for a stateless HTTP service.
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
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.
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.
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.
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.
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 containers, arbitrary runtimes, custom system dependencies
Port model
Framework-managed local mode, deployed service still follows platform rules
App must listen on injected PORT
Dockerfile
Not required
Required — but a Dockerfile alone does not mean CloudRun; first check whether the service needs long connections / custom runtime. Stateless HTTP services with a Dockerfile may fit HTTP cloud functions better.
Local run through tools
Supported
Not supported
Typical use
Streaming APIs, low-latency backend, Agent service
Custom language stack, migrated container app
How to use this skill (for a coding agent)
Choose mode first
Function mode -> quickest path for HTTP/SSE/WebSocket or Agent scenarios
Container mode -> use when Docker/custom runtime is a real requirement
Follow mandatory runtime rules
Listen on PORT
Keep the service stateless
Put durable data in DB/storage/cache
Keep dependencies and image size small
Respect resource ratio guidance: Mem = 2 × CPU
Use the correct tools
Read operations -> queryCloudRun
Write operations -> manageCloudRun
Delete requires explicit confirmation and force: true
Always use absolute targetPath
Follow the deployment sequence
Initialize or download code
For a brand-new environment, ensure CloudRun is initialized first — call manageCloudRun(action="initEnv", envId=...) (async, idempotent) before the first deploy; manageCloudRun(action="deploy") blocks new services on uninitialized environments and tells you to call initEnv
For Container mode, verify Dockerfile
Scan for DB/cache dependency signals (DATABASE_URL, docker-compose DB services, ORM configs)
If TCP DB access is required, complete the VPC checklist in references/vpc-and-database.mdbefore deploy
Local run when available
Configure ingress access model and egress VpcConf when needed
For imageUrl / third-party images, complete the five-item docs checklist in the Container deploy failure SOP before deploy
Deploy and verify detail output + DB connectivity
If deploy fails, follow the Container deploy failure SOP (references/image-deploy-troubleshooting.md) — docs → getProcessLog → config; do not start with InitialDelaySeconds
Tool routing
Read operations
queryCloudRun(action="list") -> list services
queryCloudRun(action="detail") -> inspect one service and its latest deploy status when available
queryCloudRun(action="templates") -> see available starters
queryCloudRun(action="getDeployLog") -> 构建日志（CODING / DescribeCloudRunBuildLog）。仅云端源码构建有意义；已有镜像部署（imageUrl）没有构建过程，不要用它诊断镜像部署失败。未登录 CODING 的账号会报错（如 User not created or may not qcloud user）
queryCloudRun(action="getDeployRecords") -> list deploy records (newest first; includes BuildId / RunId / FlowRatio / Status) — use to review release history and rollback context before a traffic operation
queryCloudRun(action="envStatus") -> check whether the environment's CloudRun is opened and its provisioning status (Status=creating opening / normal opened) — use after initEnv to poll progress or before deploy to confirm readiness
manageCloudRun(action="initEnv") -> open (initialize) CloudRun for the environment — async, idempotent (Status=normal → already opened, no re-create). Use on a brand-new environment before the first deploy, or when deploy is blocked with an "尚未初始化云托管" message. Params: envId (defaults to the configured env), packageType (default Trial). Poll queryCloudRun(action="envStatus") until Status=normal.
manageCloudRun(action="init") -> create local project
manageCloudRun(action="run") -> local run for Function mode
manageCloudRun(action="deploy") -> trigger deploy + lightweight wait for registration (does not hang for full build). Returns buildId / runId / taskId + DeployType-aware next_step: source → getDeployLog then getProcessLog; image (imageUrl, BuildId often 0) → skip getDeployLog, use getDeployRecords/detail for RunId then getProcessLog. Follow the returned next_step — do not always poll build logs. Existing services: RMW preserves remote VpcConf / EnvParams keys / OpenAccessTypes; new services automatically validate that the environment's CloudRun is initialized — if not, deploy is blocked with guidance to call initEnv first
manageCloudRun(action="traffic") -> traffic management / canary release (aligns with tcb cloudrun traffic): trafficOp="set" adjusts the stable/canary traffic ratio (stablePercent + canaryPercent must equal 100, e.g. 90/10); trafficOp="promote" promotes the canary version to full release (100%, closes gray release, irreversible); trafficOp="rollback" rolls back to the previous stable version (stops the releasing canary). Check queryCloudRun(action="getDeployRecords") first to understand current versions and traffic
manageCloudRun(action="delete") -> delete service
manageCloudRun(action="createAgent") -> create Agent service
Web/public scenarios -> enable PUBLIC ingress intentionally and pair it with the right auth flow.
Mini Program -> prefer internal direct connection and avoid unnecessary public exposure.
Private ingress scenarios -> keep public access off unless the product requirement clearly needs it.
Database / Redis in a VPC -> this is not solved by OpenAccessTypes. You must set serverConfig.VpcConf and use the database private address. Read references/vpc-and-database.md.
Valid OpenAccessTypes values: OA (办公网访问), PUBLIC (公网访问), MINIAPP (小程序访问), VPC (VPC访问). Use PUBLIC for web applications that need public HTTPS access.
MinNum: 1 is the recommended default when you want to reduce cold-start latency. If the user explicitly prefers lower cost and accepts more cold starts, explain the tradeoff and let them reduce MinNum to 0.
Best practices
Prefer PRIVATE/VPC or mini-program internal ingress when possible.
For TCP database access, always pair private DB URLs with VpcConf in the same VPC/region as the database.
Use environment variables for secrets and per-environment configuration — read them server-side only; never return them in HTTP responses.
Verify configuration before and after deployment with queryCloudRun(action="detail").
Keep startup work small to reduce cold-start impact.
For Agent scenarios, use the Agent SDK skill for protocol and adapter details instead of duplicating them here.
For smoke tests, return a fixed { "ok": true } / health payload — never deploy httpbin or any service that reflects request headers.
Troubleshooting hints
Access failure -> check ingress access type, domain setup, and whether the instance scaled to zero.
Deployment blocked with "尚未初始化云托管 / not initialized" -> the environment needs CloudRun enabled first: call manageCloudRun(action="initEnv", envId=...) (异步开通) and poll queryCloudRun(action="envStatus") until Status=normal; or open the console 环境 → 云托管 → 开通. For stateless HTTP services, consider an HTTP cloud function instead of CloudRun entirely.
Deployment failure -> follow the Container deploy failure SOP above (and references/image-deploy-troubleshooting.md): image deploys skip getDeployLog and use getProcessLog only; classify scheduling vs port vs exit-on-start with two log pulls. Do not raise InitialDelaySeconds until logs prove a single slow init. Also inspect Dockerfile (source) and CPU/memory ratio.
Local run failure -> remember only Function mode is supported by local-run tools.
DB / Redis connection failure after a successful deploy -> almost always missing or wrong VpcConf, wrong private host, or security group. Follow references/vpc-and-database.md before rewriting application code.
Reference index
All packaged reference files (required for skill lint reachability):
