# 维立方 KVM 集群管理平台

**Repository Path**: cncsrf/VirtKube

## Basic Information

- **Project Name**: 维立方 KVM 集群管理平台
- **Description**: 轻量级、可自托管的 KVM 虚拟化集群管理平台。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-06
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: KVM虚拟化

## README

# 维立方 KVM 集群管理平台

轻量级、可自托管的 KVM 虚拟化集群管理平台。用一个 Web 控制台统一纳管多台物理机上的 libvirt / KVM 虚拟机，覆盖虚拟机的创建、开关机、VNC 控制台、磁盘挂载、快照、跨节点迁移、网络桥接、存储池与集群节点管理、导入迁移、运维监控与操作审计等能力。


## 一、项目简介

维立方 KVM 集群管理平台面向需要集中管理多台 KVM 宿主机的运维场景，把分散在各物理机上的虚拟机、网络、存储与监控收敛到一个统一界面，降低虚拟化环境的日常运维门槛。

核心定位：

- **统一管理**：一个控制台纳管整个 KVM 集群，不必逐台登录宿主机。
- **开箱即用**：SQLite 内置数据库、一键部署脚本、默认管理桥与兜底 NAT 网络，安装后即可使用。
- **自托管**：全部组件部署在企业内网，数据不出域，无外部依赖。
- **可观测**：内置节点资源监控、健康检查与告警中心，虚拟机运行态一目了然。

## 二、核心功能

| 模块 | 能力 |
|------|------|
| 虚拟机生命周期 | 创建、启动、关机、重启、强制断电、删除、挂载/卸载磁盘、调整配置 |
| 网页控制台 | 基于 noVNC 的浏览器 VNC 控制台，无需本地客户端即可操作虚拟机 |
| 快照与备份 | 在线/离线快照、快照回滚、整机备份与恢复 |
| 集群节点 | 节点纳管（Agent 令牌）、节点详情、节点模板、批量操作 |
| 镜像管理 | 系统镜像（qcow2 等）上传、同步、Web 镜像源 |
| 存储管理 | 存储池管理、磁盘分配与回收 |
| 网络管理 | 桥接 / NAT 网络、安全组、网络同步 |
| 跨节点迁移 | 同构 Linux 虚拟机在集群节点间迁移 |
| 导入虚拟机 | 从 Proxmox VE、VMware ESXi 导入现有虚拟机（同构 Linux） |
| 运维监控 | 节点资源指标面板、健康检查、告警中心 |
| AI 助手 | 内置对话式助手，辅助排查与操作 |
| 系统管理 | 全局设置、用户与权限、通知中心、操作日志、备份恢复 |

## 三、系统架构

```
┌─────────────────────────────────────────────┐
│           管理端（单台, :8080）              │
│  Flask + SQLite(config.db) + systemd         │
│  · Web 控制台 / REST API                     │
│  · 集群编排：节点、网络、存储、镜像、迁移    │
│  · 监控接入：Prometheus(:9091) 查询          │
└───────────────┬─────────────────────────────┘
                │ HTTP / token 鉴权
   ┌────────────┴────────────┐
   ▼                         ▼
┌──────────────┐      ┌──────────────┐
│ 节点 Agent A  │ ...  │ 节点 Agent B  │   每台 KVM 宿主机一个
│ (:9090, root) │      │ (:9090)      │
│ libvirt/KVM   │      │ libvirt/KVM   │
│ 桥接/NAT/iptables             
└──────────────┘      └──────────────┘

控制台：noVNC(网页) + websockify(WS→VNC, :6080) 动态代理每台 VM 的 VNC(:5900+n)
监控：各节点 node_exporter(:9100) → 管理端 Prometheus(:9091)
```

- **管理端**：安装在单独一台机器，负责 Web 界面、数据库（SQLite）与集群编排，通过每台节点的 Agent 下发操作。
- **节点 Agent**：每台运行 KVM 的宿主机上部署一个，直接调用本机 libvirt 管理虚拟机、桥接与 NAT，使用 token 与管理端通信。
- **控制台代理**：按需启动 websockify，把 VM 的 VNC 端口通过 WebSocket 暴露给 noVNC 网页，浏览器即可操作虚拟机。
- **监控**：各节点运行 node_exporter 采集指标，管理端 Prometheus 拉取并供网页展示。

## 演示截图

> 以下为平台实际界面截图。

**登录页**

![登录页](screenshots/login.jpg)

**首页概览**

![首页概览](screenshots/dashboard.jpg)

**主机详情**

![主机详情](screenshots/host-detail.jpg)

## 四、环境要求

- 操作系统：Ubuntu 24.04 LTS（推荐）；其他 Linux 发行版未做验证
- CPU 需支持虚拟化（VT-x / AMD-V）并已开启
- 管理端与节点均需 root 权限（Agent 以 root 运行）
- 若在 ESXi 等虚拟化平台内嵌套部署，需开启端口组 `Forged Transmits` / `MAC Address Changes` / `Promiscuous Mode`，否则 Linux 桥无法收发
- Python 3.11+（部署脚本会自动建 venv）

