# 新增接口对接文档

> 来源：`默认模块.openapi.json` 与 `src/api/admin/kvmService.js` 对比
> 生成时间：2026-03-21

---

## 一、新增接口总览

| # | 模块 | 接口路径 | 方法 | 说明 | 前端状态 |
|---|------|---------|------|------|---------|
| 1 | 快照管理 | `/api/v1/admin/server/host_service/point/snapshot/count` | GET | 获取快照数量与上限 | **新增** |
| 2 | 快照管理 | `/api/v1/admin/server/host_service/point/snapshot/set_limit` | POST | 设置快照数量上限 | **新增** |
| 3 | 备份管理 | `/api/v1/admin/server/host_service/point/backup/count` | GET | 获取备份数量与上限 | **新增** |
| 4 | 备份管理 | `/api/v1/admin/server/host_service/point/backup/set_limit` | POST | 设置备份数量上限 | **新增** |
| 5 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/create` | POST | 创建用户组网 | **新增（全新模块）** |
| 6 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/assign` | POST | 为虚拟机分配组网IP | **新增（全新模块）** |
| 7 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/list` | GET | 获取组网列表 | **新增（全新模块）** |
| 8 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/detail` | GET | 获取组网详情 | **新增（全新模块）** |
| 9 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/delete` | DELETE | 删除组网 | **新增（全新模块）** |
| 10 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/remove_network` | POST | 删除组网下指定网络 | **新增（全新模块）** |

> **注意**：用户组网(Networking)接口的URL前缀为 `/api/v1/admins/service/`（admins复数、service单数），与其他接口 `/api/v1/admin/server/` 不同。

---

## 二、接口详细说明

### 2.1 快照管理 - 新增接口

#### 2.1.1 获取快照数量与上限

- **路径**：`GET /api/v1/admin/server/host_service/point/snapshot/count`
- **标签**：管理员-快照
- **请求参数**（Query）：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service_id | integer | 是 | KVM服务ID |
| vm_id | integer | 是 | 虚拟机ID |

- **响应**：

