CNAME 接入域名 cname-domains

仅管理员。用于生成 CNAME 接入名的根域,归属某个 DNS 服务商账号;支持整体更换到新根域并核对客户是否已改解析。

点击任一接口,右侧显示对应的调用示例。

DNS 与接入鉴权: 仅管理员15 个接口

鉴权

请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。

X-API-Key

鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。

约定

分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。

时间一律 RFC 3339(UTC);金额单位为分。

写操作成功回 200/201/204;重复提交按资源唯一键回 409。

GET/api/v2/cname-domains列出CNAME 接入域名

鉴权: 仅管理员

查询参数

字段类型说明
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
sortstring 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。
domainstring 只列根域包含该串的(部分匹配,不分大小写,首尾空格与结尾的点忽略)。
typestring 只列归属该服务商类型(如 aliyun)的。
dns_provider_idinteger 只列归属该账号的。
statusCnameDomainStatus 只列该状态的。
可选值 ["active","retiring"]
POST/api/v2/cname-domains创建CNAME 接入域名

鉴权: 仅管理员

请求体 application/json

字段类型说明
dns_provider_id必填integer 托管该根域的服务商账号 id。
domain必填string 小写根域,如 cdn.example.com。
expected_updated_atstring 乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。
expire_atstring 管理员手填的到期日 YYYY-MM-DD;留空时由每日任务向注册局自动获取(见 effective_expire_at)。
remarkstring 备注
statusCnameDomainStatus active 使用中;retiring 停用中(已更换走,不再给套餐选)。
可选值 ["active","retiring"]
GET/api/v2/cname-domains/options列出CNAME 接入域名选项

鉴权: 仅管理员

查询参数

字段类型说明
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
statusCnameDomainStatus 只列该状态的。
可选值 ["active","retiring"]
PUT/api/v2/cname-domains/status批量设置CNAME 接入域名状态

鉴权: 仅管理员

请求体 application/json

字段类型说明
ids必填integer[] 要设置状态的接入域名 id 列表。
status必填CnameDomainStatus active 使用中;retiring 停用中(已更换走,不再给套餐选)。
可选值 ["active","retiring"]
PUT/api/v2/cname-domains/{id}修改CNAME 接入域名

鉴权: 仅管理员

请求体 application/json

字段类型说明
dns_provider_id必填integer 托管该根域的服务商账号 id。
domain必填string 小写根域,如 cdn.example.com。
expected_updated_atstring 乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。
expire_atstring 管理员手填的到期日 YYYY-MM-DD;留空时由每日任务向注册局自动获取(见 effective_expire_at)。
remarkstring 备注
statusCnameDomainStatus active 使用中;retiring 停用中(已更换走,不再给套餐选)。
可选值 ["active","retiring"]
DELETE/api/v2/cname-domains/{id}删除CNAME 接入域名

鉴权: 仅管理员

查询参数

字段类型说明
local_onlyboolean 为 true 时只删本平台记录,不去服务商侧清该根域下的旧解析(面板「仅删除本地记录」)。
POST/api/v2/cname-domains/{id}/lines/refresh重新拉取域名线路

鉴权: 仅管理员

POST/api/v2/cname-domains/{id}/migrate整体更换CNAME 接入域名

鉴权: 仅管理员

请求体 application/json

字段类型说明
notifyboolean 是否给受影响客户发站内信。
默认 true
retireboolean 是否把旧域名置为停用中。
默认 true
target_id必填integer 目标根域 id。
GET/api/v2/cname-domains/{id}/switch-check查更换后的切换核对

鉴权: 仅管理员

查询参数

字段类型说明
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
stateCnameSwitchState 只列该核对状态的。
可选值 ["changed","unchanged","not_cname","failed","pending"]
qstring 模糊匹配客户名、网站域名或实际解析。
GET/api/v2/cname-domains/{id}/switch-check/export导出切换核对对照表

鉴权: 仅管理员

查询参数

字段类型说明
stateCnameSwitchState 只列该核对状态的。
可选值 ["changed","unchanged","not_cname","failed","pending"]
qstring 模糊匹配客户名、网站域名或实际解析。
POST/api/v2/cname-domains/{id}/switch-check/remind提醒未改的客户

鉴权: 仅管理员

POST/api/v2/cname-domains/{id}/switch-check/run立即核对

鉴权: 仅管理员

CNAME 接入域名对象

