Add F001: PVE 虚拟机管理功能需求文档
- PVE 主机配置管理
- 机器关联 PVE 虚拟机
- 虚拟机启动/停止操作
- 密码加密存储
Co-Authored-By: 狸花猫/Claude-Qwen3.6-Plus 🐾
This commit is contained in:
openclaw
199
docs/features/F001-pve-vm-management.md
Normal file
199
docs/features/F001-pve-vm-management.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# PVE 虚拟机管理功能需求文档
|
||||
|
||||
## 一、需求概述
|
||||
|
||||
在服务器状态管理面板中增加 **PVE（Proxmox Virtual Environment）虚拟机管理** 功能，允许用户通过管理面板直接启动/关闭 PVE 宿主机上的虚拟机。
|
||||
|
||||
### 关键约束
|
||||
- **可选配置**：此功能为可选项，不影响现有功能
|
||||
- **密码安全**：PVE 密码必须加密存储，不能明文保存
|
||||
- **权限**：仅管理员可操作，访客不可见
|
||||
|
||||
---
|
||||
|
||||
## 二、功能拆解
|
||||
|
||||
### 1. PVE 宿主配置
|
||||
|
||||
#### 1.1 新增 PVE 主机表
|
||||
|
||||
```sql
|
||||
pve_hosts 表:
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT
|
||||
name TEXT NOT NULL -- 名称（如 "PVE-01"）
|
||||
hostname TEXT NOT NULL -- PVE 主机地址（如 "192.168.1.100"）
|
||||
port INTEGER DEFAULT 8006 -- PVE API 端口（默认 8006）
|
||||
username TEXT NOT NULL -- 用户名（如 "root@pam" 或 "root@vmbr0"）
|
||||
password_enc TEXT NOT NULL -- 加密后的密码
|
||||
verify_ssl INTEGER DEFAULT 0 -- 是否验证 SSL（0=不验证）
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
```
|
||||
|
||||
#### 1.2 密码加密存储
|
||||
- 使用现有的 AES-GCM 加密（`server/utils/crypto.go`）
|
||||
- 新增/编辑 PVE 主机时，输入明文密码，后端加密后存储
|
||||
- 查看时返回 `***` 或空，密码不可回显
|
||||
|
||||
#### 1.3 API 设计
|
||||
|
||||
| 方法 | 路径 | 说明 | 权限 |
|
||||
|------|------|------|------|
|
||||
| GET | `/api/pve/hosts` | 获取 PVE 主机列表 | 管理员 |
|
||||
| POST | `/api/pve/hosts` | 创建 PVE 主机 | 管理员 |
|
||||
| PUT | `/api/pve/hosts/:id` | 更新 PVE 主机 | 管理员 |
|
||||
| DELETE | `/api/pve/hosts/:id` | 删除 PVE 主机 | 管理员 |
|
||||
|
||||
---
|
||||
|
||||
### 2. 机器关联 PVE 虚拟机
|
||||
|
||||
#### 2.1 机器表扩展
|
||||
|
||||
在 `machines` 表新增字段：
|
||||
|
||||
```sql
|
||||
pve_host_id INTEGER REFERENCES pve_hosts(id) -- 关联的 PVE 主机
|
||||
pve_vmid TEXT -- 虚拟机 ID（如 "101"）
|
||||
```
|
||||
|
||||
#### 2.2 机器编辑页扩展
|
||||
- 在机器编辑弹窗中增加 "PVE 配置" 区块（仅管理员可见）
|
||||
- 选择关联的 PVE 主机
|
||||
- 输入虚拟机 ID（VMID）
|
||||
- 可选：填写后显示虚拟机当前状态
|
||||
|
||||
#### 2.3 前端交互
|
||||
- 选择 PVE 主机后，通过下拉框显示该主机上的虚拟机列表供选择
|
||||
- 或手动输入 VMID
|
||||
|
||||
---
|
||||
|
||||
### 3. 虚拟机操作
|
||||
|
||||
#### 3.1 PVE API 调用
|
||||
|
||||
使用 PVE REST API（参考）：
|
||||
- 认证：Cookie 认证或 Ticket
|
||||
- 启动：`POST /api2/json/nodes/{node}/qemu/{vmid}/status/start`
|
||||
- 停止：`POST /api2/json/nodes/{node}/qemu/{vmid}/status/stop`
|
||||
- 状态查询：`GET /api2/json/nodes/{node}/qemu/{vmid/status`
|
||||
|
||||
#### 3.2 操作按钮
|
||||
|
||||
在机器详情页增加：
|
||||
- **启动虚拟机** 按钮（显示在机器状态旁边）
|
||||
- **关闭虚拟机** 按钮
|
||||
- 按钮显示状态：支持 / 不支持（仅关联 PVE 虚拟机时显示）
|
||||
|
||||
#### 3.3 API 设计
|
||||
|
||||
| 方法 | 路径 | 说明 | 权限 |
|
||||
|------|------|------|------|
|
||||
| GET | `/api/machines/:id/vm-status` | 获取虚拟机状态（运行中/已停止） | 管理员 |
|
||||
| POST | `/api/machines/:id/vm-start` | 启动虚拟机 | 管理员 |
|
||||
| POST | `/api/machines/:id/vm-stop` | 关闭虚拟机 | 管理员 |
|
||||
|
||||
---
|
||||
|
||||
### 4. 状态展示
|
||||
|
||||
#### 4.1 机器列表页
|
||||
- 已关联 PVE 虚拟机的机器，显示虚拟机状态图标
|
||||
- 显示 "🟢 虚拟机运行中" 或 "🔴 虚拟机已停止"
|
||||
|
||||
#### 4.2 机器详情页
|
||||
- 显示 PVE 主机信息
|
||||
- 显示虚拟机当前状态
|
||||
- 显示最近一次操作结果
|
||||
|
||||
---
|
||||
|
||||
## 三、页面设计
|
||||
|
||||
### PVE 主机管理页（新增）
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PVE 主机管理 [+ 添加主机] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ PVE-01 │ │ PVE-02 │ │
|
||||
│ │ 192.168.1.10 │ │ 192.168.1.11 │ │
|
||||
│ │ root@pam │ │ root@pam │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ [编辑] [删除] │ │ [编辑] [删除] │ │
|
||||
│ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 机器编辑弹窗扩展
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 添加机器 ✕ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ... (现有字段) │
|
||||
│ │
|
||||
│ ───────────────── PVE 配置（可选） ───────────────────── │
|
||||
│ │
|
||||
│ PVE 主机: [选择 PVE 主机 ▼] │
|
||||
│ 虚拟机ID: [输入 VMID，如 101] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、技术实现要点
|
||||
|
||||
### 1. PVE API 客户端
|
||||
- 使用 Go HTTP 客户端调用 PVE REST API
|
||||
- 认证方式：Ticket（获取 API Token 或用户名+密码登录）
|
||||
- 超时设置：30 秒
|
||||
|
||||
### 2. 错误处理
|
||||
- 网络超时/连接失败：提示 "无法连接 PVE 主机"
|
||||
- 认证失败：提示 "PVE 认证失败，请检查用户名和密码"
|
||||
- 操作失败：显示 PVE 返回的错误信息
|
||||
|
||||
### 3. 密码安全
|
||||
- 前端传输使用 HTTPS（或内部网络）
|
||||
- 后端使用 ENCRYPT_KEY 加密存储
|
||||
- 密码不在任何 API 响应中返回
|
||||
|
||||
---
|
||||
|
||||
## 五、验收标准
|
||||
|
||||
### 功能验收
|
||||
|
||||
| 场景 | 预期结果 |
|
||||
|------|----------|
|
||||
| 管理员添加 PVE 主机 | 主机成功添加到列表，密码加密存储 |
|
||||
| 管理员编辑 PVE 主机 | 更新成功，密码重新加密 |
|
||||
| 管理员删除 PVE 主机 | 主机删除，关联机器的 PVE 字段清空 |
|
||||
| 机器关联 PVE 虚拟机 | 机器详情页显示操作按钮 |
|
||||
| 点击启动虚拟机 | 虚拟机启动，状态更新为运行中 |
|
||||
| 点击关闭虚拟机 | 虚拟机停止，状态更新为已停止 |
|
||||
| 访客访问 | 看不到 PVE 相关入口和按钮 |
|
||||
|
||||
### 安全验收
|
||||
|
||||
| 场景 | 预期结果 |
|
||||
|------|----------|
|
||||
| 查看 PVE 主机列表 | 密码字段为空或 `***` |
|
||||
| 查看机器详情 | 不返回 PVE 密码 |
|
||||
| 直接调用 API | 未登录返回 401 |
|
||||
|
||||
---
|
||||
|
||||
## 六、待确认
|
||||
|
||||
1. PVE 认证方式：使用用户名+密码 还是 API Token？
|
||||
2. 是否需要支持集群（多个 PVE 节点）？
|
||||
3. 虚拟机状态刷新频率？
|
||||
|
||||
---
|
||||
|
||||
**需求整理**：狸花猫 @dare
|
||||
Reference in New Issue
Block a user