```json
{
  "code": 200,
  "data": {
    "vm_id": 1,
    "count": 3,
    "limit": 10
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| vm_id | int64 | 虚拟机ID |
| count | uint32 | 当前快照数量 |
| limit | uint32 | 快照上限 |

- **前端函数名**：`getSnapshotCount`

---

#### 2.1.2 设置快照数量上限

- **路径**：`POST /api/v1/admin/server/host_service/point/snapshot/set_limit`
- **标签**：管理员-快照
- **Content-Type**：`multipart/form-data`
- **请求参数**（FormData）：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service_id | integer | 是 | KVM服务ID |
| vm_id | integer | 是 | 虚拟机ID |
| limit | integer | 是 | 快照数量上限 |

- **响应**：

```json
{
  "code": 200,
  "data": {
    "vm_id": 1,
    "count": 3,
    "limit": 20
  }
}
```

- **前端函数名**：`setSnapshotLimit`

---

### 2.2 备份管理 - 新增接口

#### 2.2.1 获取备份数量与上限

- **路径**：`GET /api/v1/admin/server/host_service/point/backup/count`
- **标签**：管理员-备份
- **请求参数**（Query）：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service_id | integer | 是 | KVM服务ID |
| vm_id | integer | 是 | 虚拟机ID |

- **响应**：

```json
{
  "code": 200,
  "data": {
    "vm_id": 1,
    "count": 2,
    "limit": 5
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| vm_id | int64 | 虚拟机ID |
| count | uint32 | 当前备份数量 |
| limit | uint32 | 备份上限 |

- **前端函数名**：`getBackupCount`

---

#### 2.2.2 设置备份数量上限

- **路径**：`POST /api/v1/admin/server/host_service/point/backup/set_limit`
- **标签**：管理员-备份
- **Content-Type**：`multipart/form-data`
- **请求参数**（FormData）：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service_id | integer | 是 | KVM服务ID |
| vm_id | integer | 是 | 虚拟机ID |
| limit | integer | 是 | 备份数量上限 |

- **响应**：

```json
{
  "code": 200,
  "data": {
    "vm_id": 1,
    "count": 2,
    "limit": 10
  }
}
```

- **前端函数名**：`setBackupLimit`

---

### 2.3 用户组网管理（全新模块 KVM-UserNetworking）

> **URL 前缀注意**：此模块所有接口使用 `/api/v1/admins/service/` 前缀

#### 2.3.1 获取组网列表

- **路径**：`GET /api/v1/admins/service/host_service/point/networking/list`
- **请求参数**（Query）：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service_id | integer | 是 | KVM 服务 ID |
| page | integer | 否 | 页码 |
| count | integer | 否 | 每页数量 |
| host_id | integer | 否 | 按宿主机 ID 筛选 |
| user_id | integer | 否 | 按用户 ID 筛选 |
| keyword | string | 否 | 关键词搜索 |

- **响应**：

```json
{
  "meta": { "count": 10 },
  "data": [
    {
      "id": 1,
      "name": "组网名称",
      "description": "描述",
      "user_id": 1,
      "host_id": 1,
      "bridge_name": "br0",
      "gateway": "192.168.1.1",
      "created_at": "2026-03-21T00:00:00Z",
      "updated_at": "2026-03-21T00:00:00Z"
    }
  ]
}
```

- **前端函数名**：`getUserNetworkingList`

---

#### 2.3.2 获取组网详情

- **路径**：`GET /api/v1/admins/service/host_service/point/networking/detail`
- **请求参数**（Query）：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service_id | integer | 是 | KVM 服务 ID |
| networking_id | integer | 是 | 组网 ID |

- **响应**：

```json
{
  "data": { "id": 1, "name": "...", "..." },
  "networks": [
    {
      "network": {},
      "vm_id": 1,
      "vm_name": "vm-1",
      "vm_status": "running"
    }
  ]
}
```

- **前端函数名**：`getUserNetworkingDetail`

---

#### 2.3.3 创建用户组网

- **路径**：`POST /api/v1/admins/service/host_service/point/networking/create`
- **Content-Type**：`multipart/form-data`
- **请求参数**（FormData）：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service_id | integer | 是 | KVM 服务 ID |
| name | string | 是 | 组网名称 |
| description | string | 否 | 组网描述 |
| user_id | integer | 是 | 用户 ID |
| host_id | integer | 是 | 宿主机 ID |
| bridge_name | string | 是 | 网桥名称 |
| gateway | string | 是 | 网关地址 |

- **响应**：返回 `UserNetworkingData` 对象
- **前端函数名**：`createUserNetworking`

---

#### 2.3.4 为虚拟机分配组网 IP

- **路径**：`POST /api/v1/admins/service/host_service/point/networking/assign`
- **Content-Type**：`multipart/form-data`
- **请求参数**（FormData）：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service_id | integer | 是 | KVM 服务 ID |
| networking_id | integer | 是 | 组网 ID |
| vm_id | integer | 是 | 虚拟机 ID |
| ip | string | 否 | 指定 IP，不传则自动分配 |

- **响应**：返回 `networking`、`network`、`task` 三个对象
- **前端函数名**：`assignUserNetworking`

---

#### 2.3.5 删除组网

- **路径**：`DELETE /api/v1/admins/service/host_service/point/networking/delete`
- **请求参数**（Query）：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service_id | integer | 是 | KVM 服务 ID |
| networking_id | integer | 是 | 组网 ID |

- **前端函数名**：`deleteUserNetworking`

---

#### 2.3.6 删除组网下的指定网络

- **路径**：`POST /api/v1/admins/service/host_service/point/networking/remove_network`
- **Content-Type**：`multipart/form-data`
- **请求参数**（FormData）：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service_id | integer | 是 | KVM 服务 ID |
| networking_id | integer | 是 | 组网 ID |
| network_id | integer | 是 | 网络 ID |
| vm_id | integer | 是 | 虚拟机 ID（用于从 VM 中移除网络） |

- **前端函数名**：`removeUserNetworkingNetwork`

---

## 三、数据模型

### UserNetworkingData

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int64 | 组网ID |
| name | string | 组网名称 |
| description | string | 描述 |
| user_id | int64 | 用户ID |
| host_id | int64 | 宿主机ID |
| bridge_name | string | 网桥名称 |
| gateway | string | 网关地址 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### NetworkingNetworkItem

| 字段 | 类型 | 说明 |
|------|------|------|
| network | Network | 网络对象 |
| vm_id | int64 | 虚拟机ID |
| vm_name | string | 虚拟机名称 |
| vm_status | string | 虚拟机状态 |

---

## 四、已有接口（已对接，无需修改）

以下接口在 `kvmService.js` 中已存在，无需新增：

- 主控服务管理：list / detail / create / update / delete（5个）
- 宿主机组映射管理：list / sync / bind / update / generate_goods / delete（6个）
- 远程宿主机组管理：list / detail / tree / optimal_host / create / update / delete（7个）
- 宿主机管理：list / detail / metrics / add / update / delete（6个）
- 镜像管理：list / detail / host_status / create / update / delete / reload / sync / reload_host / compare_host（10个）
- 网络管理：list / detail / create / update / delete（5个）
- 数据卷管理：list / detail / create / resize / mount / unmount / transfer / delete（8个）
- 虚拟机管理：list / detail / status / metrics / create / update / rebuild / refactor / update_traffic / start / stop / reboot / suspend / resume / rescue / exit_rescue / delete（17个）
- 安全组管理：list / detail / create / update / sync / bind / unbind / delete / enable_whitelist / disable_whitelist / create_rule / update_rule / delete_rule / apply / set_shared（15个）
- VNC节点管理：list / vm_vnc / add / test / update / delete（6个）
- 快照管理：list / progress / create / restore / delete（5个）
- 备份管理：list / progress / create / restore / delete（5个）

**共计已对接 95 个接口，新增 10 个接口待对接。**