cloudrun-development

## 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 containers, arbitrary runtimes, custom system dependencies | | Port model | The function framework binds the platform port itself — **your code must not call `app.listen()`** | App must listen on the 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) 1. **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 2. **Follow mandatory runtime rules** - Container mode: listen on the injected `PORT`. Function mode: the framework binds the port for you — **never** call `app.listen()` - Settle the credential gate (who issues / how injected / how revoked) before writing any CloudBase SDK call - Keep the service stateless - Put durable data in DB/storage/cache - Keep dependencies and image size small - Respect resource ratio guidance: `Mem = 2 × CPU` 3. **Use the correct tools** - Read operations -> `queryCloudRun` - Write operations -> `manageCloudRun` - Delete requires explicit confirmation and `force: true` - Always use absolute `targetPath` 4. **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.md` **before** 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="getProcessLog")` -> **运行日志**（`tcbr/DescribeCloudRunProcessLog`）。返回部署阶段步骤（如 `create_version_check_vpc` / `create_eks_virtual_service` / `check_eks_virtual_service`）+ 容器启动/运行日志（s6-overlay、应用进程、readiness probe 失败原因）。**镜像部署与源码构建均可用，不依赖 CODING**。参数：`detailServerName`/`serverName` + 可选 `runId`（不传则取最新部署的 `RunId`；`RunId` 也可从 `detail` / `getDeployRecords` 的 `latestDeploy.RunId` 取得） - `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 - `queryCloudRun(action="getManageTask")` -> **发布任务状态**（`tcbr/DescribeServerManageTask`）。返回 `taskId` / `taskStatus` 与最新部署记录状态 `latestDeployStatus`。用于两件事：撞到「已有部署发布任务运行中」时先确认任务是否真在推进；以及部署长时间无进展时，区分「任务仍在推进」和「任务已卡住」。**不知道任务状态就不要反复重试 deploy** ### Log query SOP（构建日志 vs 运行日志） 部署失败排查时**必须区分**两类日志，不要只用 `getDeployLog`： 1. **云端源码构建**（传 `targetPath`、走 CODING 构建） - 先 `queryCloudRun(action="getDeployLog", detailServerName=..., buildId=...)` 查**构建日志**（编译/打包失败） - 再 `queryCloudRun(action="getProcessLog", detailServerName=..., runId=...)` 查**运行日志**（部署步骤 + 容器启动/健康检查） 2. **已有镜像部署**（传 `imageUrl`、`DeployType=image`） - **跳过** `getDeployLog`（无构建过程；且依赖 CODING，未登录会直接失败） - 直接 `queryCloudRun(action="detail")` 或 `getDeployRecords` 取 `latestDeploy.RunId`，再 `getProcessLog` 查运行日志 ```json { "action": "getProcessLog", "detailServerName": "my-svc", "runId": "<from latestDeploy.RunId>" } ``` ### Deploy-task SOP（撞到「已有部署发布任务运行中」时） `manageCloudRun(action="deploy")` 报「已有部署发布任务运行中」/ *already has a deploy task running* 时，**不要盲目重试，也不要反复改 Dockerfile / serverConfig** —— 先确认任务真实状态： 1. `queryCloudRun(action="getManageTask", detailServerName=...)` → 读 `taskId` / `taskStatus` / `latestDeployStatus` 2. `queryCloudRun(action="getProcessLog")` → 隔 20–40 秒对比两次拉取，确认部署阶段步骤是否还在推进 3. 按结果分支： | 观察 | 动作 | | --- | --- | | `taskStatus` 仍是运行态，部署步骤有推进 | **继续等**，不要重发 deploy | | 任务已结束（非运行态），而 deploy 仍被拒 | 才考虑重试 | | 任务长时间停在非终态，版本也停在 `creating` 不动 | 记录 `taskId` / `latestDeployStatus` / 时间窗作为证据，不要空转重试 | **`force=true` 不解决这个问题**：它只跳过本工具的确认提示，不会取消或覆盖服务端已有的发布任务 —— 把它当「强制覆盖」用只会白撞一次。 日志侧的排查顺序（构建日志 vs 运行日志、先日志后配置）见上面的 **Log query SOP** 与 **Container deploy failure SOP**。 ### Write operations - `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="download")` -> pull remote code - `manageCloudRun(action="run")` -> local run for Function mode