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

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

鉴权: 仅管理员 · 文档: https://www-demo.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;到期前 30/7/1 天与过期后各提醒管理员一次。 |
| `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":"主接入域名"}'
```

### 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;到期前 30/7/1 天与过期后各提醒管理员一次。 |
| `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"
```

### 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 |  | 最近一次解析检查时间。 |
| `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 |  | 受影响客户数(站点所属租户去重)。 |