CDN > API 文档 > 域名配置

域名配置

最近更新时间: 2026-05-21 09:21:16

1. 快速查阅区

1.1 核心接口概览

接口功能	请求方法	接口路径	核心参数	成功响应
修改加速区域	PUT	`/domain/<Name>/geocover`	geoCover	`{"code":200}`
修改源站配置	PUT	`/domain/<Name>/source`	sourceType,sourceQiniuBucket	`{"code":200}`
修改 Range 回源	PUT	`/domain/<Name>/range`	enable	`{"code":200}`
修改缓存规则	PUT	`/domain/<Name>/cache`	cacheControls	`{"code":200}`
修改响应头	PUT	`/domain/<Name>/respheader`	responseHeaderControls	`{"code":200}`
开启 HTTPS	PUT	`/domain/<Name>/sslize`	certId,forceHttps,http2Enable	`{"code":200}`
修改 HTTPS 配置	PUT	`/domain/<Name>/httpsconf`	certId,forceHttps,http2Enable	`{"code":200}`
配置 Referer 防盗链	PUT	`/domain/<Name>/referer`	refererType,refererValues	`{"code":200}`
配置 IP 黑白名单	PUT	`/domain/<Name>/ipacl`	ipACLType,ipACLValues	`{"code":200}`
配置 UA 黑白名单	PUT	`/domain/<Name>/uaacl`	ruleType,userAgent	`{"code":200}`
配置时间戳防盗链	PUT	`/domain/<Name>/timeacl`	enable,timeACLKeys,checkUrl	`{"code":200}`
配置回源鉴权	PUT	`/domain/<Name>/bsauth`	enable,method,userAuthUrl	`{"code":200}`

注：<Name>为加速服务域名

1.2 核心约束

请求域名: api.qiniu.com
鉴权方式: Qiniu 鉴权（详见鉴权指南）
QPS限制: 10 QPS
生效时间: 所有配置修改需要 5-10 分钟生效

2. 详细接口说明

2.1 修改加速区域

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/geocover
生效时间: 5-10 分钟
前置条件: geoCover 为 china 和 global 时域名需在中国大陆已备案

请求参数

参数名	类型	必填	说明	示例值
geoCover	string	是	加速区域	`china(中国大陆)` / `foreign(海外)` / `global(全球)`

请求示例

curl -X PUT 'https://api.qiniu.com/domain/test.example.com/geocover' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"geoCover":"global"}'

2.2 修改源站配置

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/source

请求参数

参数名	类型	必填	说明
sourceType	string	是	源站类型: `domain`(域名)/`ip`(ip地址)/`qiniuBucket`(七牛云存储，备注：不支持平台是动态加速)/`advanced`(高级)
sourceHost	string	否	回源Host, 普通域名默认`SourceHost`为域名本身, 泛域名默认`SourceHost`为用户请求时的域名
sourceIPs	[]string	否	回源ip, sourceType为ip时sourceIPs必填
sourceDomain	string	否	回源域名, sourceType为domain时此字段必填
sourceQiniuBucket	string	否	回源的七牛云存储的bucket名称, sourceType为qiniuBucket时此字段必填
sourceURLScheme	string	否	回源协议,可选值: `http/https`, 回源七牛bucket时本值无效,默认不填是follow请求协议
advancedSources	array	否	高级回源配置
addr	string	否	高级回源的回源地址, 可以是IP或者域名; 如需指定端口, 可直接拼接在地址后面(示例: 1.1.1.1:8080), sourceType为`advanced`时advancedSources字段必填
weight	int	否	高级回源的回源addr权重, 0 ~ 100, 按照权重比例回源, sourceType为`advanced`时advancedSources字段必填
backup	bool	否	高级回源的回源addr是否为备源地址, sourceType为`advanced`时advancedSources字段必填
testURLPath	string	是	用于测试的URL Path, 检测源站是否可访问, 大小建议小于1KB, 采用静态资源, 并请不要删除, 后面域名任何配置更改都会测试该资源, 用以保证域名的访问性

