跳到主要内容

自定义域名

CloudBase HTTP 网关默认提供自动生成的域名，您也可以将自定义域名绑定至 CloudBase HTTP 网关。

生产环境建议绑定已完成备案的自定义域名以获得完整的服务能力和稳定性保障。默认域名的相关限制与适用说明，请参阅 HTTP 网关概述 - 默认域名。

关于客户端源 IP​

如果您的业务要使用限频能力（如 环境QPS、资源限频），或需要对访问来源做判断，需要先明确 CloudBase 网关识别到的客户端源 IP 取值方式。

适用范围

以下规则适用于所有场景，包括通过 HTTP 网关配置的自定义域名，以及直接通过 SDK、HTTP API 或 CLI 接入自定义域名的方式。

云开发接入（HTTP 网关直连、边缘加速、存量 CDN）

网关取的是直连的客户端 IP，不接受由请求方通过 X-Forwarded-For 指定，客户端无法自行控制该取值。

自定义接入

回源到云开发网关之前存在自建 7 层代理（如反向代理、WAF、CDN、边缘加速等）时，需由该代理通过 X-Forwarded-For 将客户端源 IP 传递给云开发网关。网关取 X-Forwarded-For 的最后一段作为客户端源 IP（CloudBase HTTP 网关只信任其前一层代理设置的 XFF）；若代理未正确传递，相关资源限频策略可能无法按预期生效。

注意

只有 7 层代理（能解析并改写 HTTP 请求头）才能通过 X-Forwarded-For 传递客户端源 IP；4 层代理（如 TCP/L4 负载均衡）不解析 HTTP 协议，无法设置或透传 X-Forwarded-For，网关取到的仍会是代理的出口 IP。

前置准备​

在开始配置自定义域名前，请确保已完成以下准备工作：

环境要求

边缘加速需要标准版及以上套餐。边缘加速按资源点计费，若当前环境未处于资源点模式，需先进入 云开发控制台 → 套餐用量 将计费模式转换为资源点模式后方可开启边缘加速。

  1. 域名备案 准备 自定义域名，并完成 ICP 备案。

    提示

    也可直接使用云开发环境完成备案，前往 云开发平台 - 备案管理。备案资格与完整流程请参考 ICP 备案。

  2. SSL 证书 独立接入域名时，准备 SSL 证书，可在 SSL 证书控制台 上传或申请；选择「继承泛域名」时复用已接入泛域名的证书，无需重复配置。

域名归属权校验​

域名独立接入云开发网关时，需要通过域名归属权校验确认您确实拥有该域名，避免域名被他人误用或冒用接入，保障您的业务安全。选择「继承泛域名」时，复用已接入泛域名的校验结果，无需重复校验。

校验方式为在 DNS 服务商处添加一条 TXT 解析记录，具体记录值会在域名接入的操作过程中提供，请按页面指引添加即可。

泛域名接入时，其覆盖范围内的子域名无需逐个校验归属权：*.example.com 可免验证任意层级子域名（如 a.example.com、a.b.c.example.com），*.xxx.example.com 仅免验证一级子域名（如 a.xxx.example.com）。详见 泛域名接入 - 域名归属权验证规则。

添加域名时，页面会引导您完成 TXT 记录校验，例如：

绑定自定义域名页面指引
开启边缘加速的归属权校验

独立接入域名并首次开启 边缘加速 时，还需要验证 边缘加速域名归属权。这是边缘加速平台自身的要求，与云开发的首次域名归属权校验不通用，需按平台指引添加对应的 DNS TXT 记录完成校验。选择「继承泛域名」时复用已接入泛域名的校验结果。

开始接入​

  1. 进入云开发平台 - HTTP 网关
  2. 点击「添加域名」
  3. 填写自定义域名
  4. 选择接入方式；独立接入时配置 SSL 证书，继承泛域名时复用已有配置

添加自定义域名入口

提示

除了在 HTTP 网关统一管理域名外，您也可以在具体的 云函数 / 云托管 / 静态托管应用 详情页中，就地为该应用添加自定义域名。两种入口效果一致，HTTP 网关可查看并管理所有已添加的域名。

接入方式​

自定义域名支持以下三种接入方式：

  • 云开发接入：由云开发平台统一管理域名接入，可选择开启或关闭边缘加速
  • 继承泛域名：复用平台版或当前环境已接入的泛域名，继承其证书、解析与归属权校验结果，无需重复配置
  • 自定义接入：使用您自己的 CDN 或 WAF 服务接入

云开发接入​

云开发接入支持「开启边缘加速」和「不开启边缘加速」两种方式。

开启边缘加速​

开启边缘加速后，您的访问请求会通过边缘节点就近接入。可缓存的资源在命中缓存时由边缘节点直接返回，未命中时回源获取，从而降低访问延迟与源站压力。

