cloudrun-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use this skill

何时使用此技能

Use this skill for CloudBase Run backend service development when you need:

Long connection capabilities: WebSocket / SSE / server push
Long-running or persistent processes: tasks that are not suitable for cloud functions, background jobs
Custom runtime environments/system dependencies: custom images, specific system libraries
Multi-language/arbitrary frameworks: Java, Go, PHP, .NET, Python, Node.js, etc.
Stable external services with elastic scaling: pay-as-you-go, can scale down to 0
Private/internal network access: VPC/PRIVATE access, mini-program
```
callContainer
```
internal direct connection
AI agent development: develop personalized AI applications based on Function mode CloudRun

Do NOT use for:

Simple cloud functions (use cloud function development instead)
Frontend-only applications
Database schema design (use data-model-creation skill)

当您需要进行CloudBase Run 后端服务开发且满足以下场景时，使用此技能：

长连接能力：WebSocket / SSE / 服务器推送
长时间运行或持久化进程：不适合云函数的任务、后台作业
自定义运行时环境/系统依赖：自定义镜像、特定系统库
多语言/任意框架：Java、Go、PHP、.NET、Python、Node.js 等
具备弹性扩缩容的稳定外部服务：按量付费，可缩容至 0
私有/内网访问：VPC/PRIVATE 访问、小程序
```
callContainer
```
内网直连
AI Agent 开发：基于 Function 模式 CloudRun 开发个性化 AI 应用

请勿用于：

简单云函数场景（请使用云函数开发技能）
纯前端应用
数据库 schema 设计（请使用数据模型创建技能）

How to use this skill (for a coding agent)

如何使用此技能（面向编码 Agent）

Choose the right mode
- Function mode: Fastest to get started, built-in HTTP/WebSocket/SSE, fixed port 3000, local running supported
- Container mode: Any language and runtime, requires Dockerfile, local running not supported by tools
Follow mandatory requirements
- Must listen on
```
PORT
```
  environment variable (real port in container)
- Stateless service: write data externally (DB/storage/cache)
- No background persistent threads/processes outside requests
- Minimize dependencies, slim images; reduce cold start and deployment time
- Resource constraints:
```
Mem = 2 × CPU
```
  (e.g., 0.25 vCPU → 0.5 GB)
- Access control: Only enable public network for Web scenarios; mini-programs prioritize internal direct connection, recommend closing public network
Use tools correctly
- Read operations:
```
queryCloudRun
```
  (list, detail, templates)
- Write operations:
```
manageCloudRun
```
  (init, download, run, deploy, delete, createAgent)
- Always use absolute paths for
```
targetPath
```
- Use
```
force: true
```
  for delete operations
Follow the workflow
- Initialize project → Check/generate Dockerfile (for container mode) → Local run (function mode only) → Configure access → Deploy → Verify

选择合适的模式
- Function 模式：最快上手，内置 HTTP/WebSocket/SSE，固定端口 3000，支持本地运行
- Container 模式：支持任意语言和运行时，需要 Dockerfile，工具不支持本地运行
遵循强制要求
- 必须监听
```
PORT
```
  环境变量（容器内的实际端口）
- 无状态服务：数据需写入外部存储（数据库/存储/缓存）
- 除请求处理外，禁止后台持久线程/进程
- 最小化依赖，精简镜像；减少冷启动和部署时间
- 资源约束：
```
内存 = 2 × CPU
```
  （例如：0.25 vCPU → 0.5 GB）
- 访问控制：仅 Web 场景开启公网访问；小程序优先使用内网直连，建议关闭公网
正确使用工具
- 读取操作：
```
queryCloudRun
```
  （列表、详情、模板）
- 写入操作：
```
manageCloudRun
```
  （初始化、下载、运行、部署、删除、创建 Agent）
- ```
targetPath
```
  必须使用绝对路径
- 删除操作需添加
```
force: true
```
遵循工作流
- 初始化项目 → 检查/生成 Dockerfile（Container 模式）→ 本地运行（仅 Function 模式）→ 配置访问 → 部署 → 验证