回源配置示例 (七牛存储源):

{
  "sourceType": "qiniuBucket",
  "sourceQiniuBucket": "your-bucket-name",
  "testURLPath": "/1235.jpg"
}

回源配置示例 (域名源站):

{
  "sourceType": "domain",
  "sourceDomain": "origin.example.com",
  "sourceProtocol": "http",
  "testURLPath": "/1235.jpg"
}

回源配置示例 (IP源站):

{
  "sourceType": "ip",
  "sourceIPs": ["1.1.1.1","2.2.2.2"],
  "sourceProtocol": "http",
  "testURLPath": "/1235.jpg"
}

回源配置示例 (高级源站):

{
  "sourceType": "advanced",
  "sourceURLScheme": "http",
  "advancedSources": [
        {
            "addr": "1.1.1.1:8080",
            "weight": 1,
            "backup": false
        },
        {
            "addr": "2.2.2.2:8888",
            "weight": 2,
            "backup": true
        }
    ],
    "testURLPath": "/path/1235.jpg"
}

请求示例

curl -X PUT 'https://api.qiniu.com/domain/test.example.com/source' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"sourceType":"qiniuBucket","sourceQiniuBucket":"new-bucket","testURLPath":"/1235.jpg"}'

2.3 修改 Range 回源

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/range

请求参数

参数名	类型	必填	说明	示例值
enable	string	是	Range 回源开关	“on” / “off”

请求体示例:

{
    "enable": "off"
}

请求示例

curl -X PUT 'https://api.qiniu.com/domain/test.example.com/range' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"enable":"off"}'

响应示例

成功 (HTTP 200):

{
    "code": 200
}

失败 (无改动):

{
    "code": 400910,
    "error": "没有改动不能提交"
}

2.4 修改缓存规则

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/cache

请求参数

Body 直接传 cacheControls + ignoreParam，不包 cache 层。

cacheControls 数组中每个元素的字段:

参数名	类型	必填	说明	示例值
time	int	是	缓存时间，总时间不超 1 年，type=follow 时配 -1	2
timeunit	int	是	时间单位: 0(秒) / 1(分钟) / 2(小时) / 3(天) / 4(周) / 5(月) / 6(年)，type=follow 时配 0	3
type	string	是	缓存类型: `path` (路径) / `suffix` (后缀) / `all` (全局) / `follow` (遵循源站)	“all”
rule	string	是	匹配规则: path 以 / 开头，suffix 以 . 开头，all/follow 填 “*”	“*”

顶层参数:

参数名	类型	必填	说明	示例值
cacheControls	array	是	缓存规则数组	见下方示例
ignoreParam	bool	否	是否开启去问号缓存，默认 false	true
ignoreParams	[]string	否	忽略指定参数列表	[“type”,“key”]
includeParams	[]string	否	保留指定参数列表	[“sourcepath”,“taskid”]

修改缓存时若缺少 type=all 全局规则，服务端会自动追加默认全局兜底。

缓存规则配置示例:

{
    "cacheControls": [
        {
            "time": 1,
            "timeunit": 2,
            "type": "path",
            "rule": "/live"
        },
        {
            "time": 2,
            "timeunit": 3,
            "type": "suffix",
            "rule": ".jpg"
        },
        {
            "time": 3,
            "timeunit": 0,
            "type": "all",
            "rule": "*"
        }
    ],
    "ignoreParam": true,
    "ignoreParams": ["type","key"],
    "includeParams": ["sourcepath","taskid"]
}

请求示例

curl -X PUT 'https://api.qiniu.com/domain/test.example.com/cache' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"cacheControls":[{"time":1,"timeunit":2,"type":"path","rule":"/live"},{"time":2,"timeunit":3,"type":"suffix","rule":".jpg"},{"time":3,"timeunit":0,"type":"all","rule":"*"}],"ignoreParam":true,"ignoreParams": ["type","key"],"includeParams": ["sourcepath","taskid"]}'