## 五、安装部署

### 5.1 管理端

在计划作为管理端的机器上执行：

```bash
bash deploy-manager.sh
```

脚本会：在 `/kvm_manager` 建立 Python 虚拟环境、安装依赖、配置 systemd 服务（`kvm-manager`）、初始化数据库、部署本机 Agent、并搭建默认管理桥 `br0` 与兜底 NAT 网络 `virbr0`。

默认已集成监控组件（Prometheus + 各节点 node_exporter），无需单独安装；如不想安装监控，可加 `--skip-monitor` 参数。运行脚本后会显示菜单，可选「安装 / 卸载 / 退出」（卸载会移除脚本安装的全部组件，但保留 `/var/lib/libvirt` 下的虚拟机磁盘）。

### 5.2 计算节点

推荐方式：在管理端「节点」页添加节点后，平台会自动生成一条安装命令（仅含管理端地址 `--server`），复制该命令到目标机执行即可。安装完成后终端会**打印本机自动生成的 Token**，把它复制回管理端「节点」页对应节点填写，即可完成纳管：

```bash
curl -sSL http://<管理端IP>:8080/static/deploy-agent.sh | bash -s -- --server <管理端IP>
```

也可手动到节点执行（`<管理端IP>` 通过 `--server` 指定；`--token` 可选，不填则装完后由节点生成并打印）：

```bash
bash deploy-agent.sh --server <管理端IP>
```

脚本会部署 Agent、建立 venv、配置 `kvm-agent` 服务，并自动建桥。通过安装 URL（带 `--server`）执行时脚本直接安装、不再弹菜单；若在节点本地无参数运行 `bash deploy-agent.sh`，则显示「1) 安装 / 2) 卸载 / 3) 退出」菜单。如需卸载本节点 Agent，执行 `bash deploy-agent.sh --uninstall`（保留宿主 KVM 与虚拟机磁盘）。

### 5.3 建桥（被部署脚本自动调用）

`setup-br0.sh` 由上述部署脚本在全新机器上自动调用，负责创建 `br0` 并把管理网卡接入桥；一般无需手动执行。

## 六、快速使用

1. 浏览器访问 `http://<管理端IP>:8080`。
2. 以默认管理员登录（用户名 `admin`，密码 `admin888`），**请立即在「设置」中修改口令**。
3. 在「节点」页面添加计算节点，粘贴节点令牌完成纳管。
4. 「镜像」页面上传或同步系统镜像（qcow2）；「存储」页面管理存储池。
5. 「虚拟机」页面创建虚拟机、挂载磁盘、开关机、打开 VNC 控制台、做快照、跨节点迁移；亦可在「导入虚拟机」中从 Proxmox VE / VMware ESXi 导入。
6. 「网络」页面创建桥接与 NAT 网络、配置安全组。
7. 「监控」页面查看各节点资源指标与健康检查、告警（管理端部署时已默认集成监控）。

## 七、默认端口

| 端口 | 用途 |
|------|------|
| 8080 | 管理端 Web / API |
| 9090 | 节点 Agent |
| 9091 | Prometheus（因 9090 已被 Agent 占用，退至 9091） |
| 9100 | node_exporter |
| 6080 | websockify 控制台代理（按需启动） |

## 八、仓库目录结构

```
virtkube-kvm/
├── app.py                  # 管理端入口
├── auth.py / core.py / utils.py / agent_client.py
├── agent/                  # 节点 Agent 源码
├── routes/                 # 管理端 API / 页面路由
├── db/                     # 数据库模型与初始化
├── static/                 # 前端静态资源 + 部署用 Agent 包(static/agent)
├── templates/              # 页面模板
├── deploy-manager.sh       # 管理端部署
├── deploy-agent.sh         # 节点部署
├── setup-br0.sh            # 建桥（被部署脚本调用）
├── setup-monitoring.sh     # 一键监控
├── requirements.txt
├── CONSTRAINTS.md          # 项目约束
├── KVM管理平台开发文档.md    # 开发 / 实现细节（主文档）
├── KVM管理平台部署运维手册.md # 部署与运维手册
└── README.md
```

## 九、配套文档

- 开发约束见 `CONSTRAINTS.md`；
- 实现细节、接口与踩坑记录见 `KVM管理平台开发文档.md`；
- 部署与运维流程见 `KVM管理平台部署运维手册.md`。

## 十、注意事项

- 数据库采用 SQLite（`config.db`），由部署脚本初始化，无需额外数据库服务。
- 镜像同步依赖管理端到节点的 SSH 免密登录，新增节点时请确保已配置。
- 默认管理员口令为 `admin888`，生产环境务必第一时间修改。
- 平台名称、页脚等品牌信息在「设置 → 全局设置」中可配置；全新安装默认名称为「维立方 KVM 集群管理平台」。
- 忘记管理员密码时，参见《KVM管理平台部署运维手册》的「密码重置」章节（提供免登录、免重启的 `reset_password.py` 便携工具）。