自定义域名

管理云开发环境的自定义域名绑定及 HTTP 访问路由规则。通过 app.env 访问。

版本提示

自 v5.0.0 起新增此能力。v5.0.0 之前请使用 HTTP 网关（旧）。

概念说明

概念	说明
自定义域名	绑定到云开发 HTTP 网关的自定义域名，支持 HTTPS 证书配置
访问路由	在某个域名下配置路径到上游服务（云函数/云托管/静态托管）的映射规则
AccessType	域名接入方式：`DIRECT`（直连）/ `CDN`（云开发 CDN）/ `CUSTOM`（自定义 CDN/WAF）/ `EO`（云开发 EdgeOne）
Protocol	HTTPS 协议策略：`HTTP_AND_HTTPS` / `HTTP_TO_HTTPS`（强制跳转）/ `HTTPS_TO_HTTP`
UpstreamResourceType	路由上游类型：`SCF`（云函数）/ `CBR`（云托管）/ `STATIC_STORE`（静态托管）/ `WEB_SCF`（Web 云函数）

describeHttpServiceRoute

1. 接口描述

接口功能：查询环境下的域名与访问路由列表，支持多维度过滤

接口声明：app.env.describeHttpServiceRoute(params): Promise<DescribeHttpServiceRouteRes>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Filters	否	HTTPServiceRouteFilter[]	过滤条件，支持 `Domain`、`Path`、`DomainType`、`UpstreamResourceType`
Offset	否	Number	分页偏移量，默认 0
Limit	否	Number	分页大小，默认 20，最大 1000

3. 返回结果

字段	类型	说明
Domains	HTTPServiceDomain[]	域名路由信息列表
OriginDomain	String	HTTP 网关源站域名（用于自定义 CDN/WAF 回源）
TotalCount	Number	域名总数
RequestId	String	请求唯一标识

HTTPServiceDomain

字段	类型	说明
Domain	String	域名
DomainType	String	域名类型
AccessType	String	接入方式：`DIRECT` / `CDN` / `CUSTOM` / `EO`
CertId	String	SSL 证书 ID
Protocol	String	协议类型
Cname	String	需配置的 CNAME 目标值
IsDefault	Boolean	是否是默认域名
Enable	Boolean	是否已开启
Status	String	状态：`PROCESSING` / `FAIL` / `SUCCESS`
DNSStatus	String	DNS 解析状态：`OK` / `INVALID`
Routes	HTTPServiceRoute[]	该域名下的路由列表
CreateTime	String	创建时间
UpdateTime	String	更新时间

4. 示例代码

const CloudBase = require('@cloudbase/manager-node')
const app = new CloudBase({ secretId: 'Your SecretId', secretKey: 'Your SecretKey', envId: 'your-env-id' })

async function test() {
  const { Domains, TotalCount } = await app.env.describeHttpServiceRoute({
    EnvId: 'your-env-id',
    Limit: 20
  })
  console.log(`共 ${TotalCount} 个域名`)
  Domains.forEach(d => console.log(d.Domain, d.Status, d.DNSStatus))
}

test()

bindCustomDomain

1. 接口描述

接口功能：绑定自定义域名到 HTTP 网关，支持配置 HTTPS 证书和接入方式

接口声明：app.env.bindCustomDomain(params): Promise<BindCustomDomainRes>

调用建议

建议先调用 verifyHttpServiceRoute 进行归属权与冲突预检，通过后再执行域名绑定。

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	BindCustomDomainDomainParam	域名配置，见下方说明

BindCustomDomainDomainParam

字段	必填	类型	说明
Domain	是	String	域名，全局唯一
CertId	是	String	SSL 证书 ID（腾讯云 SSL 平台）
AccessType	否	String	接入方式：`DIRECT`（默认）/ `CDN` / `CUSTOM` / `EO`
Protocol	否	String	协议策略：默认 `HTTP_AND_HTTPS`
Enable	否	Boolean	是否立即开启，默认 `true`
CustomCname	否	String	自定义 CDN/WAF 的回源 CNAME（`AccessType=CUSTOM` 时填写）

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识

4. 示例代码

