cloudbase-platform

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use this skill

何时使用此技能

Use this skill for CloudBase platform knowledge when you need to:

Understand CloudBase storage and hosting concepts
Configure authentication for different platforms (Web vs Mini Program)
Deploy and manage cloud functions
Understand database permissions and access control
Work with data models (MySQL and NoSQL)
Access CloudBase console management pages

This skill provides foundational knowledge that applies to all CloudBase projects, regardless of whether they are Web, Mini Program, or backend services.

当你需要以下相关的CloudBase平台知识时，使用此技能：

了解CloudBase存储与托管概念
为不同平台配置身份认证（Web vs 小程序）
部署与管理云函数
了解数据库权限与访问控制
处理数据模型（MySQL与NoSQL）
访问CloudBase控制台管理页面

此技能提供基础知识，适用于所有CloudBase项目，无论它们是Web、小程序还是后端服务。

How to use this skill (for a coding agent)

如何使用此技能（针对编码Agent）

Understand platform differences
- Web and Mini Program have completely different authentication approaches
- Must strictly distinguish between platforms
- Never mix authentication methods across platforms
Follow best practices
- Use SDK built-in authentication features (Web)
- Understand natural login-free feature (Mini Program)
- Configure appropriate database permissions
- Use cloud functions for cross-collection operations
Use correct SDKs and APIs
- Different platforms require different SDKs for data models
- MySQL data models must use models SDK, not collection API
- Use
```
envQuery
```
  tool to get environment ID

了解平台差异
- Web和小程序的身份认证方式完全不同
- 必须严格区分平台
- 切勿跨平台混用认证方法
遵循最佳实践
- 使用SDK内置的身份认证功能（Web端）
- 了解小程序的天然免登录特性
- 配置合适的数据库权限
- 使用云函数实现跨集合操作
使用正确的SDK与API
- 不同平台的数据模型需要使用不同的SDK
- MySQL数据模型必须使用Models SDK，而非集合API
- 使用
```
envQuery
```
  工具获取环境ID

CloudBase Platform Knowledge

CloudBase平台知识

Storage and Hosting

存储与托管

Static Hosting vs Cloud Storage:
- CloudBase static hosting and cloud storage are two different buckets
- Generally, publicly accessible files can be stored in static hosting, which provides a public web address
- Static hosting supports custom domain configuration (requires console operation)
- Cloud storage is suitable for files with privacy requirements, can get temporary access addresses via temporary file URLs
Static Hosting Domain:
- CloudBase static hosting domain can be obtained via
```
getWebsiteConfig
```
  tool
- Combine with static hosting file paths to construct final access addresses
- Important: If access address is a directory, it must end with
```
/
```

静态托管 vs 云存储:
- CloudBase静态托管与云存储是两个不同的存储桶
- 通常，公开可访问的文件可存储在静态托管中，它提供公开的网页地址
- 静态托管支持自定义域名配置（需在控制台操作）
- 云存储适合有隐私要求的文件，可通过临时文件URL获取临时访问地址
静态托管域名:
- 可通过
```
getWebsiteConfig
```
  工具获取CloudBase静态托管域名
- 结合静态托管文件路径构建最终访问地址
- 重要提示：如果访问地址是目录，必须以
```
/
```
  结尾

Environment and Authentication

环境与身份认证

SDK Initialization:
- CloudBase SDK initialization requires environment ID
- Can query environment ID via
```
envQuery
```
  tool
- For Web, always initialize synchronously:
  - ```
  import cloudbase from "@cloudbase/js-sdk"; const app = cloudbase.init({ env: "xxxx-yyy" });
```
- Do not use dynamic imports like
```
  import("@cloudbase/js-sdk")
```
  or async wrappers such as
```
  initCloudBase()
```
  with internal
```
  initPromise
```
- Then proceed with login, for example using anonymous login

SDK初始化:
- CloudBase SDK初始化需要环境ID
- 可通过
```
envQuery
```
  工具查询环境ID
