跳到主要内容

环境与资源管理

本文介绍如何通过腾讯云 API 管理云开发环境及其内部资源，包括环境创建与计费、云函数部署、域名配置、数据库管理以及监控与日志。

云开发管理 API 总览

所有云开发管理 API 均可通过 云开发 API 概览 查阅，支持 Python、Java、Go、Node.js、PHP、.NET、C++、Ruby 等多语言 SDK 接入。

创建环境与计费​

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

操作步骤​

第一步：确认前置条件

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

第二步：调用 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 参考​

大规模创建场景：环境池 API

如果你的平台需要为大量用户快速创建云开发环境（如 SaaS 多租户、C 端平台等场景），对环境创建的吞吐量和响应速度有较高要求，我们提供了环境池 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单租户，或所有环境属于同一用户无隔离最低
共享角色 + 只写权限多租户，需防止跨环境日志读取防读不防写低
每环境独立角色 + 限定资源多租户，需严格环境隔离读写均隔离较高（可自动化）