CloudBase Run AI Development Rules

CloudBase Run AI 开发规范

A concise guide for AI assistants and engineering collaboration, providing "when to use, how to use" rules and tool workflows.

这是一份面向 AI 助手与工程协作的简明指南，提供「何时使用、如何使用」的规则及工具工作流。

1. When to use CloudBase Run (Use Cases)

1. 何时使用 CloudBase Run（适用场景）

Need long connection capabilities: WebSocket / SSE / server push
Need long-running or persistent processes: tasks that are not suitable for cloud functions, background jobs
Need custom runtime environments/system dependencies: custom images, specific system libraries
Use multi-language/arbitrary frameworks: Java, Go, PHP, .NET, Python, Node.js, etc.
Need stable external services with elastic scaling: pay-as-you-go, can scale down to 0
Need private/internal network access: VPC/PRIVATE access, mini-program
```
callContainer
```
internal direct connection
Need to develop AI agents: develop personalized AI applications based on Function mode CloudRun

需要长连接能力：WebSocket / SSE / 服务器推送
需要长时间运行或持久化进程：不适合云函数的任务、后台作业
需要自定义运行时环境/系统依赖：自定义镜像、特定系统库
使用多语言/任意框架：Java、Go、PHP、.NET、Python、Node.js 等
需要具备弹性扩缩容的稳定外部服务：按量付费，可缩容至 0
需要私有/内网访问：VPC/PRIVATE 访问、小程序
```
callContainer
```
内网直连
需要开发 AI Agent：基于 Function 模式 CloudRun 开发个性化 AI 应用

2. Mode Selection (Quick Comparison)

2. 模式选择（快速对比）

Function mode: Fastest to get started, built-in HTTP/WebSocket/SSE, fixed port 3000; local running supported by tools
Container mode: Any language and runtime, requires Dockerfile; local running not supported by tools

Function 模式：最快上手，内置 HTTP/WebSocket/SSE，固定端口 3000；工具支持本地运行
Container 模式：支持任意语言和运行时，需要 Dockerfile；工具不支持本地运行

Mode Comparison Checklist

模式对比检查表

Dimension	Function Mode	Container Mode
Language/Framework	Node.js (via `@cloudbase/functions-framework` )	Any language/runtime (Java/Go/PHP/.NET/Python/Node.js, etc.)
Runtime	Function framework loads functions (Runtime)	Docker image starts process
Port	Fixed 3000	Application listens on `PORT` (injected by platform during deployment)
Dockerfile	Not required	Required (and must pass local build)
Local Running	Supported (built-in tools)	Not supported (recommend using Docker for debugging)
Typical Scenarios	WebSocket/SSE/streaming responses, forms/files, low latency, multiple functions per instance, shared memory	Arbitrary system dependencies/languages, migrating existing containerized applications

维度	Function 模式	Container 模式
语言/框架	Node.js（基于 `@cloudbase/functions-framework` ）	任意语言/运行时（Java/Go/PHP/.NET/Python/Node.js 等）
运行时	函数框架加载函数（Runtime）	Docker 镜像启动进程
端口	固定 3000	应用监听 `PORT` （部署时由平台注入）
Dockerfile	不需要	必须提供（且需通过本地构建）
本地运行	支持（内置工具）	不支持（推荐使用 Docker 调试）
典型场景	WebSocket/SSE/流式响应、表单/文件处理、低延迟、单实例多函数、共享内存	任意系统依赖/语言、迁移现有容器化应用

3. Development Requirements (Must Meet)

3. 开发要求（必须满足）

Must listen on
```
PORT
```
environment variable (real port in container)
Stateless service: write data externally (DB/storage/cache)
No background persistent threads/processes outside requests
Minimize dependencies, slim images; reduce cold start and deployment time
Resource constraints:
```
Mem = 2 × CPU
```
(e.g., 0.25 vCPU → 0.5 GB)
Access control: Only enable public network for Web scenarios; mini-programs prioritize internal direct connection, recommend closing public network

