跳到主要内容

平台接入云开发方案

CloudBase for Platform 是什么​

面向 AI Coding、Vibe Coding 等平台（如 Lovable、Bolt.new、Vercel v0、Figma Make）的解决方案，让任意平台可以代替它的用户来配置和管理后端。平台希望向终端用户提供更无缝的流程、即开即用的后端能力，同时不暴露数据库、云函数、对象存储等底层资源的复杂性——用户不必理解这些概念，即可通过一句话或简单操作获得一个可用的应用。

您能获得什么：用云开发为您的每个租户提供一个独立环境，每个环境内包含数据库、云函数、静态托管和统一的 HTTP 访问入口；租户之间资源隔离，您通过腾讯云 API 即可完成创建、计费、部署、数据库与监控的自动化管理。

适用场景：SaaS、内部业务平台、多租户系统，或 AI Coding / Vibe Coding 平台——希望为每个客户/租户提供可隔离的后端能力，并通过 API 而非仅控制台来管理。

管理单元：以环境为单位。一个环境 = 一个租户的一整套资源（数据库、云函数、HTTP 访问服务、静态托管等），通常一租户一环境。所有能力均通过 腾讯云开发 API 以编程方式管理。

腾讯云账号与环境的关系：采用大账号模式——您使用一个腾讯云账号（主账号或具备云开发权限的子用户），即可在该账号下创建多个环境。每个租户对应一个环境，所有环境的资源与计费均归属该账号，便于您统一管理、统一出账。环境个数受账号配额限制，创建前可通过 API 查询环境个数上限；如需调整上限，可联系我们。

账号、环境与资源层级关系如下：

创建环境与计费​

为新租户创建环境，并管理其计费与配额。

操作步骤​

第一步：确认前置条件

创建前需通过以下接口确认账号状态与可用资源：

第二步：调用 CreateEnv 创建环境

调用 CreateEnv 接口，接口会自动下单并扣款。关键参数：

参数说明
PackageId套餐 ID，如 baas_personal；可通过 DescribeBaasPackageList 获取
Alias环境别名
Resources本次一并开通的资源类型，见下表
Period购买时长（月，默认 1）
Tags环境标签，用于权限隔离与资源分组；建议按租户 ID、业务线打标

Resources 可选值：

取值说明
flexdb文档型数据库（NoSQL），兼容 MongoDB 风格 API
storage对象存储（云存储）
function云函数（含 HTTP 云函数）

按业务需要从上述类型中选择；其余资源（如 MySQL）可在环境创建后按需开通。

第三步：等待发货并确认状态

环境发货为异步行为，调用 DescribeEnvs 轮询，直至环境状态变为可用。确认后可进一步查询用量与计费：

配额注意事项：COS 资源和云函数（非上海地域）均存在账号级或地域级配额上限；计划批量创建大量环境时，建议提前与云开发团队进行配额评估。

环境生命周期 API 参考​

为租户部署后端服务​

请求经 HTTP 访问服务 统一入口，按路由转发至对应云函数。支持 REST API、WebSocket 长连接，以及容器镜像部署。

从获取环境信息到对外可访问的完整调用流程：

操作步骤​

第一步：获取环境与日志配置

调用 DescribeEnvs，从 EnvInfo.LogServices[0] 取出 LogsetId / TopicId，后续创建函数时作为 ClsLogsetId / ClsTopicId 传入，用于日志投递。

第二步：打包并上传代码

将函数目录打包为 ZIP 并 Base64 编码，上限 50 MB。超过时需先上传至 COS，再通过 CosBucketName / CosObjectName / CosBucketRegion 引用（桶名不含 -appid 后缀，路径以 / 开头）。

第三步：创建或更新函数

调用 CreateFunction 或 UpdateFunctionCode。必填参数：Type: 'HTTP'、Namespace（云开发环境 ID）、Handler。WebSocket 函数额外需要 ProtocolType: 'WS'，详见 WebSocket 函数。

第四步：等待函数就绪

轮询 ListFunctions 直至 Status = Active。

第五步：配置 HTTP 访问服务路由

调用 CreateCloudBaseGWAPI，关键参数：EnableUnion: true、Path、ServiceId（环境 ID）、Type: 6、Name（函数名）、AuthSwitch: 2（关闭鉴权）、PathTransmission: 2（透传路径）、EnableRegion: true、Domain。

第六步：等待服务就绪

轮询 DescribeCloudBaseGWAPI 直至 APISet[0].UnionStatus = 1，即可获得对外访问地址。