- 对于Web端，始终同步初始化：
  - ```
  import cloudbase from "@cloudbase/js-sdk"; const app = cloudbase.init({ env: "xxxx-yyy" });
```
- 请勿使用动态导入如
```
  import("@cloudbase/js-sdk")
```
  或带有内部
```
  initPromise
```
  的异步包装器如
```
  initCloudBase()
```
- 之后进行登录操作，例如使用匿名登录

Authentication Best Practices

身份认证最佳实践

Important: Authentication methods for different platforms are completely different, must strictly distinguish!

重要提示：不同平台的身份认证方式完全不同，必须严格区分！

Web Authentication

Web端身份认证

Must use SDK built-in authentication: CloudBase Web SDK provides complete authentication features
Recommended method: SMS login with
```
auth.getVerification()
```
, for detailed, refer to web auth related docs
Forbidden behavior: Do not use cloud functions to implement login authentication logic
User management: After login, get user information via
```
auth.getCurrentUser()
```

必须使用SDK内置认证：CloudBase Web SDK提供完整的身份认证功能
推荐方式：使用
```
auth.getVerification()
```
实现短信登录，详情请参考Web端认证相关文档
禁止行为：请勿使用云函数实现登录认证逻辑
用户管理：登录后，通过
```
auth.getCurrentUser()
```
获取用户信息

Mini Program Authentication

小程序身份认证

Login-free feature: Mini program CloudBase is naturally login-free, no login flow needed
User identifier: In cloud functions, get
```
wxContext.OPENID
```
via wx-server-sdk
User management: Manage user data in cloud functions based on openid
Forbidden behavior: Do not generate login pages or login flow code

免登录特性：小程序CloudBase天然支持免登录，无需登录流程
用户标识：在云函数中，通过wx-server-sdk获取
```
wxContext.OPENID
```
用户管理：在云函数中基于openid管理用户数据
禁止行为：请勿生成登录页面或登录流程代码

Cloud Functions

云函数

Node.js Cloud Functions:
- Node.js cloud functions need to include
```
package.json
```
  , declaring required dependencies
- Can use
```
createFunction
```
  to create functions
- Use
```
updateFunctionCode
```
  to deploy cloud functions
- Prioritize cloud dependency installation, do not upload node_modules
- ```
functionRootPath
```
  refers to the parent directory of function directories, e.g.,
```
cloudfunctions
```
  directory

Node.js云函数:
- Node.js云函数需要包含
```
package.json
```
  ，声明所需依赖
- 可使用
```
createFunction
```
  创建函数
- 使用
```
updateFunctionCode
```
  部署云函数
- 优先使用云端依赖安装，请勿上传node_modules
- ```
functionRootPath
```
  指函数目录的父目录，例如
```
cloudfunctions
```
  目录

Database Permissions

数据库权限

⚠️ CRITICAL: Always configure permissions BEFORE writing database operation code!

Permission Model:
- CloudBase database access has permissions
- Default basic permissions include:
  - READONLY: Everyone can read, only creator/admin can write
  - PRIVATE: Only creator/admin can read/write
  - ADMINWRITE: Everyone can read, only admin can write (⚠️ NOT for Web SDK write!)
  - ADMINONLY: Only admin can read/write
  - CUSTOM: Fine-grained control with custom rules
Platform Compatibility (CRITICAL):
- ⚠️ Web SDK cannot use
  ADMINWRITE
  or
  ADMINONLY
  for write operations
- ✅ For user-generated content in Web apps, use CUSTOM rules
- ✅ For admin-managed data (products, settings), use READONLY
- ✅ Cloud functions have full access regardless of permission type
Configuration Workflow:
```
Create collection → Configure security rules → Write code → Test
```
- Use
```
writeSecurityRule
```
  MCP tool to configure permissions
- Wait 2-5 minutes for cache to clear before testing
- See
```
no-sql-web-sdk/security-rules.md
```
  for detailed examples
Common Scenarios:
- E-commerce products:
```
READONLY
```
  (admin manages via cloud functions)
- Shopping carts:
```
CUSTOM
```
  with
