## CNAME 接入域名 (`cname-domains`)

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

鉴权: 仅管理员 · 文档: https://www-sa2.kuxitong.com/zh/docs/api/cname-domains

### GET `/api/v2/cname-domains`

列出CNAME 接入域名 · 鉴权: 仅管理员

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `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"] |

```sh
curl "https://panel.example.com/api/v2/cname-domains" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/cname-domains`

创建CNAME 接入域名 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `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 停用中(已更换走,不再给套餐选)。 可选值: ["active","retiring"] |

```sh
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":"主接入域名"}'
```

### GET `/api/v2/cname-domains/options`

列出CNAME 接入域名选项 · 鉴权: 仅管理员

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `status` | CnameDomainStatus |  | 只列该状态的。 可选值: ["active","retiring"] |

```sh
curl "https://panel.example.com/api/v2/cname-domains/options" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/cname-domains/status`

批量设置CNAME 接入域名状态 · 鉴权: 仅管理员

请求体:

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

```sh
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"}'
```

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

获取CNAME 接入域名 · 鉴权: 仅管理员

```sh
curl "https://panel.example.com/api/v2/cname-domains/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

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

修改CNAME 接入域名 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `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 停用中(已更换走,不再给套餐选)。 可选值: ["active","retiring"] |

```sh
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":"主接入域名"}'
```

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

删除CNAME 接入域名 · 鉴权: 仅管理员

查询参数:

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

```sh
curl -X DELETE "https://panel.example.com/api/v2/cname-domains/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/cname-domains/{id}/line-options`

单个域名的线路选项 · 鉴权: 仅管理员

```sh
curl "https://panel.example.com/api/v2/cname-domains/{id}/line-options" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/cname-domains/{id}/lines/refresh`

重新拉取域名线路 · 鉴权: 仅管理员

```sh
curl -X POST "https://panel.example.com/api/v2/cname-domains/{id}/lines/refresh" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

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

整体更换CNAME 接入域名 · 鉴权: 仅管理员

请求体:

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

```sh
curl -X POST "https://panel.example.com/api/v2/cname-domains/{id}/migrate" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

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

查CNAME 接入域名的引用 · 鉴权: 仅管理员

```sh
curl "https://panel.example.com/api/v2/cname-domains/{id}/refs" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### 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 |  | 模糊匹配客户名、网站域名或实际解析。 |

```sh
curl "https://panel.example.com/api/v2/cname-domains/{id}/switch-check" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

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

导出切换核对对照表 · 鉴权: 仅管理员

查询参数:

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

```sh
curl "https://panel.example.com/api/v2/cname-domains/{id}/switch-check/export" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

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

提醒未改的客户 · 鉴权: 仅管理员

```sh
curl -X POST "https://panel.example.com/api/v2/cname-domains/{id}/switch-check/remind" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

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

立即核对 · 鉴权: 仅管理员

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

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 没有到期日。 可选值: ["manual","auto","none"] |
| `failed` | integer |  | 查询失败的行数。 |
| `from` | string |  | 原根域。 |
| `granularity` | string |  | 粒度:province=有运营商×省,isp=只有运营商,default=只有默认,none=还没拉到线路。 可选值: ["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 |  | 是否给受影响客户发站内信。 默认: true |
| `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 |  | 是否把旧域名置为停用中。 默认: true |
| `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 待核对。 可选值: ["changed","unchanged","not_cname","failed","pending"] |
| `status` | CnameDomainStatus |  | active 使用中;retiring 停用中(已更换走,不再给套餐选)。 可选值: ["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 |  | 受影响客户数(站点所属租户去重)。 |
