版本 2.1.1792967583 · 最新下载 OpenAPI Markdown 版

CNAME 接入域名

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

cname-domainsDNS 与接入鉴权: 仅管理员12 个接口

列出CNAME 接入域名

GET/api/v2/cname-domains

鉴权: 仅管理员

查询参数

字段	类型	必填	说明
page	integer	—	页码,从 1 开始。默认 `1`
page_size	integer	—	每页条数。默认 `20`
sort	string	—	排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。
domain	string	—	只列根域包含该串的(部分匹配,不分大小写,首尾空格与结尾的点忽略)。
type	string	—	只列归属该服务商类型(如 aliyun)的。
dns_provider_id	integer	—	只列归属该账号的。
status	CnameDomainStatus	—	只列该状态的。可选值 `["active","retiring"]`

创建CNAME 接入域名

POST/api/v2/cname-domains

鉴权: 仅管理员

请求体 application/json

字段	类型	必填	说明
dns_provider_id	integer	必填	托管该根域的服务商账号 id。
domain	string	必填	小写根域,如 cdn.example.com。
expected_updated_at	string	—	乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。
expire_at	string	—	管理员手填的到期日 YYYY-MM-DD;到期前 30/7/1 天与过期后各提醒管理员一次。
remark	string	—	备注
status	CnameDomainStatus	—	active 使用中;retiring 停用中(已更换走,不再给套餐选)。可选值 `["active","retiring"]`

批量设置CNAME 接入域名状态

PUT/api/v2/cname-domains/status

鉴权: 仅管理员

请求体 application/json

字段	类型	必填	说明
ids	integer[]	必填	要设置状态的接入域名 id 列表。
status	CnameDomainStatus	必填	active 使用中;retiring 停用中(已更换走,不再给套餐选)。可选值 `["active","retiring"]`

获取CNAME 接入域名

GET/api/v2/cname-domains/{id}

鉴权: 仅管理员

修改CNAME 接入域名

PUT/api/v2/cname-domains/{id}

鉴权: 仅管理员

请求体 application/json

字段	类型	必填	说明
dns_provider_id	integer	必填	托管该根域的服务商账号 id。
domain	string	必填	小写根域,如 cdn.example.com。
expected_updated_at	string	—	乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。
expire_at	string	—	管理员手填的到期日 YYYY-MM-DD;到期前 30/7/1 天与过期后各提醒管理员一次。
remark	string	—	备注
status	CnameDomainStatus	—	active 使用中;retiring 停用中(已更换走,不再给套餐选)。可选值 `["active","retiring"]`

删除CNAME 接入域名

DELETE/api/v2/cname-domains/{id}

鉴权: 仅管理员

查询参数

字段	类型	必填	说明
local_only	boolean	—	为 true 时只删本平台记录,不去服务商侧清该根域下的旧解析(面板「仅删除本地记录」)。

整体更换CNAME 接入域名

POST/api/v2/cname-domains/{id}/migrate

鉴权: 仅管理员

请求体 application/json

字段	类型	必填	说明
notify	boolean	—	是否给受影响客户发站内信。默认 `true`
retire	boolean	—	是否把旧域名置为停用中。默认 `true`
target_id	integer	必填	目标根域 id。

查CNAME 接入域名的引用

GET/api/v2/cname-domains/{id}/refs

鉴权: 仅管理员

查更换后的切换核对

GET/api/v2/cname-domains/{id}/switch-check

鉴权: 仅管理员

查询参数

字段	类型	必填	说明
page	integer	—	页码,从 1 开始。默认 `1`
page_size	integer	—	每页条数。默认 `20`
state	CnameSwitchState	—	只列该核对状态的。可选值 `["changed","unchanged","not_cname","failed","pending"]`
q	string	—	模糊匹配客户名、网站域名或实际解析。

导出切换核对对照表

GET/api/v2/cname-domains/{id}/switch-check/export

鉴权: 仅管理员

查询参数

字段	类型	必填	说明
state	CnameSwitchState	—	只列该核对状态的。可选值 `["changed","unchanged","not_cname","failed","pending"]`
q	string	—	模糊匹配客户名、网站域名或实际解析。

提醒未改的客户

POST/api/v2/cname-domains/{id}/switch-check/remind

鉴权: 仅管理员

立即核对

POST/api/v2/cname-domains/{id}/switch-check/run

鉴权: 仅管理员

CNAME 接入域名对象