async function test() {
  await app.env.bindCustomDomain({
    EnvId: 'your-env-id',
    Domain: {
      Domain: 'api.example.com',
      CertId: 'your-cert-id',
      AccessType: 'DIRECT',
      Protocol: 'HTTP_TO_HTTPS'
    }
  })
  console.log('域名绑定成功，请前往 DNS 服务商配置 CNAME 解析')
}

test()

deleteCustomDomain

1. 接口描述

接口功能：删除自定义域名。域名下存在路由绑定时会抛出错误，需先删除路由

接口声明：app.env.deleteCustomDomain(params): Promise<DeleteCustomDomainRes>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	String	要删除的域名

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识

verifyHttpServiceRoute

1. 接口描述

接口功能：对待创建/修改的域名路由配置进行只读预检，不会创建或修改任何资源

接口声明：app.env.verifyHttpServiceRoute(params): Promise<VerifyHttpServiceRouteRes>

版本提示

自 v5.8.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	HTTPServiceDomainParam	域名及路由配置，见下方说明

HTTPServiceDomainParam

字段	必填	类型	说明
Domain	是	String	域名（全局唯一）
AccessType	否	String	绑定类型：`DIRECT` / `CDN` / `CUSTOM` / `EO`
CertId	否	String	当前账号下 SSL 平台证书 ID
Protocol	否	String	协议策略：`HTTP` / `HTTPS` / `HTTP_AND_HTTPS` / `HTTP_TO_HTTPS` / `HTTPS_TO_HTTP`
CustomCname	否	String	自定义 CNAME，仅 `AccessType=CUSTOM` 时使用
Enable	否	Boolean	域名开启状态，不传默认开启
Routes	否	HTTPServiceRouteParam[]	路由列表，最多 20 条
Extension	否	HTTPServiceExtension	域名扩展配置

HTTPServiceRouteParam（单条路由）

字段	必填	类型	说明
Path	是	String	路由路径，如 `/api`
UpstreamResourceType	否	String	上游类型：`SCF` / `CBR` / `STATIC_STORE` / `WEB_SCF` / `LH` / `STORAGE`（创建时必填，修改时可选）
UpstreamResourceName	否	String	上游服务名称（创建时必填，修改时可选；`STATIC_STORE` / `STORAGE` 可不填）
PathRewrite	否	HTTPServicePathRewrite	路径重写配置
EnableSafeDomain	否	Boolean	是否启用安全域名，默认 `true`
EnableAuth	否	Boolean	是否启用身份认证，默认 `false`
EnablePathTransmission	否	Boolean	是否路径透传，默认 `false`
QPSPolicy	否	HTTPServiceRouteQPSPolicy	QPS 限频策略
Extension	否	HTTPServiceExtension	路由扩展配置（包含 headers 处理等）
Enable	否	Boolean	是否开启路由

HTTPServicePathRewrite

字段	必填	类型	说明
Prefix	否	String	路径前缀重写。与 `StaticStorePrefix` 二选一
StaticStorePrefix	否	String	静态托管路径前缀重写。与 `Prefix` 二选一

HTTPServiceRouteQPSPolicy

字段	必填	类型	说明
QPSTotal	否	Number	全局 QPS 值（每秒请求次数）
QPSPerClient	否	HTTPServiceQPSPerClient	客户端限频配置

HTTPServiceQPSPerClient

字段	必填	类型	说明
LimitBy	否	String	客户端维度：`UserID` / `ClientIP`
LimitValue	否	Number	客户端限频值（每秒请求次数）

HTTPServiceExtension

字段	必填	类型	说明
HeadersHandler	否	HTTPServiceHeadersHandler	headers 处理配置

HTTPServiceHeadersHandler

字段	必填	类型	说明
RequestHeadersToAdd	否	HTTPServiceHeaderToAdd[]	要添加的请求头列表
RequestHeadersToRemove	否	String[]	要删除的请求头 key 列表
ResponseHeadersToAdd	否	HTTPServiceHeaderToAdd[]	要添加的响应头列表
ResponseHeadersToRemove	否	String[]	要删除的响应头 key 列表

HTTPServiceHeaderToAdd