响应示例

成功 (HTTP 200):

{
    "code": 200
}

失败 (用错字段名):

{
    "code": 400309,
    "error": "缓存规则未设置全局或者为遵循源站"
}

2.5 修改响应头

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/respheader

请求参数

参数名	类型	必填	说明	示例值
op	string	是	对响应头的进行操作的类型，可选"set",“del”，目前不支持"add"	set
key	string	是	匹配响应头的key,可选值：Content-Type,Cache-Control,Content-Disposition,Content-Language,Expires,Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-Control-Allow-Headers,Access-Control-Max-Age,Access-Control-Expose-Headers,Access-Control-Allow-Credentials	Cache-Control
value	string	是	响应头的value,在op为"set"时有效	max-age=3600

响应头配置示例:

{
  "responseHeaderControls": [
    {
      "op": "set",     
      "key": "Cache-Control",
      "value": "max-age=3600"
    },
    {
      "op": "set",
      "key": "Access-Control-Allow-Origin",
      "value": "*"
    }
  ]
}

2.6 开启 HTTPS

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/sslize
前置条件: 已上传有效的SSL证书

请求参数

参数名	类型	必填	说明	示例值
certId	string	是	证书id，从上传或者获取证书列表里拿到证书id	694d122c30a46002d17c981a
forceHttps	bool	是	是否强制https跳转	true
http2Enable	bool	是	http2功能是否启用，false为关闭，true为开启	true
tlsVersions	string	否	支持的tls版本	TLSv1.0/TLSv1.1/TLSv1.2/TLSv1.3

SSL配置示例:

{
   "certId": "your-cert-id",
   "forceHttps": true,
   "http2Enable": true,
   "tlsVersions": "TLSv1.0"
}

请求示例

curl -X PUT 'https://api.qiniu.com/domain/test.example.com/sslize' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"certId":"abcdef1234567890","forceHttps":true,"http2Enable":true,"tlsVersions":"TLSv1.0"}'

2.7 修改 HTTPS 配置

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/httpsconf

请求参数

参数名	类型	必填	说明	示例值
certId	string	是	证书ID	同升级HTTPS
forceHttps	bool	否	是否强制https跳转	false
http2Enable	bool	否	http2功能是否启用	false
tlsVersions	string	否	支持的tls版本	TLSv1.0/TLSv1.1/TLSv1.2/TLSv1.3

SSL证书修改示例:

{
    "certId": "update-cert-id",
    "forceHttps": true,
    "http2Enable": true,
    "tlsVersions": "TLSv1.0"
}

2.8 配置 Referer 防盗链

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/referer

请求参数

参数名	类型	必填	说明	示例值
refererType	string	是	Referer防盗链类型, (""代表关闭本功能, 此时请注意refererValues需要为空)	`black/white/""`
refererValues	array	是	Referer防盗链黑白名单, 支持泛域名和标准域名配置	`["*.example.com"]`
nullReferer	bool	否	Referer防盗链, 是否支持空referer, 不填为false	false

Referer防盗链配置示例:

{
    "refererType": "white",
    "refererValues": [
        "*.example.com",
        "www.trusted.com"
    ],
    "nullReferer": true
}

2.9 配置 IP 黑白名单

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/ipacl

请求参数

参数名	类型	必填	说明	示例值
ipACLType	string	是	ip黑白名单控制控制类型(""代表关闭本功能,此时请注意ipACLValues需要为空)	`black/white/""`
ipACLValues	array	是	ip黑白名单, 支持IP段和指定IP配置	`["127.0.0.1/24"]`

IP黑白名单配置示例:

{
    "ipACLType": "black",
    "ipACLValues": [
        "192.168.1.0/24",
        "172.168.2.50"
    ]
}

2.10 配置 UA 黑白名单

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/uaacl

