版本 2.4.8 · 最新
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 接入域名
鉴权: 仅管理员
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 页码,从 1 开始。 |
page_size | integer | 每页条数。 |
sort | string | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
domain | string | 只列根域包含该串的(部分匹配,不分大小写,首尾空格与结尾的点忽略)。 |
type | string | 只列归属该服务商类型(如 aliyun)的。 |
dns_provider_id | integer | 只列归属该账号的。 |
status | CnameDomainStatus | 只列该状态的。 |
POST
/api/v2/cname-domains创建CNAME 接入域名
鉴权: 仅管理员
请求体 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;留空时由每日任务向注册局自动获取(见 effective_expire_at)。 |
remark | string | 备注 |
status | CnameDomainStatus | active 使用中;retiring 停用中(已更换走,不再给套餐选)。 |
GET
/api/v2/cname-domains/options列出CNAME 接入域名选项
鉴权: 仅管理员
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 页码,从 1 开始。 |
page_size | integer | 每页条数。 |
status | CnameDomainStatus | 只列该状态的。 |
PUT
/api/v2/cname-domains/status批量设置CNAME 接入域名状态
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
ids必填 | integer[] | 要设置状态的接入域名 id 列表。 |
status必填 | CnameDomainStatus | active 使用中;retiring 停用中(已更换走,不再给套餐选)。 |
PUT
/api/v2/cname-domains/{id}修改CNAME 接入域名
鉴权: 仅管理员
请求体 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;留空时由每日任务向注册局自动获取(见 effective_expire_at)。 |
remark | string | 备注 |
status | CnameDomainStatus | active 使用中;retiring 停用中(已更换走,不再给套餐选)。 |
DELETE
/api/v2/cname-domains/{id}删除CNAME 接入域名
鉴权: 仅管理员
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
local_only | boolean | 为 true 时只删本平台记录,不去服务商侧清该根域下的旧解析(面板「仅删除本地记录」)。 |
POST
/api/v2/cname-domains/{id}/migrate整体更换CNAME 接入域名
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
notify | boolean | 是否给受影响客户发站内信。 |
retire | boolean | 是否把旧域名置为停用中。 |
target_id必填 | integer | 目标根域 id。 |
GET
/api/v2/cname-domains/{id}/switch-check查更换后的切换核对
鉴权: 仅管理员
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 页码,从 1 开始。 |
page_size | integer | 每页条数。 |
state | CnameSwitchState | 只列该核对状态的。 |
q | string | 模糊匹配客户名、网站域名或实际解析。 |
GET
/api/v2/cname-domains/{id}/switch-check/export导出切换核对对照表
鉴权: 仅管理员
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
state | CnameSwitchState | 只列该核对状态的。 |
q | string | 模糊匹配客户名、网站域名或实际解析。 |
CNAME 接入域名对象
| 字段 | 类型 | 说明 |
|---|---|---|
actual | string | 实际解析到的(CNAME 目标或 IP);查询失败时为原因(NXDOMAIN、Timeout…)。 |
changed | integer | 重查后已改的行数。 |
check_rows | integer | 新建的核对行数(每个网站域名一行)。 |
checked | integer | 本次重查的行数。 |
checked_at | string | 最近一次解析检查时间。 |
code | string | 服务商版本代号;读不到为空。 |
created_at | string | 创建时间 |
dns_provider_id | integer | 托管该根域的服务商账号 id。 |
domain | string | 小写根域,如 cdn.example.com。 |
domains | LineOptionDomain[] | 组内全部域名(主组或备用组绑定的)。 |
edition | CnameEdition | 域名在服务商处的版本与线路摘要(读不到版本的服务商只有 line_count 与 granularity)。 |
effective_expire_at | string | 生效到期日 YYYY-MM-DD:手填优先,否则为注册局(RDAP/WHOIS)查到的值;都没有为 null。到期前 30/7/1 天与过期后各提醒管理员一次。 |
err | string | 最近一次拉取失败的原因;最近一次成功为空串。 |
example_hostname | string | 一个现有接入名(不含根域),向导里拼新旧接入地址示例用。 |
expected_updated_at | string | 乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。 |
expire_at | string | 管理员手填的到期日 YYYY-MM-DD;留空时由每日任务向注册局自动获取(见 effective_expire_at)。 |
expire_check_error | string | 注册局自动查询到期日最近一次失败的原因;上次查到了、还没查过或已手填到期日为 null。 |
expire_fail_count | integer | 自动查询到期日连续失败次数(查到即清零;已手填到期日为 0)。连续失败 7 次且仍没有到期日时给管理员发一次站内信。 |
expire_source | CnameExpireSource | 生效到期日来源:manual 手填;auto 注册局自动获取;none 没有到期日。 |
failed | integer | 查询失败的行数。 |
from | string | 原根域。 |
granularity | string | 粒度:province=有运营商×省,isp=只有运营商,default=只有默认,none=还没拉到线路。 |
id | integer | 记录 ID |
ids必填 | integer[] | 要设置状态的接入域名 id 列表。 |
last_checked_at | string | 该根域的核对行最近一次核对的时间;未更换或还没核对过为 null。 |
line_count | integer | 线路条数(线路树节点总数,含默认线路);没拉到为 0。 |
line_tag | integer | 线路地区标签取自本根域的节点数(删除根域时标签一并清掉)。 |
messaged | integer | 发了站内信的客户数。 |
min_ttl | integer | TTL 下限(秒),0=未知。 |
name | string | 版本显示名;读不到为空。 |
new_target | string | 切换后的 CNAME 目标。 |
nodes | LineOptionNode[] | 统一线路并集(不含 default 与专有线路)。 |
not_cname | integer | 非 CNAME 接入的行数。 |
notified_at | string | 通知客户的时间。 |
notify | boolean | 是否给受影响客户发站内信。 |
old_target | string | 切换前的 CNAME 目标。 |
package | integer | 切走的套餐接入名数。 |
package_list | string[] | 前 20 个引用本根域的用户套餐。 |
paid | boolean | 付费版(按服务商版本代号推断,读不到版本为 false)。 |
private | LinePrivateGroup[] | 专有线路,按域名分组;没有专有线路的域名不列。 |
provider_name | string | 归属账号名称。 |
provider_type | string | 归属账号的服务商类型。 |
pulled_at | string | 最近一次成功拉取的时间;还没按域名拉过为空。 |
remark | string | 备注 |
retire | boolean | 是否把旧域名置为停用中。 |
site | integer | 切走的站点接入名数。 |
site_count | integer | 引用该根域的网站、四层转发与套餐总数(与 /cname-domains/{id}/refs 的 site+stream+package 同口径),无引用为 0。 |
site_id | integer | 网站 ID |
site_list | string[] | 切走的站点接入名清单。 |
skipped | object[] | 被跳过的接入域名及原因。 |
state | CnameSwitchState | changed 已改;unchanged 未改;not_cname 非 CNAME 接入(指向别处或只有 A 记录);failed 查询失败;pending 待核对。 |
status | CnameDomainStatus | active 使用中;retiring 停用中(已更换走,不再给套餐选)。 |
stream | integer | 切走的四层转发接入名数。 |
stream_list | string[] | 前 20 个四层转发(id:<id> <接入名>)。 |
switch_changed | integer | 其中客户已把 CNAME 改到新根域的个数(核对状态 changed);未更换时为 null。 |
switch_pending | integer | 其中还没核对过的个数(核对状态 pending);未更换时为 null。 |
switch_total | integer | 整体更换后需核对的网站域名总数;未更换(switched_to 为空)时为 null。 |
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 | 受影响客户数(站点所属租户去重)。 |
返回与错误
成功直接回资源 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"
}