349 lines
10 KiB
Markdown
349 lines
10 KiB
Markdown
# 新增接口对接文档
|
||
|
||
> 来源：`默认模块.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 个接口待对接。**
|