# 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