管理环境的资源

环境创建完成后，您需要通过腾讯云 API 管理环境内的资源，包括云函数部署、域名配置、数据库管理以及监控与日志。

环境的创建与计费开通请参考 开通并创建第一个环境。

云开发管理 API 总览

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

为租户部署后端服务

请求经 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 实际探测一次。

（可选）增量维护路由

• 修改已有域名或路由：调用 ModifyHTTPServiceRoute
• 删除指定 Path 或整个域名配置：调用 DeleteHTTPServiceRoute

以上云 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 参数的值传入。

• 获取函数列表：ListFunctions
• 创建函数：CreateFunction
• 更新函数代码：UpdateFunctionCode
• 更新函数配置：UpdateFunctionConfiguration
• 获取函数详情：GetFunction
• 删除函数：DeleteFunction
• 调用函数：Invoke
• 获取函数代码下载地址：GetFunctionAddress

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 网关路由：CreateHTTPServiceRoute
• 删除 HTTP 网关路由：DeleteHTTPServiceRoute
• 查询 HTTP 网关路由信息：DescribeHTTPServiceRoute
• 修改 HTTP 网关路由：ModifyHTTPServiceRoute

---

域名与安全域名

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

操作步骤

第一步：申请 SSL 证书

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

第二步：绑定自定义域名

根据用途选择对应接口：

• HTTP 网关域名：调用 CreateHTTPServiceRoute 创建域名与路由，至少传入 EnvId 与 Domain；如果只想先绑定域名，可仅创建域名信息，后续通过 ModifyHTTPServiceRoute 增量维护路由。
• 静态托管域名：调用 CreateHostingDomain，任务为异步，通过 DescribeHostingDomainTask 轮询完成状态。

第三步：配置 DNS CNAME

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

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

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

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

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

• 增加安全域名：CreateAuthDomain
• 获取安全域名列表：DescribeAuthDomains

域名 API 参考

• 创建 HTTP 网关域名 / 路由：CreateHTTPServiceRoute
• 修改 HTTP 网关域名 / 路由：ModifyHTTPServiceRoute
• 查询 HTTP 网关域名 / 路由：DescribeHTTPServiceRoute
• 删除 HTTP 网关域名 / 路由：DeleteHTTPServiceRoute
• 绑定静态托管域名：CreateHostingDomain
• 查询静态托管域名任务状态：DescribeHostingDomainTask
• 增加安全域名：CreateAuthDomain
• 获取安全域名列表：DescribeAuthDomains

---

数据库

平台集成方案采用 PostgreSQL 数据库（PG 模式）作为环境默认数据库，创建环境时在 Resources 中传入 postgresql 即自动启用，租户之间按环境隔离。

• PostgreSQL 数据库：完整 SQL 能力（表、视图、外键、索引、事务、存储过程等），基于 PostgREST 自动暴露 RESTful API，客户端可直连读写
• 权限模型：表级 GRANT + 行级 RLS Policy 双层权限，以 SQL 表达，支持按租户隔离数据行
• 其他数据库：如需 MySQL 等类型，可在环境创建后按需开通

PostgreSQL

操作步骤

第一步：开通

创建环境时在 Resources 中传入 postgresql 即可，环境自动以 PG 模式运行，PostgreSQL 实例自动启用，无需额外开通。详见 PG 模式概述。

第二步：建表与执行 SQL

通过 executePGSql（管理面 SDK）或 HTTP API 执行 SQL 语句 执行建表、DDL 与 DML：

await database.executePGSql({
  Sql: 'CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE)'
})

第三步：配置权限

• 表级权限：GRANT ... TO <role>，使用 anon / authenticated / service_role 三种内置角色
• 行级权限：RLS Policy，按租户隔离数据行
• 详见 PostgreSQL 数据库 - 数据权限管理

PostgreSQL API 参考

• 管理面执行 SQL：executePGSql
• HTTP 执行 SQL：执行 SQL 语句
• HTTP 数据操作：PostgREST 风格，见 PostgreSQL RESTful API
• 权限与数据安全：数据权限管理、RLS 权限模式库

MySQL

操作步骤

第一步：开通 MySQL

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

• 查询开通结果：DescribeCreateMySQLResult
• 查询任务状态：DescribeMySQLTaskStatus

第二步：初始化表结构

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

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

• 查询已有账号：DescribeAccounts
• 修改账号密码：ResetAccountPassword
• 修改账号权限（按租户隔离读写范围）：ModifyAccountPrivileges

MySQL API 参考

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

• 开通 MySQL：CreateMySQL
• 查询开通结果：DescribeCreateMySQLResult
• 查询任务状态：DescribeMySQLTaskStatus
• 查询集群信息：DescribeMySQLClusterDetail
• 执行 SQL 语句：RunSql
• 销毁 MySQL：DestroyMySQL

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

• 查询账号列表：DescribeAccounts
• 修改账号密码：ResetAccountPassword
• 修改账号权限：ModifyAccountPrivileges
• 修改账号配置：ModifyAccountParams

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

• 开通外网：OpenWan
• 关闭外网：CloseWan
• 查询集群参数：DescribeClusterParams
• 修改集群参数：ModifyClusterParam

备份（cynosdb.tencentcloudapi.com）：

• 创建手动备份：CreateBackup
• 删除手动备份：DeleteBackup
• 获取备份下载地址：DescribeBackupDownloadUrl

---

监控与日志

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

操作步骤

第一步：配置日志

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

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

第二步：查询监控数据

根据需要选择粒度：

• 环境级监控曲线（调用量、流量等）：DescribeCurveData
• 环境级监控指标数据：DescribeGraphData
• HTTP 网关监控：DescribeGatewayData

第三步：检索日志

调用 SearchLog，传入：

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

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

监控与日志 API 参考

• 查询环境监控曲线：DescribeCurveData
• 查询环境监控数据：DescribeGraphData
• 查询网关监控数据：DescribeGatewayData
• 搜索云函数日志：SearchLog

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

单租户场景：可以使用预置策略 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	单租户，或所有环境属于同一用户	无隔离	最低
共享角色 + 只写权限	多租户，需防止跨环境日志读取	防读不防写	低
每环境独立角色 + 限定资源	多租户，需严格环境隔离	读写均隔离	较高（可自动化）