跳到主要内容

平台接入云开发方案

CloudBase for Platform 是什么​

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

您能获得什么：用云开发为您的每个租户提供一个独立环境，每个环境内包含数据库、云函数、静态托管和统一的 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 长连接，以及容器镜像部署。

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

操作步骤​

第一步：创建日志配置

  1. 调用 CreateLogset 创建日志集，获取返回的 LogsetId
  2. 调用 CreateTopic 创建日志主题，传入上一步的 LogsetId，获取返回的 TopicId
  3. 创建日志角色（用于日志投递）：在 CAM 角色控制台 创建角色，选择腾讯云产品服务，角色载体选择 scf 和 cls，关联自定义策略（仅授予日志写入权限，防止跨环境日志越权），记录角色名称（如 SCF_CLSWriteOnly），后续在配置或函数创建时使用

后续创建函数时，将 LogsetId / TopicId 作为 ClsLogsetId / ClsTopicId 传入，并将角色名称作为 Role 传入。

第二步：打包并上传代码

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

第三步：创建或更新函数

调用 CreateFunction 或 UpdateFunctionCode。必填参数：Type: 'HTTP'、Namespace（云开发环境 ID）、Handler。同时传入第一步获取的日志配置：ClsLogsetId、ClsTopicId，以及日志角色名称 Role。WebSocket 函数额外需要 ProtocolType: 'WS'，详见 WebSocket 函数。

第四步：等待函数就绪

轮询 ListFunctions 直至 Status = Active。

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

调用 CreateHTTPServiceRoute。该接口要求传入 EnvId 与 Domain 对象；Domain 中包含域名配置与 Routes 路由规则。示例结构：

{
  "EnvId": "<env-id>",
  "Domain": {
    "Domain": "api.example.com",
    "AccessType": "DIRECT",
    "Protocol": "HTTP_AND_HTTPS",
    "CertId": "<cert-id>",
    "Enable": true,
    "Routes": [
      {
        "Path": "/api/v1",
        "UpstreamResourceType": "<upstream-resource-type>",
        "UpstreamResourceName": "<resource-name>",
        "EnableSafeDomain": false,
        "EnablePathTransmission": false,
        "Enable": true
      }
    ]
  }
}

注意：旧 GWAPI 里的 Type 数字类型（例如历史示例中的 6）在新接口中已经改为 UpstreamResourceType 枚举字段，不再直接写魔数；请按当前上游资源类型填写对应枚举值。官方当前示例里的云托管服务使用 "CBR"。

如仅需先创建域名信息，可只传 Domain 而不传 Routes。

第六步：确认路由已生效

调用 DescribeHTTPServiceRoute，传入 EnvId，并可结合 Filters 按 Domain、Path 精确查询。检查返回的 Domains[].Status 与 Domains[].DNSStatus：

  • Status = SUCCESS：配置已生效
  • DNSStatus = SUCCESS：DNS 已生效
  • Status = PROCESSING：仍需继续轮询

接口返回成功后，路由下发仍可能有短暂延迟，建议再通过 HTTP / HTTPS 实际探测一次。

（可选）增量维护路由

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

云函数 API 参考​

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

此外，调用 SCF 云函数接口时还需传入以下两个参数：

  • Stamp：固定值 "MINI_QCBASE"
  • Role：云函数执行角色名称
安全提示

若您是普通用户（单环境账户），可直接传入默认角色 TCB_QcsRole，无需额外配置。

若您是平台客户，通过环境划分管理多个小租户时，使用 TCB_QcsRole 存在跨环境越权风险，建议为每个环境创建独立的自定义 CAM 角色：

  1. 前往 CAM 角色控制台 创建角色；
  2. 角色载体选择「腾讯云产品服务」；
  3. 服务授权对象勾选 SCF（云函数） 和 CLS（日志服务）；
  4. 关联自定义策略（仅授予日志写入权限，防止跨环境日志越权）；
  5. 记录角色名称（例如 SCF_CLSWriteOnly），并将其作为 Role 参数的值传入。

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'
}