必须监听
```
PORT
```
环境变量（容器内的实际端口）
无状态服务：数据需写入外部存储（数据库/存储/缓存）
除请求处理外，禁止后台持久线程/进程
最小化依赖，精简镜像；减少冷启动和部署时间
资源约束：
```
内存 = 2 × CPU
```
（例如：0.25 vCPU → 0.5 GB）
访问控制：仅 Web 场景开启公网访问；小程序优先使用内网直连，建议关闭公网

4. Tools (Plain Language & Read/Write Separation)

4. 工具（通俗化与读写分离）

Read operations (
```
queryCloudRun
```
):
- ```
list
```
  : What services do I have? Can filter by name/type
- ```
detail
```
  : Current configuration, version, access address of a service
- ```
templates
```
  : Ready-to-use starter templates
Write operations (
```
manageCloudRun
```
):
- ```
init
```
  : Create local project (optional template)
- ```
download
```
  : Pull existing service code to local
- ```
run
```
  : Run locally (Function mode only, supports normal function and Agent mode)
- ```
deploy
```
  : Deploy local code to CloudRun
- ```
delete
```
  : Delete service (requires explicit confirmation)
- ```
createAgent
```
  : Create AI agent (based on Function mode CloudRun)
Important parameters (remember these):
- ```
targetPath
```
  : Local directory (must be absolute path)
- ```
serverConfig
```
  : Deployment parameters (CPU/Mem/instance count/access type/environment variables, etc.)
- ```
runOptions
```
  : Local running port and temporary environment variables (Function mode), supports
```
runMode: 'normal' | 'agent'
```
- ```
agentConfig
```
  : Agent configuration (agentName, botTag, description, template)
- Delete must include
```
force: true
```
  , otherwise it won't execute

读取操作（
```
queryCloudRun
```
）：
- ```
list
```
  ：查看我拥有的服务？可按名称/类型过滤
- ```
detail
```
  ：查看某个服务的当前配置、版本、访问地址
- ```
templates
```
  ：查看可用的启动模板
写入操作（
```
manageCloudRun
```
）：
- ```
init
```
  ：创建本地项目（可选模板）
- ```
download
```
  ：将现有服务代码拉取到本地
- ```
run
```
  ：本地运行（仅 Function 模式，支持普通函数和 Agent 模式）
- ```
deploy
```
  ：将本地代码部署到 CloudRun
- ```
delete
```
  ：删除服务（需显式确认）
- ```
createAgent
```
  ：创建 AI Agent（基于 Function 模式 CloudRun）
重要参数（请牢记）：
- ```
targetPath
```
  ：本地目录（必须为绝对路径）
- ```
serverConfig
```
  ：部署参数（CPU/内存/实例数/访问类型/环境变量等）
- ```
runOptions
```
  ：本地运行端口和临时环境变量（Function 模式），支持
```
runMode: 'normal' | 'agent'
```
- ```
agentConfig
```
  ：Agent 配置（agentName、botTag、description、template）
- 删除操作必须包含
```
force: true
```
  ，否则不会执行

5. Core Workflow (Understand Steps First, Then Examples)

5. 核心工作流（先理解步骤，再看示例）

Choose mode
- Need multi-language/existing container/Docker: choose "Container mode"
- Need long connection/streaming/low latency/multiple functions coexisting: prioritize "Function mode"

Initialize local project

General: Use template
```
init
```
(both Function mode and Container mode can start from templates)

Container mode must "check or generate Dockerfile":

Node.js minimal example:

dockerfile

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV NODE_ENV=production
EXPOSE 3000
CMD ["node","server.js"]

Python minimal example:

dockerfile

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt ./
RUN pip install -r requirements.txt --no-cache-dir
COPY . .
ENV PORT=3000
EXPOSE 3000
CMD ["python","app.py"]

Local running (Function mode only)
- Automatically use
```
npm run dev/start
```
  or entry file via
```
run
```
Configure access
- Set
```
OpenAccessTypes
```
  (WEB/VPC/PRIVATE) as needed; configure security domain and authentication for Web scenarios