```
auth.uid
```
  check (users manage their own)
- Orders:
```
CUSTOM
```
  with ownership validation
- System logs:
```
PRIVATE
```
  or
```
ADMINONLY
```
Cross-Collection Operations:
- If user has no special requirements, operations involving cross-database collections must be implemented via cloud functions
Cloud Function Optimization:
- If involving cloud functions, while ensuring security, can minimize the number of cloud functions as much as possible
- For example: implement one cloud function for client-side requests, implement one cloud function for data initialization

⚠️ 关键提示：在编写数据库操作代码前，务必先配置权限！

权限模型:
- CloudBase数据库访问有权限控制
- 默认基础权限包括：
  - READONLY：所有人可读取，仅创建者/管理员可写入
  - PRIVATE：仅创建者/管理员可读写
  - ADMINWRITE：所有人可读取，仅管理员可写入（⚠️ 不适用于Web SDK写入！）
  - ADMINONLY：仅管理员可读写
  - CUSTOM：通过自定义规则实现细粒度控制
平台兼容性（关键）:
- ⚠️ Web SDK无法使用
  ADMINWRITE
  或
  ADMINONLY
  进行写入操作
- ✅ 对于Web应用中的用户生成内容，使用CUSTOM规则
- ✅ 对于管理员管理的数据（产品、设置），使用READONLY
- ✅ 无论权限类型如何，云函数都拥有完全访问权限

配置流程:

创建集合 → 配置安全规则 → 编写代码 → 测试

使用
```
writeSecurityRule
```
MCP工具配置权限
测试前需等待2-5分钟让缓存清除
详细示例请查看
```
no-sql-web-sdk/security-rules.md
```

常见场景:
- 电商产品：
```
READONLY
```
  （管理员通过云函数管理）
- 购物车：带有
```
auth.uid
```
  校验的
```
CUSTOM
```
  规则（用户管理自己的购物车）
- 订单：带有所有权验证的
```
CUSTOM
```
  规则
- 系统日志：
```
PRIVATE
```
  或
```
ADMINONLY
```
跨集合操作:
- 如果用户无特殊要求，涉及跨数据库集合的操作必须通过云函数实现
云函数优化:
- 如果涉及云函数，在确保安全的前提下，可尽量减少云函数的数量
- 例如：为客户端请求实现一个云函数，为数据初始化实现一个云函数

Data Models

数据模型

Get Data Model Operation Object:

Mini Program: Need

@cloudbase/wx-cloud-client-sdk

, initialize

const client = initHTTPOverCallFunction(wx.cloud)

, use

client.models

Cloud Function: Need

@cloudbase/node-sdk@3.10+

, initialize

const app = cloudbase.init({env})

, use

app.models

Web: Need

@cloudbase/js-sdk

, initialize

const app = cloudbase.init({env})

, after login use

app.models

Data Model Query:
- Can call MCP
```
manageDataModel
```
  tool to:
  - Query model list
  - Get model detailed information (including Schema fields)
  - Get specific models SDK usage documentation
MySQL Data Model Invocation Rules:
- MySQL data models cannot use collection method invocation, must use data model SDK
- Wrong:
```
db.collection('model_name').get()
```
- Correct:
```
app.models.model_name.list({ filter: { where: {} } })
```
- Use
```
manageDataModel
```
  tool's
```
docs
```
  method to get specific SDK usage

获取数据模型操作对象:

小程序：需要

@cloudbase/wx-cloud-client-sdk

，初始化

const client = initHTTPOverCallFunction(wx.cloud)

，使用

client.models

云函数：需要

@cloudbase/node-sdk@3.10+

，初始化

const app = cloudbase.init({env})

，使用

app.models

Web：需要

@cloudbase/js-sdk

，初始化

const app = cloudbase.init({env})

，登录后使用

app.models

数据模型查询:
- 可调用MCP
```
manageDataModel
```
  工具来：
  - 查询模型列表
  - 获取模型详细信息（包括Schema字段）
  - 获取特定模型的SDK使用文档