边缘加速依托全球边缘节点，覆盖 70+ 国家与地区，海外用户也能就近接入。开启后将产生加速流量费用与加速请求次数两项费用，按访问来源大区计费。具体价格请参考 云开发计费文档。

加速特性​

默认启用，无需额外配置

特性对您的帮助
智能压缩默认开启 Brotli 和 Gzip，根据客户端支持情况返回压缩内容，减小传输体积、加快加载并节省流量
IPv6 访问支持 IPv6 客户端接入，兼容更多网络环境
WebSocket支持实时通信连接；边缘侧连接超时设置为 300 秒，源站与其他链路的超时限制仍需单独确认
TLS 1.2 / 1.3HTTPS 接入支持 TLS 1.2 和 TLS 1.3，不支持 TLS 1.0 / 1.1
OCSP Stapling在 TLS 握手中提供证书状态信息，减少客户端单独查询证书状态的开销
缓存隔离根据 Origin、Accept-Encoding 区分缓存响应，避免不同跨域来源或压缩版本的内容被错误复用
智能压缩的适用条件

客户端需通过 Accept-Encoding 声明支持 br 或 gzip，资源的 Content-Type 需属于支持类型（如 HTML、CSS、JavaScript、JSON），且文件大小为 256 B–30 MB。算法均可用时优先 Brotli，实际返回也取决于已有缓存版本。

源站已返回 Content-Encoding 时不重复压缩；源站使用 Transfer-Encoding: chunked 时，不在首次回源的同步传输过程中实时压缩，后续请求可基于已缓存内容进行压缩。压缩并非对所有资源、每次请求都生效。

按业务需要配置

特性能力说明
节点与浏览器缓存默认缓存跟随源站；可按请求特征配置不缓存、自定义时长或跟随源站，分别控制边缘节点与浏览器缓存，详见缓存配置
自定义缓存键可选择 URL 与查询参数如何参与缓存键，控制哪些请求共享缓存；签名 URL 的 sign、t 会保留用于缓存隔离，实际签名校验由云开发网关处理
Referer 防盗链支持 Referer 白名单或黑名单，不符合规则的请求在边缘节点返回 403，缓存命中时也会执行检查
协议控制支持 HTTP 与 HTTPS 同时接入、仅允许一种协议，或使用 301 将 HTTP / HTTPS 请求跳转到另一种协议
自定义错误页平台版可为支持的 4XX 错误配置自定义返回内容，统一错误场景下的用户体验，详见自定义错误页
跨域与源站配置

缓存隔离不等于跨域授权。跨域访问仍需正确配置跨域校验及源站响应头；开启边缘加速也不会解除源站的鉴权、请求大小或超时限制。

后续步骤​
  1. 完成边缘加速域名归属权校验：首次开启边缘加速时，需要验证边缘加速域名归属权，按指引添加对应的 DNS TXT 记录即可。
  1. 配置 CNAME 解析：域名接入状态正常后，前往 DNS 控制台 配置 CNAME 解析，CNAME 的值会在页面上提供。
说明

由于边缘加速平台的配置需要一定时间下发，验证边缘加速域名归属权后的处理状态约需 10-20 分钟，请耐心等待。

不开启边缘加速​

不开启边缘加速时，直接走云开发网关。

第 1 步：云开发平台添加自定义域名​

在 HTTP 网关 添加自定义域名并选择云开发接入（不开启边缘加速）

第 2 步：等待域名关联完成​

在云开发平台添加自定义域名后，需要等待域名关联完成，通常需要等待 3-5 分钟，域名关联成功后，复制 CNAME 值。

第 3 步：DNS 控制台并添加 CNAME 解析​

用步骤 2 中复制的 CNAME 值，前往域名 DNS 服务商添加 CNAME 记录，将请求切入 CDN，域名才能生效，前往 DNS 控制台，添加域名解析记录。

第 4 步：完成云开发接入​

返回云开发平台，检查自定义域名接入状态

说明

如果自定义域名接入状态未更新，可刷新网页再查看。

存量云开发 CDN 迁移到边缘加速​

说明

原「云开发 CDN」接入方式已不再支持。如果您之前使用的是云开发 CDN 接入的域名，建议迁移到云开发接入（开启边缘加速），借助边缘加速能力获得更好的访问体验。

  1. 在域名管理页面，找到原域名，点击「编辑」，将接入方式改为 云开发接入，并 开启边缘加速 后保存。
  2. 首次开启边缘加速，需要验证边缘加速域名归属权，操作过程中按指引添加对应的 DNS TXT 记录即可。
  3. 修改完接入方式，等状态正常后，前往 DNS 解析控制台，将域名 CNAME 指向新创建的 CNAME 值。

继承泛域名​