Deploy
- Specify CPU/Mem/instance count/environment variables, etc. during
```
deploy
```
Verify
- Use
```
detail
```
  to confirm access address and configuration meet expectations

选择模式
- 需要多语言/现有容器/Docker：选择「Container 模式」
- 需要长连接/流式响应/低延迟/多函数共存：优先选择「Function 模式」

初始化本地项目

通用方式：使用模板
```
init
```
（Function 模式和 Container 模式均可从模板开始）

Container 模式必须「检查或生成 Dockerfile」：

Node.js 最简示例：

dockerfile

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV NODE_ENV=production
EXPOSE 3000
CMD ["node","server.js"]

Python 最简示例：

dockerfile

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt ./
RUN pip install -r requirements.txt --no-cache-dir
COPY . .
ENV PORT=3000
EXPOSE 3000
CMD ["python","app.py"]

本地运行（仅 Function 模式）
- 通过
```
run
```
  自动使用
```
npm run dev/start
```
  或入口文件
配置访问
- 根据需要设置
```
OpenAccessTypes
```
  （WEB/VPC/PRIVATE）；Web 场景需配置安全域名和认证
部署
- ```
deploy
```
  时指定 CPU/内存/实例数/环境变量等
验证
- 使用
```
detail
```
  确认访问地址和配置符合预期

Example Tool Calls

工具调用示例

View templates/services

json

{ "name": "queryCloudRun", "arguments": { "action": "templates" } }

json

{ "name": "queryCloudRun", "arguments": { "action": "detail", "detailServerName": "my-svc" } }

Initialize project

json

{ "name": "manageCloudRun", "arguments": { "action": "init", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "template": "helloworld" } }

Download code (optional)

json