MySQL数据模型调用规则:
- MySQL数据模型无法使用集合方法调用，必须使用数据模型SDK
- 错误示例：
```
db.collection('model_name').get()
```
- 正确示例：
```
app.models.model_name.list({ filter: { where: {} } })
```
- 使用
```
manageDataModel
```
  工具的
```
docs
```
  方法获取特定SDK使用方式

Console Management

控制台管理

After creating/deploying resources, provide corresponding console management page links. All console URLs follow the pattern:

https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path}

创建/部署资源后，提供对应的控制台管理页面链接。所有控制台URL遵循以下格式：

https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path}

Core Function Entry Points

核心功能入口

Overview (概览):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/overview
```
- Main dashboard showing environment status, resource usage, and quick access to key features
- Displays overview of all CloudBase services and their status
Template Center (模板中心):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/template
```
- Access project templates for React, Vue, Mini Program, UniApp, and backend frameworks
- AI Builder templates for rapid application generation
- Framework templates: React, Vue, Miniapp, UniApp, Gin, Django, Flask, SpringBoot, Express, NestJS, FastAPI
Document Database (文档型数据库):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/db/doc
```
- Manage NoSQL document database collections
- Collection Management:
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/db/doc/collection/${collectionName}
```
  - View, edit, and manage collection data
  - Configure security rules and permissions
- Data Model Management:
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/db/doc/model/${modelName}
```
  - Create and manage data models with relationships
  - View model schema and field definitions
MySQL Database (MySQL 数据库):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/db/mysql
```
- Manage MySQL relational database
- Table Management:
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/db/mysql/table/default/
```
  - Create, modify, and manage database tables
  - Execute SQL queries and manage table structure
- Important: Must enable MySQL database in console before use
Cloud Functions (云函数):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/scf
```
- Manage and deploy Node.js cloud functions
- Function List:
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/scf
```
- Function Detail:
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/scf/detail?id=${functionName}&NameSpace=${envId}
```
  - View function code, logs, and configuration
  - Manage function triggers and environment variables
  - Monitor function invocations and performance
CloudRun (云托管):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/cloudrun
```
- Manage containerized backend services
- Deploy services using Function mode or Container mode
- Configure service scaling, access types, and environment variables
- View service logs and monitoring data
Cloud Storage (云存储):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/storage
```
- Manage file storage buckets
- Upload, download, and organize files
- Configure storage permissions and access policies
- Generate temporary access URLs for private files
AI+:
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/ai
```
- Access AI capabilities and services
- AI Builder for generating templates and code
- AI image recognition and other AI features
Static Website Hosting (静态网站托管):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/hosting
```
- Deploy and manage static websites
- Alternative URL:
```
https://console.cloud.tencent.com/tcb/hosting
```
- Configure custom domains and CDN settings
- View deployment history and access logs
Identity Authentication (身份认证):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/identity
```
- Configure authentication methods and user management
- Login Management:
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/identity/login-manage
```
  - Enable/disable login methods (SMS, Email, Username/Password, WeChat, Custom Login)
  - Configure SMS/Email templates
  - Manage security domain whitelist
- Token Management:
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/identity/token-management
```
  - Manage API Keys and Publishable Keys
  - View and manage access tokens
Weida Low-Code (微搭低代码):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/weida
```
- Access Weida low-code development platform
- Build applications using visual drag-and-drop interface
Logs & Monitoring (日志监控):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/logs
```
- View logs from cloud functions, CloudRun services, and other resources
- Monitor resource usage, performance metrics, and error rates
- Set up alerts and notifications
Environment Settings (环境配置):
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/settings
```
- Configure environment-level settings
- Manage security domains and CORS settings
- Configure environment variables and secrets
- View environment information and resource quotas

