CDN > API 文档 > 域名配置

域名配置

最近更新时间: 2026-03-25 14:06:22

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}`
修改证书	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}`
配置时间戳防盗链	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

请求参数

参数名	类型	必填	说明	示例值
source	object	是	回源配置	见下方说明

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

{
  "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": "/3/"
}

请求示例

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

修改缓存时若缺少 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
}

请求示例

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}'

响应示例

成功 (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
tlsVersion	string	否	支持的tls版本	TLSv1.0/TLSv1.1/TLSv1.2/TLSv1.3

SSL配置示例:

{
  "ssl": {
    "certId": "your-cert-id",
    "forceHttps": true,
    "http2Enable": true
  }
}

请求示例

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 '{"ssl":{"certId":"abcdef1234567890","forceHttps":true,"http2Enable":true}}'

2.7 修改证书

基本信息

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

请求参数

参数名	类型	必填	说明	示例值
certId	string	是	证书ID	同升级HTTPS
forceHttps	bool	否	是否强制https跳转	false
http2Enable	bool	否	http2功能是否启用	false

SSL证书修改示例:

{
    "certId": "update-cert-id",
    "forceHttps": true,
    "http2Enable": true
}

2.8 配置 Referer 防盗链

基本信息

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

请求参数

参数名	类型	必填	说明	示例值
refererType	string	是	Referer防盗链类型	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黑白名单	`["127.0.0.1/24"]`

IP黑白名单配置示例:

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

2.10 配置时间戳防盗链

基本信息

请求方法: 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时本项必填，用以验证是否真实了解该时间戳防盗链加密算法

时间戳防盗链配置示例:

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

2.11 配置回源鉴权

基本信息

请求方法: 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 (暂不支持)
parameter	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 分钟生效，避免频繁调用
HTTPS配置: 开启 HTTPS 时，protocol 必须设为 https
缓存规则: ttl 单位为秒，支持按后缀、路径、文件类型配置
增量修改: 可以只传需要修改的配置项，未传项保留原有配置

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

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