请求参数

参数名	类型	必填	说明	示例值
enable	string	是	ua黑白名单开关	`on/off`
ruleType	string	是	ua黑白名单控制类型	`black/white`
userAgent	array	是	ua黑白名单	`["Mozilla/5.0 (Macintosh"]`

UA黑白名单配置示例:

{
	"enable": "on",
	"ruleType": "black",
	"userAgent":["Mozilla/5.0 (Macintosh"]
}

2.11 配置时间戳防盗链

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/timeacl
互斥配置: 不能与回源鉴权同时启用

请求参数

参数名	类型	必填	说明	示例值
enable	bool	是	时间戳防盗链的开关	true
timeACLKeys	array	否	时间戳防盗链的加密key列表,key字符长度区间为[24,40];enable为true时必填2个key,enable为false时不填	见下方说明
checkUrl	string	否	根据时间戳防盗链加密算法生成的url,timeACL为true时本项必填,用以验证是否真实了解该时间戳防盗链加密算法	https://test.example.com/test/test.jpg?sign=&t=

时间戳防盗链配置示例:

{
    "enable": true,
    "timeACLKeys": [
        "your-secret-key-1",
        "your-secret-key-2"
    ],
    "checkUrl": "https://test.example.com/test/test.jpg?sign=<SIGN>&t=<T>"
}

2.12 配置回源鉴权

基本信息

请求方法: PUT
接口地址: https://api.qiniu.com/domain/<Name>/bsauth

请求参数

参数名	类型	必填	说明
enable	bool	是	回源鉴权开关
method	string	是	回源鉴权 HTTP 方法: GET/POST/HEAD
timeLimit	int	是	鉴权超时时间 (ms)，100-10000
userAuthUrl	string	是	鉴权服务地址
successStatusCode	int	是	鉴权通过的 HTTP 状态码，100-10000
failureStatusCode	int	是	鉴权失败的 HTTP 状态码，100-10000
strict	bool	否	超时后是否严格判定为鉴权失败
isQiniuPrivate	bool	否	是否为七牛私有 bucket 鉴权
path	string	否	匹配回源鉴权的 path (暂不支持)
parameters	string	否	参与鉴权的 URL 参数
userAuthMatchRuleConf	object	否	鉴权对象匹配规则
userAuthReqConf	object	否	特殊鉴权参数 (body/header/urlquery)
userAuthContentType	string	否	MIME 类型: application/json 或 application/x-www-form-urlencoded

回源鉴权配置示例:

{
    "enable": true,
    "method": "GET",
    "timeLimit": 5000,
    "userAuthUrl": "https://auth.example.com/verify",
    "strict": false,
    "successStatusCode": 200,
    "failureStatusCode": 403
}

3. 常见问题

3.1 专属错误码

错误码	描述	解决方案
400108	覆盖冲突	加速区域未变更 (geocover 相同值重复提交)
400309	缓存规则未设置全局	cache 接口包了多余层或用错字段名
400910	没有改动不能提交	配置值与当前相同 (range/source 等)
400324	证书不存在/已过期	检查 certId 有效性，重新上传有效证书
400302	更改证书失败	域名未开启 HTTPS，需先 sslize
400916	http协议不允许降级	域名未开启 HTTPS，无需降级
500235	该域名未绑定证书	需先绑定证书再升级 HTTPS
400042	配置参数错误	检查缓存规则/防盗链格式符合平台要求
400520	不能同时设置时间戳防盗链和回源鉴权	两者互斥，只能启用其中一个
404001	域名不存在	确认域名已创建且状态为 online/processing

3.2 最佳实践

配置生效时间: 所有配置修改需要 5-10 分钟生效，避免频繁调用
增量修改: 可以只传需要修改的配置项，未传项保留原有配置

提示: 详细的鉴权签名生成方法请参考鉴权指南,错误码详细说明请参考公共错误码&通用约束。

以上内容是否对您有帮助？