（可选）绑定自定义域名

调用 BindCloudBaseAccessDomain，传入 ServiceId（环境 ID）、Domain、BindFlag: 2；HTTPS 需传 CertId，证书需在 SSL 证书控制台 提前申请。若使用腾讯云 DNSPod 解析，可通过 DescribeRecordFilterList 查询 CNAME 是否存在，不存在则调用 CreateRecord 创建。

以上云 API 可通过 管理面 SDK commonService 统一发起；也可直接使用 腾讯云 SDK 3.0 调用云函数 API，支持 Python、Java、PHP、Go、Node.js、.NET、C++、Ruby 等多语言。

云函数 API 参考​

Namespace 传入云开发环境 ID，即可在对应环境下操作函数；完整参数见 云函数 API 概览。

WebSocket 函数​

WebSocket 函数在普通 HTTP 函数基础上，CreateFunction 需额外传入以下参数：

ProtocolType: 'WS',
ProtocolParams: {
  WSParams: {
    IdleTimeOut: 7200   // 连接空闲超时，10–7200 秒
  }
},
Timeout: 7200           // 函数超时，必须 >= IdleTimeOut，15–7200 秒

注意：函数超时时间必须 ≥ 空闲超时时间，否则创建会报错。

单实例多并发（WebSocket 推荐基于会话，普通 HTTP 推荐基于请求）：

InstanceConcurrencyConfig: {
  DynamicEnabled: 'FALSE',
  MaxConcurrency: 10,
  Type: 'Session-Based',        // WebSocket 用 Session-Based；HTTP 用 Request-Based
  SessionConfig: {
    SessionExpireTime: 7200,
    IdleSessionExpireTime: 3600,
    SessionDestroyStrategy: 'IdleDestroy',
    SessionKeyType: 'Header',
    SessionKey: 'x-ws-session'
  },
  InstanceIsolationEnabled: 'FALSE'
}

容器镜像部署​

镜像部署适合依赖复杂、体积大或需要自定义运行环境的场景。

前置条件：

  1. 授权镜像拉取：为云函数角色授权策略 QcloudAccessForSCFRoleInPullImage，一次性操作：点击授权
  2. 准备镜像仓库：在 腾讯云容器镜像服务 TCR 创建仓库；参考 获取访问凭证 和 推送镜像。
  3. 镜像要求：基于 Linux 的 amd64 镜像，容器内监听 9000 端口。

在 Apple Silicon Mac 或其他 ARM 架构机器上构建时，必须加 --platform linux/amd64，否则部署后函数会因架构不匹配无法启动：

docker build --platform linux/amd64 -t your-image-name .

部署时，CreateFunction 中用 Code.ImageConfig 替代 Code.ZipFile：

Code: {
  ImageConfig: {
    ImageType: 'personal',   // 个人版仓库
    ImageUri: 'ccr.ccs.tencentyun.com/your-ns/your-image:tag',
    // RegistryId: ''        // 企业版仓库需填
  }
}

参考：ImageConfig 参数说明

HTTP 访问服务 API 参考​

域名与安全域名​

为租户环境的静态托管或 HTTP 访问服务绑定自定义域名与证书；配置可发起云开发请求的前端安全域名白名单。

操作步骤​

第一步：申请 SSL 证书

绑定 HTTPS 域名前，需在 SSL 证书控制台 申请或上传证书，获取 CertId。

第二步：绑定自定义域名

根据用途选择对应接口：

第三步：配置 DNS CNAME

绑定完成后，在域名服务商处将自有域名以 CNAME 指向 CloudBase 提供的接入域名（形如 xxx.tcbaccess.tencentcloudbase.com）。若使用腾讯云 DNSPod，可通过 API 操作：

  1. 查询 CNAME 记录是否已存在：DescribeRecordFilterList
  2. 不存在时创建记录：CreateRecord，Value 填接入域名

域名绑定与 DNS 解析均完成后访问才生效。

第四步：配置安全域名（可选）

安全域名控制哪些前端域名可向云开发发起请求。为租户前端域名添加白名单：

域名 API 参考​

数据库​

每个环境内提供两类数据库能力，租户之间按环境隔离。

  • 文档型数据库（FlexDB / NoSQL）：按集合与文档存储，兼容 MongoDB 风格 API，支持集合 CRUD、索引管理。环境创建时在 Resources 中勾选 flexdb 即可开通。
  • 关系型数据库（MySQL）：支持标准 SQL 与 DDL，表结构管理；前端可通过 Web SDK 以 Supabase 风格 API 访问。
  • 权限与安全：支持数据库级 ACL 及表级安全规则，用于控制读写范围与行级访问。