容器镜像部署​

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

前置条件：

  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 访问服务绑定自定义域名与证书；配置可发起云开发请求的前端安全域名白名单。

操作步骤​

第一步：申请 SSL 证书

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

第二步：绑定自定义域名

根据用途选择对应接口：

第三步：配置 DNS CNAME

创建 HTTP 访问服务域名后，可通过 DescribeHTTPServiceRoute 从返回的 Domains[].Cname 获取 CloudBase 提供的 CNAME 目标域名；静态托管则按对应接口返回结果处理。若使用腾讯云 DNSPod，可通过 API 操作：

  1. 查询 CNAME 记录是否已存在：DescribeRecordFilterList
  2. 不存在时创建记录：CreateRecord，Value 填上一步获取的 CNAME 目标

域名绑定与 DNS 解析均完成后，可继续轮询 Domains[].DNSStatus 直至 SUCCESS。

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

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

域名 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 日志，用于排障与用量分析。

操作步骤​

第一步：配置日志

检索日志前，需先完成日志配置，创建日志角色。若已配置可跳过此步骤，详见云函数部署 - 第一步：创建日志配置。

  1. 调用 CreateLogset 创建日志集，获取 LogsetId
  2. 调用 CreateTopic 创建日志主题，获取 TopicId
  3. 创建日志角色（用于日志投递）：在 CAM 角色控制台 创建角色，选择腾讯云产品服务，角色载体选择 scf 和 cls，关联自定义策略（仅授予日志写入权限，防止跨环境日志越权），记录角色名称（如 SCF_CLSWriteOnly），后续在配置或函数创建时使用
  4. 创建函数时传入 ClsLogsetId、ClsTopicId、Role

第二步：查询监控数据

根据需要选择粒度：

第三步：检索日志

调用 SearchLog，传入：

  • TopicId：创建函数时配置的日志主题 ID
  • 时间范围
  • Query：遵循 CLS 语法，如 SCF_FunctionName:函数名

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

监控与日志 API 参考​

日志角色权限与多租户隔离​

单租户场景：可以使用预置策略 QcloudCLSFullAccess，该策略授予 CLS 全部资源的读写权限。

多租户场景：预置策略 QcloudCLSFullAccess 不区分日志集或日志主题。在同一账号下管理多个租户环境时，任意环境的角色都能读写其他环境的日志，存在跨环境越权风险。

如需环境间日志隔离，应使用自定义策略：

方案一：共享角色 + 只写权限（推荐，平衡安全与管理成本）

所有环境共享一个角色，仅授予日志写入权限，防止跨环境读取日志内容：

{
  "version": "2.0",
  "statement": [
    {
      "effect": "allow",
      "action": ["cls:pushLog", "cls:UploadLog"],
      "resource": "*"
    },
    {
      "effect": "allow",
      "action": ["cls:DescribeTopics", "cls:DescribeLogsets"],
      "resource": "*"
    }
  ]
}

DescribeTopics 和 DescribeLogsets 为云函数部署时所需的校验权限，仅返回日志主题的元信息，不返回日志内容。

方案二：每环境独立角色 + 限定资源（最严格隔离）

为每个环境创建独立角色，策略中通过 资源六段式 限定到具体的 TopicId：

{
  "version": "2.0",
  "statement": [
    {
      "effect": "allow",
      "action": ["cls:pushLog", "cls:UploadLog"],
      "resource": "qcs::cls:<region>::topic/<该环境的TopicId>"
    },
    {
      "effect": "allow",
      "action": ["cls:DescribeTopics", "cls:DescribeLogsets"],
      "resource": "*"
    }
  ]
}
方案适用场景隔离粒度管理成本
QcloudCLSFullAccess单租户，或所有环境属于同一用户无隔离最低
共享角色 + 只写权限多租户，需防止跨环境日志读取防读不防写低
每环境独立角色 + 限定资源多租户，需严格环境隔离读写均隔离较高（可自动化）

开发与集成方式​

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

方式适用场景文档
管理面 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

平台接入