字段	必填	类型	说明
Key	否	String	要添加的头部 key
Value	否	String	要添加的头部值
Action	否	String	添加行为：`APPEND_IF_EXISTS_OR_ADD` / `ADD_IF_ABSENT` / `OVERWRITE_IF_EXISTS_OR_ADD` / `OVERWRITE_IF_EXISTS`

3. 返回结果

字段	类型	说明
Passed	Boolean	所有启用检查项均通过时为 `true`
Ownership	VerifyHttpServiceRouteCheckItem	域名归属权校验结果
Cert	VerifyHttpServiceRouteCheckItem	证书校验结果
Quota	VerifyHttpServiceRouteCheckItem	域名/路径配额校验结果
RouteConflict	VerifyHttpServiceRouteCheckItem	同域名下路由冲突校验结果
DomainConflict	VerifyHttpServiceRouteCheckItem	域名占用冲突校验结果
InternalAccount	VerifyHttpServiceRouteCheckItem	内部域名与账号校验结果
Blacklist	VerifyHttpServiceRouteCheckItem	域名黑名单校验结果
CDNResource	VerifyHttpServiceRouteCheckItem	CDN 资源校验结果
EO	VerifyHttpServiceRouteCheckItem	EdgeOne 预检结果
RequestId	String	请求唯一标识

VerifyHttpServiceRouteCheckItem 结构：

字段	类型	说明
Status	String	检查状态：`PASS` / `SKIPPED` / `FAIL`
Code	String	失败原因码，仅 `FAIL` 时返回
Message	String	结果详情或跳过原因
OwnershipVerification	Object	归属权验证指引（如 DNS 记录/文件校验信息）

4. 示例代码

建议在创建或修改路由前先调用 verifyHttpServiceRoute。若返回 Passed=true，再继续绑定域名与创建路由。

async function test() {
  const verifyRes = await app.env.verifyHttpServiceRoute({
    EnvId: 'your-env-id',
    Domain: {
      Domain: 'api.example.com',
      CertId: 'your-cert-id'
    }
  })

  if (!verifyRes.Passed) {
    console.log('预检未通过，请根据返回结果完成归属权校验或修复冲突后再重试')
    console.log(verifyRes.Ownership, verifyRes.RouteConflict, verifyRes.DomainConflict)
    return
  }

  console.log('预检通过，可继续 bindCustomDomain / createHttpServiceRoute')
}

test()

createHttpServiceRoute

1. 接口描述

接口功能：在指定域名下创建访问路由，将路径映射到云函数、云托管或静态托管等上游服务

接口声明：app.env.createHttpServiceRoute(params): Promise<CreateHttpServiceRouteRes>

调用建议

建议先调用 verifyHttpServiceRoute 完成预检，确认 Passed=true 后再创建路由。

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	HTTPServiceDomainParam	域名及路由配置，见下方说明

HTTPServiceDomainParam

字段	必填	类型	说明
Domain	是	String	域名（全局唯一）
AccessType	否	String	绑定类型：`DIRECT` / `CDN` / `CUSTOM` / `EO`
CertId	否	String	当前账号下 SSL 平台证书 ID
Protocol	否	String	协议策略：`HTTP` / `HTTPS` / `HTTP_AND_HTTPS` / `HTTP_TO_HTTPS` / `HTTPS_TO_HTTP`
CustomCname	否	String	自定义 CNAME，仅 `AccessType=CUSTOM` 时使用
Enable	否	Boolean	域名开启状态，不传默认开启
Routes	否	HTTPServiceRouteParam[]	路由列表，最多 20 条
Extension	否	HTTPServiceExtension	域名扩展配置

HTTPServiceRouteParam（单条路由）