文档型数据库​

操作步骤​

第一步：开通

环境创建时在 Resources 中传入 flexdb 即可一并开通，无需额外操作。

第二步：创建集合

调用 CreateTable 创建集合，传入 EnvId 和集合名。

第三步：管理索引与权限

  • 查询或修改集合索引：UpdateTable
  • 配置读写权限与安全规则，控制租户数据访问范围

文档型数据库 API 参考​

MySQL​

操作步骤​

第一步：开通 MySQL

调用 CreateMySQL 开通，接口为异步，通过以下接口轮询结果：

第二步：初始化表结构

开通完成后，通过 RunSql 执行建表、建索引等 DDL 语句。

第三步：配置账号与访问权限

MySQL API 参考​

生命周期管理（tcb.tencentcloudapi.com）：

账号管理（cynosdb.tencentcloudapi.com）：

连接与集群（cynosdb.tencentcloudapi.com）：

备份（cynosdb.tencentcloudapi.com）：

监控与日志​

按环境查看监控曲线与 HTTP 访问服务运行状态，并检索 CLS 日志，用于排障与用量分析。

操作步骤​

第一步：查询监控数据

根据需要选择粒度：

第二步：检索日志

调用 SearchClsLog，传入：

  • EnvId：环境 ID
  • 时间范围
  • QueryString：遵循 CLS 语法，如 module:database、src:app

单次最多返回 100 条，支持游标翻页（最多 10,000 条）。

监控与日志 API 参考​

开发与集成方式​

按您的技术栈与场景，可选用以下方式管理环境与资源：

方式适用场景文档
管理面 SDK（Node.js）自有系统或脚本中集成，推荐首选管理面 SDK 文档
管理面 API直接调用 REST API、与现有后端对接云开发 API 简介
MCP 工具AI Coding 平台（Cursor、Claude Code 等），由 AI Agent 调用 CloudBase 能力CloudBase MCP、Skills 使用

MCP 提供本地模式与托管模式两种连接方式，详见 连接方式说明：

本地模式（推荐）：MCP Server 在本机通过 npx 启动，功能最全（含文件上传、模板下载等依赖本地文件系统的能力），需要本机已安装 Node.js。

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {
        "CLOUDBASE_ENV_ID": "<env_id>",
        "TENCENTCLOUD_SECRETID": "<SecretId>",
        "TENCENTCLOUD_SECRETKEY": "<SecretKey>"
      }
    }
  }
}

托管模式：MCP Server 运行在腾讯云，IDE 通过 HTTP 连接，无需本地安装 Node.js，但不支持本地文件操作（如模板下载到本机）。

{
  "mcpServers": {
    "cloudbase": {
      "type": "http",
      "url": "https://tcb-api.cloud.tencent.com/mcp/v1?env_id=<env_id>",
      "headers": {
        "X-TencentCloud-SecretId": "<SecretId>",
        "X-TencentCloud-SecretKey": "<SecretKey>"
      }
    }
  }
}

托管模式支持通过 URL 参数 disable_plugins 禁用指定插件（如 &disable_plugins=rag&disable_plugins=env）；可用插件：env、database、functions、hosting、storage、setup、rag、cloudrun、gateway、security-rule、capi 等；完整工具列表见 MCP 工具文档。

建议的实现顺序​

  1. 环境创建与计费：完成单租户环境的创建与计费开通，并支持用量查询。
  2. 部署后端：部署 HTTP 云函数，对外提供 API 或 WebSocket 能力。
  3. HTTP 访问服务与域名：配置路由与自定义域名，实现对外暴露与访问控制。
  4. 数据库与权限：为租户开通数据库、建表，配置权限与安全规则。
  5. 监控与日志：通过监控曲线与 CLS 日志进行排障与用量分析。

术语说明​

术语说明
环境一个租户的一整套资源（数据库、云函数、HTTP 访问服务、静态托管等），通常一租户一环境。
HTTP 云函数按需执行的云函数，通过 HTTP 访问服务对外提供 URL，适合 REST API、轻量逻辑。
HTTP 访问服务统一的 HTTP 入口，将请求按路由转发到 HTTP 云函数（腾讯云文档中采用此称谓）。

参考资源​

官方文档

AI Coding / MCP

平台接入