如果您的域名是已接入泛域名下的精准子域名（例如 *.example.com 下的 api.example.com），可选择「继承泛域名」。此方式可复用平台版或当前环境已接入泛域名的证书、DNS 解析配置与域名归属权校验结果，无需为精准子域名重复配置。

泛域名的接入方式请参阅泛域名接入；平台版介绍请参阅 CloudBase 平台版概述。

自定义接入​

CDN 接入​

第 1 步：云开发平台添加自定义域名​

在HTTP 网关添加自定义域名并选择自定义 CDN，并复制回源域名

第 2 步：添加 CDN 域名​

前往 CDN 控制台，点击「添加域名」。

第 3 步：CDN 域名配置​

1. 配置源站域名：添加域名配置，粘贴步骤 1 中复制的回源域名到源站域名地址中。

说明

请根据业务类型自主选择加速区域和加速类型。

2. 填写推荐配置：提升加速性能。

说明

若无需额外配置，该步可选择跳过。

3. 添加 CNAME 解析：复制 CDN 控制台中的 CNAME 值，前往 DNS 控制台添加 CNAME 类型解析。

说明

DNS 解析需要前往对应的域名服务商控制台添加 CNAME 解析记录。

4. 完成配置：完成自定义 CDN 配置

第 4 步：校验 CDN 域名接入​

添加 CNAME 记录后，通常需要等待 5-30 分钟让 DNS 解析生效。并返回云开发平台查看自定义 CDN 接入状态。您可以通过以下命令检查域名解析是否已生效：

nslookup 您的自定义域名

如果返回结果中显示了 CloudBase 提供的 CNAME 域名，则表示解析已生效。

WAF 接入​

WAF（Web 应用防火墙）接入流程与自定义 CDN 接入类似，区别在于：需要在 WAF 控制台完成源站配置后，将 WAF 分配的 CNAME 回填到云开发平台，再在 DNS 服务商处添加 CNAME 解析。

第 1 步：云开发平台添加自定义域名​

在 HTTP 网关 添加自定义域名并选择自定义 CDN，并复制回源域名。

第 2 步：添加 WAF 域名​

前往 Web 应用防火墙控制台，在「接入管理」中点击「添加域名」。

第 3 步：配置 WAF 源站域名​

在新添加的域名行点击「编辑」，将「源站地址」类型选择为「域名」，并把第 1 步中复制的云开发回源域名粘贴到源站地址中。

说明

源站域名示例：xxxxxx-1234567890.ap-shanghai.service.tcloudbase.com，请以控制台实际展示为准。

第 4 步：获取 WAF CNAME 并回填至云开发​
  1. 在 WAF 域名列表的「CNAME」列，复制 WAF 分配的 CNAME 值。
  1. 返回 HTTP 网关，在对应域名的「CNAME」输入框中，粘贴 WAF 分配的 CNAME 值并保存。
第 5 步：DNS 控制台添加 CNAME 解析​

将域名的 CNAME 解析指向 WAF 分配的 CNAME 值，前往 DNS 控制台 添加 CNAME 记录。

说明

DNS 解析需要前往您域名实际所在的 DNS 服务商控制台添加 CNAME 解析记录，腾讯云 DNS 添加方法可参考本文档末尾的「腾讯云 DNS 设置方法」。

第 6 步：校验 WAF 域名接入​

添加 CNAME 记录后，通常需要等待 5-30 分钟让 DNS 解析生效。返回云开发平台查看 WAF 域名接入状态。您可以通过以下命令检查域名解析是否已生效：

nslookup 您的自定义域名

如果返回结果中显示了 WAF 分配的 CNAME 域名，则表示解析已生效。

腾讯云 DNS 设置方法​

如果您的 DNS 服务商为腾讯云，可按以下步骤添加 CNAME 记录：

1. 进入域名解析

登录 域名服务控制台，在域名列表中找到目标域名，点击操作栏的「解析」。

2. 添加解析记录

在解析页面中，点击「添加记录」。

3. 配置解析记录

配置解析记录参数：

  • 主机记录：填写域名前缀（例如：@）
  • 记录类型：选择 CNAME
  • 记录值：填写 CNAME 值
  • 点击「保存」完成配置
提示

域名解析各种记录类型之间存在优先级差异。在主机记录相同的情况下，同一条线路的不同记录类型不能共存，否则会提示冲突。CNAME 记录与除 CNAME 记录以外的任何记录类型都冲突，需要先删除其他记录再进行配置。详情请参见 为什么添加解析记录的时候提示"记录有冲突"。

使用限制​

  • 每个 CloudBase 环境最多可绑定的自定义域名数量根据套餐不同有所差异，具体请参考 套餐配额与能力项说明
  • 自定义域名必须已完成 ICP 备案
  • 域名解析生效需要一定时间，请耐心等待