admin
dbba1694d8
- 新增 /vm/list-all API 聚合所有主机虚拟机 - parse_vm_info 支持 include_ip 参数控制IP获取 - VMList 添加主机选择器，显示宿主机列 - 修复 API 路径 /host/list -> /hosts/list - 新增启动脚本 scripts/start.sh - 新增 Guest Agent 安装脚本 scripts/install-guest-agent.sh - 更新 README 文档
169 lines
4.2 KiB
Markdown
169 lines
4.2 KiB
Markdown
# KVM 虚拟化管理平台
|
||
|
||
基于 FastAPI + Vue 3 + Element Plus 的 KVM 虚拟机管理平台，通过 libvirt API 管理虚拟机，支持多主机纳管。
|
||
|
||
## 技术栈
|
||
|
||
- **后端**: FastAPI + libvirt Python API
|
||
- **前端**: Vue 3 + Element Plus + Vite + noVNC
|
||
- **虚拟化**: QEMU/KVM + libvirt
|
||
- **认证**: JWT Token
|
||
|
||
## 功能
|
||
|
||
- 🖥️ 虚拟机管理（创建/启动/停止/删除/克隆/迁移）
|
||
- 📊 资源监控（CPU/内存/磁盘/网络）
|
||
- 💾 存储池管理（支持多种存储类型）
|
||
- 🌐 网络管理（桥接/NAT/独立网络）
|
||
- 📋 控制台访问（WebSocket VNC）
|
||
- 📸 快照管理
|
||
- 🔐 用户认证（JWT）
|
||
- 🖧 多主机纳管（支持 SSH/TCP 连接远程 KVM）
|
||
- 📡 IP 地址自动获取（需要配置 QEMU Guest Agent）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
kvm-manager/
|
||
├── backend/
|
||
│ ├── app/
|
||
│ │ ├── main.py # FastAPI 应用入口
|
||
│ │ ├── config.py # 配置
|
||
│ │ ├── libvirt_conn.py # libvirt 连接池
|
||
│ │ ├── hosts.py # 主机注册表
|
||
│ │ ├── utils.py # 工具函数
|
||
│ │ └── routers/ # API 路由
|
||
│ │ ├── vm.py # 虚拟机管理
|
||
│ │ ├── storage.py # 存储管理
|
||
│ │ ├── network.py # 网络管理
|
||
│ │ ├── snapshot.py # 快照管理
|
||
│ │ ├── monitor.py # 资源监控
|
||
│ │ └── host.py # 主机管理
|
||
│ ├── requirements.txt
|
||
│ └── Dockerfile
|
||
├── frontend/
|
||
│ ├── src/
|
||
│ │ ├── views/ # 页面组件
|
||
│ │ ├── components/ # 通用组件
|
||
│ │ ├── api/ # API 调用
|
||
│ │ ├── router/ # 路由配置
|
||
│ │ └── App.vue
|
||
│ ├── package.json
|
||
│ └── vite.config.js
|
||
├── scripts/ # 工具脚本
|
||
│ ├── start.sh # 服务启动脚本
|
||
│ └── install-guest-agent.sh # Guest Agent 安装脚本
|
||
├── docker-compose.yml
|
||
└── README.md
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 方式一：使用启动脚本（推荐）
|
||
|
||
```bash
|
||
cd kvm-manager/scripts
|
||
|
||
# 启动所有服务
|
||
./start.sh
|
||
|
||
# 查看服务状态
|
||
./start.sh status
|
||
|
||
# 停止服务
|
||
./start.sh -s
|
||
```
|
||
|
||
### 方式二：手动启动
|
||
|
||
```bash
|
||
# 后端
|
||
cd backend
|
||
python -m venv venv
|
||
source venv/bin/activate
|
||
pip install -r requirements.txt
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8004
|
||
|
||
# 前端（另开终端）
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
### 方式三：Docker 部署
|
||
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
## 访问地址
|
||
|
||
- 前端界面：http://localhost:8005
|
||
- API 接口：http://localhost:8004
|
||
- API 文档：http://localhost:8004/docs
|
||
|
||
## 多主机纳管
|
||
|
||
在「主机管理」页面添加远程 KVM 主机，支持以下连接方式：
|
||
|
||
- **本地连接**：`qemu:///system`
|
||
- **SSH 连接**：`qemu+ssh://user@host/system`
|
||
- **TCP 连接**：`qemu+tcp://host/system`
|
||
|
||
## QEMU Guest Agent
|
||
|
||
用于自动获取虚拟机 IP 地址。
|
||
|
||
### 安装脚本
|
||
|
||
```bash
|
||
# 单个虚拟机
|
||
./scripts/install-guest-agent.sh VM_NAME
|
||
|
||
# 所有虚拟机
|
||
./scripts/install-guest-agent.sh --all
|
||
```
|
||
|
||
### 手动配置
|
||
|
||
1. 关机虚拟机
|
||
2. 编辑配置：`virsh edit VM_NAME`
|
||
3. 在 `<devices>` 中添加：
|
||
|
||
```xml
|
||
<controller type='virtio-serial' index='0'/>
|
||
<channel type='unix'>
|
||
<source mode='bind'/>
|
||
<target type='virtio' name='org.qemu.guest_agent.0'/>
|
||
</channel>
|
||
```
|
||
|
||
4. 开机后安装 Agent：
|
||
|
||
```bash
|
||
# CentOS/RHEL
|
||
yum install qemu-guest-agent
|
||
systemctl enable qemu-guest-agent
|
||
|
||
# Ubuntu/Debian
|
||
apt install qemu-guest-agent
|
||
systemctl enable qemu-guest-agent
|
||
```
|
||
|
||
5. 验证：`virsh qemu-agent-command VM_NAME '{"execute":"guest-info"}'`
|
||
|
||
## 配置说明
|
||
|
||
| 配置项 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `LIBVIRT_URI` | 本地 libvirt 连接 URI | `qemu:///system` |
|
||
| `API_PREFIX` | API 路径前缀 | `/api` |
|
||
| `SECRET_KEY` | JWT 密钥 | 自动生成 |
|
||
| `KVM_DATA_DIR` | 主机数据存储目录 | `/var/lib/kvm-manager` |
|
||
|
||
## 注意事项
|
||
|
||
- 远程主机 VNC 需要监听 `0.0.0.0` 才能被代理访问
|
||
- SSH 模式需要配置无密码 SSH 登录
|
||
- Guest Agent 需要虚拟机内部安装并运行才能获取 IP
|