字段类型说明
actualstring 实际解析到的(CNAME 目标或 IP);查询失败时为原因(NXDOMAIN、Timeout…)。
changedinteger 重查后已改的行数。
check_rowsinteger 新建的核对行数(每个网站域名一行)。
checkedinteger 本次重查的行数。
checked_atstring 最近一次解析检查时间。
codestring 服务商版本代号;读不到为空。
created_atstring 创建时间
只读
dns_provider_idinteger 托管该根域的服务商账号 id。
domainstring 小写根域,如 cdn.example.com。
domainsLineOptionDomain[] 组内全部域名(主组或备用组绑定的)。
editionCnameEdition 域名在服务商处的版本与线路摘要(读不到版本的服务商只有 line_count 与 granularity)。
effective_expire_atstring 生效到期日 YYYY-MM-DD:手填优先,否则为注册局(RDAP/WHOIS)查到的值;都没有为 null。到期前 30/7/1 天与过期后各提醒管理员一次。
errstring 最近一次拉取失败的原因;最近一次成功为空串。
example_hostnamestring 一个现有接入名(不含根域),向导里拼新旧接入地址示例用。
expected_updated_atstring 乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。
expire_atstring 管理员手填的到期日 YYYY-MM-DD;留空时由每日任务向注册局自动获取(见 effective_expire_at)。
expire_check_errorstring 注册局自动查询到期日最近一次失败的原因;上次查到了、还没查过或已手填到期日为 null。
expire_fail_countinteger 自动查询到期日连续失败次数(查到即清零;已手填到期日为 0)。连续失败 7 次且仍没有到期日时给管理员发一次站内信。
expire_sourceCnameExpireSource 生效到期日来源:manual 手填;auto 注册局自动获取;none 没有到期日。
可选值 ["manual","auto","none"]
failedinteger 查询失败的行数。
fromstring 原根域。
granularitystring 粒度:province=有运营商×省,isp=只有运营商,default=只有默认,none=还没拉到线路。
可选值 ["province","isp","default","none"]
idinteger 记录 ID
只读
ids必填integer[] 要设置状态的接入域名 id 列表。
last_checked_atstring 该根域的核对行最近一次核对的时间;未更换或还没核对过为 null。
line_countinteger 线路条数(线路树节点总数,含默认线路);没拉到为 0。
line_taginteger 线路地区标签取自本根域的节点数(删除根域时标签一并清掉)。
messagedinteger 发了站内信的客户数。
min_ttlinteger TTL 下限(秒),0=未知。
namestring 版本显示名;读不到为空。
new_targetstring 切换后的 CNAME 目标。
nodesLineOptionNode[] 统一线路并集(不含 default 与专有线路)。
not_cnameinteger 非 CNAME 接入的行数。
notified_atstring 通知客户的时间。
notifyboolean 是否给受影响客户发站内信。
默认 true
old_targetstring 切换前的 CNAME 目标。
packageinteger 切走的套餐接入名数。
package_liststring[] 前 20 个引用本根域的用户套餐。
paidboolean 付费版(按服务商版本代号推断,读不到版本为 false)。
privateLinePrivateGroup[] 专有线路,按域名分组;没有专有线路的域名不列。
provider_namestring 归属账号名称。
provider_typestring 归属账号的服务商类型。
pulled_atstring 最近一次成功拉取的时间;还没按域名拉过为空。
remarkstring 备注
retireboolean 是否把旧域名置为停用中。
默认 true
siteinteger 切走的站点接入名数。
site_countinteger 引用该根域的网站、四层转发与套餐总数(与 /cname-domains/{id}/refs 的 site+stream+package 同口径),无引用为 0。
site_idinteger 网站 ID
site_liststring[] 切走的站点接入名清单。
skippedobject[] 被跳过的接入域名及原因。
stateCnameSwitchState changed 已改;unchanged 未改;not_cname 非 CNAME 接入(指向别处或只有 A 记录);failed 查询失败;pending 待核对。
可选值 ["changed","unchanged","not_cname","failed","pending"]
statusCnameDomainStatus active 使用中;retiring 停用中(已更换走,不再给套餐选)。
可选值 ["active","retiring"]
streaminteger 切走的四层转发接入名数。
stream_liststring[] 前 20 个四层转发(id:<id> <接入名>)。
switch_changedinteger 其中客户已把 CNAME 改到新根域的个数(核对状态 changed);未更换时为 null。
switch_pendinginteger 其中还没核对过的个数(核对状态 pending);未更换时为 null。
switch_totalinteger 整体更换后需核对的网站域名总数;未更换(switched_to 为空)时为 null。
switched_atstring 整体更换发生的时间;未更换为空。
switched_tointeger 整体更换到的根域 id。
switched_to_domainstring 更换到的根域名称;未更换为空。
target_id必填integer 目标根域 id。
tenant_idinteger 所属租户(用户)ID
tostring 目标根域。
unchangedinteger 仍未改的行数。
updatedinteger 实际更新的个数。
updated_atstring 更新时间
只读
user_liststring[] 受影响的客户清单。
user_namestring 客户(租户)名;租户已删为空。
usersinteger 受影响客户数(站点所属租户去重)。

返回与错误

成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。

成功
{
  "id": 1,
  "name": "example"
}
列表
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
失败
{
  "code": "validation_failed",
  "detail": "请求参数不合法",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name 必填"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
开始使用

体验在线演示

访问在线演示,或联系我们获取报价与安装命令