轻量级、可自托管的 KVM 虚拟化集群管理平台–维立方 KVM

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

　　仓库地址：https://gitee.com/cncsrf/VirtKube

一、项目简介

　　维立方 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 拉取并供网页展示。

演示截图

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

登录页

首页概览

主机详情

四、环境要求

操作系统：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 管理端

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

https://gitee.com/cncsrf/VirtKube
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，把它复制回管理端「节点」页对应节点填写，即可完成纳管：

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

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

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 并把管理网卡接入桥；一般无需手动执行。

六、快速使用

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

七、默认端口

端口	用途
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 便携工具）。
来源： https://gitee.com/cncsrf/VirtKube