字段	类型	必填	说明
actual	string	—	实际解析到的(CNAME 目标或 IP);查询失败时为原因(NXDOMAIN、Timeout…)。
changed	integer	—	重查后已改的行数。
check_rows	integer	—	新建的核对行数(每个网站域名一行)。
checked	integer	—	本次重查的行数。
checked_at	string	—	最近一次解析检查时间。
created_at	string	—	创建时间只读
dns_provider_id	integer	—	托管该根域的服务商账号 id。
domain	string	—	小写根域,如 cdn.example.com。
example_hostname	string	—	一个现有接入名(不含根域),向导里拼新旧接入地址示例用。
expected_updated_at	string	—	乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。
expire_at	string	—	管理员手填的到期日 YYYY-MM-DD;到期前 30/7/1 天与过期后各提醒管理员一次。
failed	integer	—	查询失败的行数。
from	string	—	原根域。
id	integer	—	记录 ID 只读
ids	integer[]	必填	要设置状态的接入域名 id 列表。
messaged	integer	—	发了站内信的客户数。
new_target	string	—	切换后的 CNAME 目标。
not_cname	integer	—	非 CNAME 接入的行数。
notified_at	string	—	通知客户的时间。
notify	boolean	—	是否给受影响客户发站内信。默认 `true`
old_target	string	—	切换前的 CNAME 目标。
package	integer	—	切走的套餐接入名数。
package_list	string[]	—	前 20 个引用本根域的用户套餐。
provider_name	string	—	归属账号名称。
provider_type	string	—	归属账号的服务商类型。
remark	string	—	备注
retire	boolean	—	是否把旧域名置为停用中。默认 `true`
site	integer	—	切走的站点接入名数。
site_id	integer	—	网站 ID
site_list	string[]	—	切走的站点接入名清单。
skipped	object[]	—	被跳过的接入域名及原因。
state	CnameSwitchState	—	changed 已改;unchanged 未改;not_cname 非 CNAME 接入(指向别处或只有 A 记录);failed 查询失败;pending 待核对。可选值 `["changed","unchanged","not_cname","failed","pending"]`
status	CnameDomainStatus	—	active 使用中;retiring 停用中(已更换走,不再给套餐选)。可选值 `["active","retiring"]`
stream	integer	—	切走的四层转发接入名数。
stream_list	string[]	—	前 20 个四层转发(id:<id> <接入名>)。
switched_at	string	—	整体更换发生的时间;未更换为空。
switched_to	integer	—	整体更换到的根域 id。
switched_to_domain	string	—	更换到的根域名称;未更换为空。
target_id	integer	必填	目标根域 id。
tenant_id	integer	—	所属租户(用户)ID
to	string	—	目标根域。
unchanged	integer	—	仍未改的行数。
updated	integer	—	实际更新的个数。
updated_at	string	—	更新时间只读
user_list	string[]	—	受影响的客户清单。
user_name	string	—	客户(租户)名;租户已删为空。
users	integer	—	受影响客户数(站点所属租户去重)。

curl

# 列出CNAME 接入域名
curl "https://panel.example.com/api/v2/cname-domains" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 创建CNAME 接入域名
curl -X POST "https://panel.example.com/api/v2/cname-domains" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dns_provider_id":1,"domain":"cdn.example.com","expire_at":"2027-01-31","remark":"主接入域名"}'

# 批量设置CNAME 接入域名状态
curl -X PUT "https://panel.example.com/api/v2/cname-domains/status" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":[1],"status":"retiring"}'

# 获取CNAME 接入域名
curl "https://panel.example.com/api/v2/cname-domains/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 修改CNAME 接入域名
curl -X PUT "https://panel.example.com/api/v2/cname-domains/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dns_provider_id":1,"domain":"cdn.example.com","expire_at":"2027-01-31","remark":"主接入域名"}'

# 删除CNAME 接入域名
curl -X DELETE "https://panel.example.com/api/v2/cname-domains/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 整体更换CNAME 接入域名
curl -X POST "https://panel.example.com/api/v2/cname-domains/{id}/migrate" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 查CNAME 接入域名的引用
curl "https://panel.example.com/api/v2/cname-domains/{id}/refs" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 查更换后的切换核对
curl "https://panel.example.com/api/v2/cname-domains/{id}/switch-check" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 导出切换核对对照表
curl "https://panel.example.com/api/v2/cname-domains/{id}/switch-check/export" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 提醒未改的客户
curl -X POST "https://panel.example.com/api/v2/cname-domains/{id}/switch-check/remind" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 立即核对
curl -X POST "https://panel.example.com/api/v2/cname-domains/{id}/switch-check/run" \
  -H "X-API-Key: $GOCDN_API_KEY"