## IP 池 (`ip-pools`)

管理员维护的 IP 池及池内 IP;池按区域归属,名称全平台唯一。

鉴权: 仅管理员 · 文档: https://www-demo.kuxitong.com/zh/docs/api/ip-pools

### GET `/api/v2/ip-pools`

列出 IP 池 · 鉴权: 仅管理员

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `sort` | string |  | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
| `region_id` | integer |  | 按区域过滤。 |

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

### POST `/api/v2/ip-pools`

创建 IP 池 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `des` | string |  | 备注说明 |
| `name` | string | 有 | 名称 |
| `region_id` | integer | 有 | 区域 ID |

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

### GET `/api/v2/ip-pools/candidates`

IP 池候选节点 IP · 鉴权: 仅管理员

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `region_id` | integer | 有 | 区域 ID。 |

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

### GET `/api/v2/ip-pools/{id}`

获取 IP 池 · 鉴权: 仅管理员

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

### PUT `/api/v2/ip-pools/{id}`

修改 IP 池 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `des` | string |  | 备注说明 |
| `name` | string | 有 | 名称 |
| `region_id` | integer | 有 | 区域 ID |

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

### DELETE `/api/v2/ip-pools/{id}`

删除 IP 池 · 鉴权: 仅管理员

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

### GET `/api/v2/ip-pools/{id}/refs`

IP 池引用站点 · 鉴权: 仅管理员

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ip_id` | integer |  | 只看这个池内 IP。 |
| `limit` | integer |  | 每个 IP 最多列几个站点。 默认: 20 |

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

### GET `/api/v2/ip-pools/{pool_id}/ips`

列出池内 IP · 鉴权: 仅管理员

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `sort` | string |  | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |

```sh
curl "https://panel.example.com/api/v2/ip-pools/{pool_id}/ips" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/ip-pools/{pool_id}/ips`

IP 入池 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `bind_addr` | string |  | 节点上实际监听的本机地址(NAT 场景);null = 用 ip。 |
| `node_id` | integer | 有 | 节点 ID |

```sh
curl -X POST "https://panel.example.com/api/v2/ip-pools/{pool_id}/ips" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/ip-pools/{pool_id}/ips/{id}`

修改池内 IP · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `bind_addr` | string |  | 节点上实际监听的本机地址(NAT 场景);null = 用 ip。 |
| `enabled` | boolean |  | 是否启用 |

```sh
curl -X PUT "https://panel.example.com/api/v2/ip-pools/{pool_id}/ips/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### DELETE `/api/v2/ip-pools/{pool_id}/ips/{id}`

IP 出池 · 鉴权: 仅管理员

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

### POST `/api/v2/ip-pools/{pool_id}/ips/{id}/issue-cert`

签发池内 IP 的平台证书 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `confirm` | boolean |  | 已有有效证书时确认重签。 |

```sh
curl -X POST "https://panel.example.com/api/v2/ip-pools/{pool_id}/ips/{id}/issue-cert" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

IP 池对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `bind_addr` | string |  | 节点上实际监听的本机地址(NAT 场景);null = 用 ip。 |
| `cert` | IpCertState |  | 平台 IP 证书状态。 |
| `confirm` | boolean |  | 已有有效证书时确认重签。 |
| `created_at` | string |  | 创建时间 (只读) |
| `des` | string |  | 备注说明 |
| `enabled` | boolean |  | 是否启用 |
| `hints` | string[] |  | 提示(如节点没上报网卡地址,入池未核对)。 (只读) |
| `id` | integer |  | 记录 ID (只读) |
| `ip` | string |  | IP 地址。 (只读) |
| `ip_count` | integer |  | 池内 IP 数。 (只读) |
| `ips` | object[] |  | 有引用的池内 IP 及其引用站点。 |
| `items` | IpCandidate[] |  | 本页条目 |
| `name` | string |  | 名称 |
| `node_id` | integer |  | 节点 ID |
| `node_name` | string |  | 所属节点名称。 (只读) |
| `node_state` | IpNodeState |  | 持有主节点状态:停用 disabled;否则最近 2 分钟有心跳 online,没有 offline。 可选值: ["online","offline","disabled"] |
| `pool_id` | integer |  | 所属 IP 池 ID。 (只读) |
| `region_id` | integer |  | 区域 ID |
| `region_name` | string |  | 区域名称。 (只读) |
| `site_count` | integer |  | 引用池内 IP 的 IP 站点数(按站点去重)。 (只读) |
| `updated_at` | string |  | 更新时间 (只读) |