字段	必填	类型	说明
Path	是	String	路由路径，如 `/api`
UpstreamResourceType	否	String	上游类型：`SCF` / `CBR` / `STATIC_STORE` / `WEB_SCF` / `LH` / `STORAGE`（创建时必填，修改时可选）
UpstreamResourceName	否	String	上游服务名称（创建时必填，修改时可选；`STATIC_STORE` / `STORAGE` 可不填）
PathRewrite	否	HTTPServicePathRewrite	路径重写配置
EnableSafeDomain	否	Boolean	是否启用安全域名，默认 `true`
EnableAuth	否	Boolean	是否启用身份认证，默认 `false`
EnablePathTransmission	否	Boolean	是否路径透传，默认 `false`
QPSPolicy	否	HTTPServiceRouteQPSPolicy	QPS 限频策略
Extension	否	HTTPServiceExtension	路由扩展配置（包含 headers 处理等）
Enable	否	Boolean	是否开启路由

PathRewrite / EnableAuth / EnablePathTransmission / QPSPolicy 四个字段的语义与 CLI 网关配置一致，字段权威定义见配置文件-网关。Manager SDK 使用帕斯卡命名（如 EnableAuth），与 cloudbaserc.json 的小驼峰命名（enableAuth）一一对应。

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识

4. 示例代码

async function test() {
  // 在已绑定的域名下创建路由：将 /api 映射到云函数 my-function
  await app.env.createHttpServiceRoute({
    EnvId: 'your-env-id',
    Domain: {
      Domain: 'api.example.com',
      Routes: [
        {
          Path: '/api',
          UpstreamResourceType: 'SCF',
          UpstreamResourceName: 'my-function',
          EnableAuth: false,
          Enable: true
        }
      ]
    }
  })
  console.log('路由创建成功')
}

test()

modifyHttpServiceRoute

1. 接口描述

接口功能：修改指定域名下的访问路由配置

接口声明：app.env.modifyHttpServiceRoute(params): Promise<ModifyHttpServiceRouteRes>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

与 createHttpServiceRoute 相同，参见上方说明。

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识

deleteHttpServiceRoute

1. 接口描述

接口功能：删除指定域名下的访问路由。不传 Paths 时删除该域名下的全部路由

接口声明：app.env.deleteHttpServiceRoute(params): Promise<DeleteHttpServiceRouteRes>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	String	域名
Paths	否	String[]	要删除的路由路径列表；不传则删除该域名下全部路由

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识

4. 示例代码

async function test() {
  // 删除 /api 路由
  await app.env.deleteHttpServiceRoute({
    EnvId: 'your-env-id',
    Domain: 'api.example.com',
    Paths: ['/api']
  })

  // 删除域名下全部路由
  await app.env.deleteHttpServiceRoute({
    EnvId: 'your-env-id',
    Domain: 'api.example.com'
  })
}

test()

purgeHttpServiceCache

1. 接口描述

接口功能：刷新 HTTP 访问服务域名缓存，支持 CDN 和 EdgeOne（EO）两种缓存类型。刷新缓存后会生成任务 ID，可通过 describeHttpServiceCachePurgeTask 查询任务进度和详细信息。

接口声明：app.env.purgeHttpServiceCache(params): Promise<PurgeHttpServiceCacheRes>

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	String	HTTP 访问服务域名
CacheType	是	String	缓存类型：`CDN`（云开发 CDN）/ `EO`（EdgeOne）
PurgeType	是	String	刷新粒度：`PURGE_URL`（URL，需含协议）/ `PURGE_PREFIX`（目录，仅 EO）/ `PURGE_HOST`（域名，仅 EO）。CDN 仅支持 `PURGE_URL`
Targets	是	String[]	刷新目标列表，语义随 `PurgeType` 变化

3. 返回结果

字段	类型	说明
CacheType	String	缓存类型：`CDN` / `EO`
TaskId	String	刷新任务 ID，可通过 `describeHttpServiceCachePurgeTask` 查询进度
RequestId	String	请求唯一标识

4. 示例代码

async function test() {
  // 刷新 CDN 域名的 URL 缓存
  const { TaskId } = await app.env.purgeHttpServiceCache({
    EnvId: 'your-env-id',
    Domain: 'api.example.com',
    CacheType: 'CDN',
    PurgeType: 'PURGE_URL',
    Targets: ['https://api.example.com/index.html']
  })
  console.log(`已提交刷新任务：${TaskId}`)

  // 刷新 EO 域名的目录缓存（PURGE_PREFIX 仅 EO 支持）
  await app.env.purgeHttpServiceCache({
    EnvId: 'your-env-id',
    Domain: 'static.example.com',
    CacheType: 'EO',
    PurgeType: 'PURGE_PREFIX',
    Targets: ['https://static.example.com/assets/']
  })
}

