kvm-manager

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

快速开始

方式一：使用启动脚本（推荐）

cd kvm-manager/scripts

# 启动所有服务
./start.sh

# 查看服务状态
./start.sh status

# 停止服务
./start.sh -s

方式二：手动启动

# 后端
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 部署

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 地址。

安装脚本

# 单个虚拟机
./scripts/install-guest-agent.sh VM_NAME

# 所有虚拟机
./scripts/install-guest-agent.sh --all

手动配置

1. 关机虚拟机
2. 编辑配置：virsh edit VM_NAME

3. 在 <devices> 中添加：

   <controller type='virtio-serial' index='0'/>
   <channel type='unix'>
   <source mode='bind'/>
   <target type='virtio' name='org.qemu.guest_agent.0'/>
   </channel>
   

4. 开机后安装 Agent：

   # 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