{ "name": "manageCloudRun", "arguments": { "action": "download", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc" } }

Local running (Function mode only)

json

{ "name": "manageCloudRun", "arguments": { "action": "run", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "runOptions": { "port": 3000 } } }

Deploy

json

{ "name": "manageCloudRun", "arguments": { "action": "deploy", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "serverConfig": { "OpenAccessTypes": ["WEB"], "Cpu": 0.5, "Mem": 1, "MinNum": 0, "MaxNum": 5 } } }

Create AI agent (optional)

json

{ "name": "manageCloudRun", "arguments": { "action": "createAgent", "serverName": "my-agent", "targetPath": "/abs/ws/agents", "agentConfig": { "agentName": "MyAgent", "botTag": "demo", "description": "My agent", "template": "blank" } } }

Run agent (optional)

json

{ "name": "manageCloudRun", "arguments": { "action": "run", "serverName": "my-agent", "targetPath": "/abs/ws/agents/my-agent", "runOptions": { "port": 3000, "runMode": "agent" } } }

查看模板/服务

json

{ "name": "queryCloudRun", "arguments": { "action": "templates" } }

json

{ "name": "queryCloudRun", "arguments": { "action": "detail", "detailServerName": "my-svc" } }

初始化项目

json

{ "name": "manageCloudRun", "arguments": { "action": "init", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "template": "helloworld" } }

下载代码（可选）

json

{ "name": "manageCloudRun", "arguments": { "action": "download", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc" } }

本地运行（仅 Function 模式）

json

{ "name": "manageCloudRun", "arguments": { "action": "run", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "runOptions": { "port": 3000 } } }

部署

json

{ "name": "manageCloudRun", "arguments": { "action": "deploy", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "serverConfig": { "OpenAccessTypes": ["WEB"], "Cpu": 0.5, "Mem": 1, "MinNum": 0, "MaxNum": 5 } } }

创建 AI Agent（可选）

json

{ "name": "manageCloudRun", "arguments": { "action": "createAgent", "serverName": "my-agent", "targetPath": "/abs/ws/agents", "agentConfig": { "agentName": "MyAgent", "botTag": "demo", "description": "My agent", "template": "blank" } } }

运行 Agent（可选）

json

{ "name": "manageCloudRun", "arguments": { "action": "run", "serverName": "my-agent", "targetPath": "/abs/ws/agents/my-agent", "runOptions": { "port": 3000, "runMode": "agent" } } }

6. Best Practices (Strongly Recommended)

6. 最佳实践（强烈推荐）

Prioritize PRIVATE/VPC or mini-program internal
```
callContainer
```
, reduce public network exposure
Web must use CloudBase Web SDK authentication; mini-programs authenticated by platform
Secrets via environment variables; separate configuration for multiple environments (dev/stg/prod)
Use
```
queryCloudRun.detail
```
to verify configuration and accessibility before and after deployment
Image layers reusable, small volume; monitor startup latency and memory usage
Agent development: Use
```
@cloudbase/aiagent-framework
```
, supports SSE streaming responses, BotId format is
```
ibot-{name}-{tag}
```

优先使用 PRIVATE/VPC 或小程序内网
```
callContainer
```
，减少公网暴露
Web 场景必须使用 CloudBase Web SDK 认证；小程序由平台自动认证
敏感信息通过环境变量传递；多环境（开发/测试/生产）配置分离
部署前后使用
```
queryCloudRun.detail
```
验证配置和可访问性
镜像层可复用、体积小；监控启动延迟和内存使用
Agent 开发：使用
```
@cloudbase/aiagent-framework
```
，支持 SSE 流式响应，BotId 格式为
```
ibot-{name}-{tag}
```

7. Quick Troubleshooting

7. 快速故障排查

Access failure: Check OpenAccessTypes/domain/port, whether instance scaled down to 0
Deployment failure: Verify Dockerfile/build logs/image volume and CPU/Mem ratio
Local running failure: Only Function mode supported; requires
```
package.json
```
```
dev
```
/
```
start
```
or entry
```
index.js|app.js|server.js
```
Performance jitter: Reduce dependencies and initialization; appropriately increase MinNum; optimize cold start
Agent running failure: Check
```
@cloudbase/aiagent-framework
```
dependency, BotId format, SSE response format

访问失败：检查 OpenAccessTypes/域名/端口，实例是否缩容至 0
部署失败：验证 Dockerfile/构建日志/镜像体积及 CPU/内存比例
本地运行失败：仅支持 Function 模式；需要
```
package.json
```
中的
```
dev
```
/
```
start
```
脚本或入口文件
```
index.js|app.js|server.js
```
性能抖动：减少依赖和初始化操作；适当提高 MinNum；优化冷启动
Agent 运行失败：检查
```
@cloudbase/aiagent-framework
```
依赖、BotId 格式、SSE 响应格式

8. Function Mode CloudRun (Function Mode) Key Points (Concise)

8. Function 模式 CloudRun（Function Mode）核心要点（精简版）

Definition: CloudRun + function framework (
```
@cloudbase/functions-framework
```
) + function code, making container service development as simple as writing cloud functions
When to choose: Need WebSocket/SSE/file upload/streaming responses; need long tasks or connect to DB/message queue; need multiple functions per instance and shared memory, low latency and better logs/debugging
Agent mode: Develop AI agents based on Function mode CloudRun, use
```
@cloudbase/aiagent-framework
```
, supports SSE streaming responses and personalized AI applications
Tool support: Local running only supports Function mode (
```
manageCloudRun
```
→
```
run
```
); deploy using
```
manageCloudRun
```
→
```
deploy
```
; query using
```
queryCloudRun
```
Migration tips: Different from cloud function call chain/runtime, migration requires minor modifications (including client calling methods)
Portability: Based on function framework, can run locally/host/Docker, non-CloudRun requires self-managed build and deployment

定义：CloudRun + 函数框架（
```
@cloudbase/functions-framework
```
）+ 函数代码，让容器服务开发像编写云函数一样简单
适用场景：需要 WebSocket/SSE/文件上传/流式响应；需要长任务或连接数据库/消息队列；需要单实例多函数共存和共享内存、低延迟及更完善的日志/调试能力
Agent 模式：基于 Function 模式 CloudRun 开发 AI Agent，使用
```
@cloudbase/aiagent-framework
```
，支持 SSE 流式响应和个性化 AI 应用
工具支持：仅 Function 模式支持本地运行（
```
manageCloudRun
```
→
```
run
```
）；使用
```
manageCloudRun
```
→
```
deploy
```
部署；使用
```
queryCloudRun
```
查询
迁移提示：与云函数调用链/运行时不同，迁移需少量修改（包括客户端调用方式）
可移植性：基于函数框架，可本地/自建主机/Docker 运行；非 CloudRun 环境需自行管理构建和部署

9. Service Invocation Methods (Concise Examples)

9. 服务调用方式（精简示例）

HTTP Direct Access (when WEB public network enabled)

HTTP 直接访问（开启 WEB 公网访问时）

bash

curl -L "https://<your-service-domain>"

bash

curl -L "https://<your-service-domain>"

WeChat Mini Program (internal direct connection, recommend closing public network)

微信小程序（内网直连，建议关闭公网）

// app.js (ensure wx.cloud.init() is called)
const res = await wx.cloud.callContainer({
  config: { env: "<envId>" },
  path: "/",
  method: "GET",
  header: { "X-WX-SERVICE": "<serviceName>" }
});

// app.js（确保已调用 wx.cloud.init()）
const res = await wx.cloud.callContainer({
  config: { env: "<envId>" },
  path: "/",
  method: "GET",
  header: { "X-WX-SERVICE": "<serviceName>" }
});

Web (JS SDK, need to configure security domain and authentication)

Web（JS SDK，需配置安全域名和认证）

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({ env: "<envId>" });  // Collect user's phone number into variable `phoneNum` by providing a input UI

const auth = app.auth();

// Send SMS code
const verificationInfo = await auth.getVerification({
  phone_number: `+86 ${phoneNum}`,
});

// Collect user's phone number into variable `verificationCode` by providing a input UI 

// Sign in
await auth.signInWithSms({
  verificationInfo,
  verificationCode,
  phoneNum,
});

const res = await app.callContainer({
  name: "<serviceName>", method: "POST", path: "/api",
  header: { "Content-Type": "application/json" },
  data: { key: "value" }
});

// Web JS SDK initialization MUST be synchronous: // - Always use top-level

import cloudbase from "@cloudbase/js-sdk";

// - Do NOT use dynamic imports like

import("@cloudbase/js-sdk")

or async wrappers such as

initCloudBase()

with internal

initPromise

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({ env: "<envId>" });  // 通过输入界面收集用户手机号到变量 `phoneNum`

const auth = app.auth();

// 发送短信验证码
const verificationInfo = await auth.getVerification({
  phone_number: `+86 ${phoneNum}`,
});

// 通过输入界面收集用户验证码到变量 `verificationCode`

// 登录
await auth.signInWithSms({
  verificationInfo,
  verificationCode,
  phoneNum,
});

const res = await app.callContainer({
  name: "<serviceName>", method: "POST", path: "/api",
  header: { "Content-Type": "application/json" },
  data: { key: "value" }
});

// Web JS SDK 初始化必须同步： // - 始终使用顶层

import cloudbase from "@cloudbase/js-sdk";

// - 禁止使用动态导入如

import("@cloudbase/js-sdk")

或异步包装如包含内部

initPromise

的

initCloudBase()

Node.js (server-side/cloud function internal call)

Node.js（服务端/云函数内部调用）

import tcb from "@cloudbase/node-sdk";
const app = tcb.init({});
const res = await app.callContainer({
  name: "<serviceName>", method: "GET", path: "/health",
  timeout: 5000
});

import tcb from "@cloudbase/node-sdk";
const app = tcb.init({});
const res = await app.callContainer({
  name: "<serviceName>", method: "GET", path: "/health",
  timeout: 5000
});

Recommendations

建议

Mini Program/Server side prioritize internal network (VPC/PRIVATE) calls, reduce exposure surface
Web scenarios need to enable WEB, public domain and security domain, and use SDK authentication

小程序/服务端优先使用内网（VPC/PRIVATE）调用，减少暴露面
Web 场景需开启 WEB、公网域名和安全域名，并使用 SDK 认证