test()

describeHttpServiceCachePurgeTask

1. 接口描述

接口功能：查询 HTTP 访问服务域名缓存刷新任务详情。传入任务 ID 查询单个任务状态、时间、缓存类型等信息，不传则查询历史任务记录。

接口声明：app.env.describeHttpServiceCachePurgeTask(params): Promise<DescribeHttpServiceCachePurgeTaskRes>

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	String	HTTP 访问服务域名
CacheType	是	String	缓存类型：`CDN` / `EO`
TaskId	否	String	任务 ID，由 `purgeHttpServiceCache` 返回；不传时查询历史任务记录
PurgeType	否	String	按刷新粒度过滤：`PURGE_URL` / `PURGE_PREFIX` / `PURGE_HOST`
StartTime	否	String	查询开始时间，ISO8601 格式。`TaskId` 为空时默认 7 天前
EndTime	否	String	查询结束时间，ISO8601 格式。`TaskId` 为空时默认当前时间
Offset	否	Number	分页偏移量，默认 0
Limit	否	Number	分页大小，默认 20，最大 1000

3. 返回结果

字段	类型	说明
Tasks	HTTPServiceCachePurgeTask[]	任务列表
TotalCount	Number	任务总数，用于判断是否已拉取全部数据
RequestId	String	请求唯一标识

HTTPServiceCachePurgeTask

字段	类型	说明
TaskId	String	任务 ID
CacheType	String	缓存类型：`CDN` / `EO`
Status	String	任务状态：`PROCESSING`（处理中）/ `SUCCESS`（成功）/ `FAILED`（失败）/ `TIMEOUT`（超时）/ `CANCELED`（取消）
PurgeType	String	刷新类型：`PURGE_URL` / `PURGE_PREFIX` / `PURGE_HOST`
Method	String	刷新方法：`INVALIDATE`（仅刷新有更新的资源）/ `DELETE`（无论是否更新都刷新）
Targets	String[]	刷新目标列表
FailReason	String	失败原因，任务失败时返回
CreateTime	String	任务创建时间，ISO8601 格式（UTC+0）
UpdateTime	String	任务更新时间，ISO8601 格式（UTC+0）

4. 示例代码

async function test() {
  // 查询单个任务进度
  const { Tasks } = await app.env.describeHttpServiceCachePurgeTask({
    EnvId: 'your-env-id',
    Domain: 'api.example.com',
    CacheType: 'CDN',
    TaskId: 'your-task-id'
  })
  const task = Tasks[0]
  console.log(`任务状态：${task.Status}，失败原因：${task.FailReason || '-'}`)

  // 查询 EO 域名的目录刷新历史
  const history = await app.env.describeHttpServiceCachePurgeTask({
    EnvId: 'your-env-id',
    Domain: 'static.example.com',
    CacheType: 'EO',
    PurgeType: 'PURGE_PREFIX',
    Limit: 20
  })
  console.log(`共 ${history.TotalCount} 条历史记录`)
}

test()

概念说明​

describeHttpServiceRoute​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

bindCustomDomain​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

deleteCustomDomain​

1. 接口描述​

2. 输入参数​

3. 返回结果​

verifyHttpServiceRoute​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

createHttpServiceRoute​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

modifyHttpServiceRoute​

1. 接口描述​

2. 输入参数​

3. 返回结果​

deleteHttpServiceRoute​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

purgeHttpServiceCache​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

describeHttpServiceCachePurgeTask​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

概念说明

describeHttpServiceRoute

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

bindCustomDomain

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

deleteCustomDomain

1. 接口描述

2. 输入参数

3. 返回结果

verifyHttpServiceRoute

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

createHttpServiceRoute

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

modifyHttpServiceRoute

1. 接口描述

2. 输入参数

3. 返回结果

deleteHttpServiceRoute

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

purgeHttpServiceCache

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

describeHttpServiceCachePurgeTask

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码