概览：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/overview
```
- 显示环境状态、资源使用情况的主仪表盘，以及关键功能的快速入口
- 展示所有CloudBase服务及其状态的概览
模板中心：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/template
```
- 访问适用于React、Vue、小程序、UniApp及后端框架的项目模板
- 用于快速生成应用的AI Builder模板
- 框架模板：React、Vue、Miniapp、UniApp、Gin、Django、Flask、SpringBoot、Express、NestJS、FastAPI
文档型数据库：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/db/doc
```
- 管理NoSQL文档数据库集合
- 集合管理：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/db/doc/collection/${collectionName}
```
  - 查看、编辑和管理集合数据
  - 配置安全规则与权限
- 数据模型管理：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/db/doc/model/${modelName}
```
  - 创建和管理带有关联关系的数据模型
  - 查看模型Schema与字段定义
MySQL数据库：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/db/mysql
```
- 管理MySQL关系型数据库
- 表管理：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/db/mysql/table/default/
```
  - 创建、修改和管理数据库表
  - 执行SQL查询并管理表结构
- 重要提示：使用前必须在控制台中启用MySQL数据库

云函数：

https://tcb.cloud.tencent.com/dev?envId=${envId}#/scf

管理和部署Node.js云函数

函数列表：

https://tcb.cloud.tencent.com/dev?envId=${envId}#/scf

函数详情：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/scf/detail?id=${functionName}&NameSpace=${envId}
```
- 查看函数代码、日志和配置
- 管理函数触发器与环境变量
- 监控函数调用与性能

云托管：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/cloudrun
```
- 管理容器化后端服务
- 使用函数模式或容器模式部署服务
- 配置服务扩缩容、访问类型和环境变量
- 查看服务日志与监控数据
云存储：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/storage
```
- 管理文件存储桶
- 上传、下载和整理文件
- 配置存储权限与访问策略
- 为私有文件生成临时访问URL
AI+：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/ai
```
- 访问AI能力与服务
- 用于生成模板和代码的AI Builder
- AI图像识别及其他AI功能
静态网站托管：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/hosting
```
- 部署和管理静态网站
- 备用URL：
```
https://console.cloud.tencent.com/tcb/hosting
```
- 配置自定义域名与CDN设置
- 查看部署历史与访问日志
身份认证：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/identity
```
- 配置认证方式与用户管理
- 登录管理：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/identity/login-manage
```
  - 启用/禁用登录方式（短信、邮箱、用户名/密码、微信、自定义登录）
  - 配置短信/邮箱模板
  - 管理安全域名白名单
- Token管理：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/identity/token-management
```
  - 管理API密钥与可发布密钥
  - 查看和管理访问Token
微搭低代码：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/weida
```
- 访问微搭低代码开发平台
- 使用可视化拖拽界面构建应用
日志监控：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/logs
```
- 查看云函数、CloudRun服务及其他资源的日志
- 监控资源使用情况、性能指标和错误率
- 设置告警与通知
环境配置：
```
https://tcb.cloud.tencent.com/dev?envId=${envId}#/settings
```
- 配置环境级别的设置
- 管理安全域与CORS设置
- 配置环境变量与密钥
- 查看环境信息与资源配额

URL Construction Guidelines

URL构建指南

Base URL Pattern:

https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path}

Replace Variables: Always replace
```
${envId}
```
with the actual environment ID queried via
```
envQuery
```
tool
Resource-Specific URLs: For specific resources (collections, functions, models), replace resource name variables with actual values
Usage: After creating/deploying resources, provide these console links to users for management operations

基础URL格式：

https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path}

替换变量：始终将
```
${envId}
```
替换为通过
```
envQuery
```
工具查询到的实际环境ID
特定资源URL：对于特定资源（集合、函数、模型），将资源名称变量替换为实际值
使用方式：创建/部署资源后，为用户提供这些控制台链接以进行管理操作

Quick Reference

快速参考

When directing users to console pages:

Use the full URL with environment ID
Explain what they can do on each page
Provide context about why they need to access that specific page
For configuration pages (like login management), guide users through the setup process

引导用户访问控制台页面时：

使用包含环境ID的完整URL
说明他们在每个页面可以执行的操作
提供他们需要访问该特定页面的上下文
对于配置页面（如登录管理），引导用户完成设置流程