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

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

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

一、项目简介

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

核心定位：

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

二、核心功能

三、系统架构

┌─────────────────────────────────────────────┐ │ 管理端（单台, :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 管理端

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

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

六、快速使用

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

七、默认端口

八、仓库目录结构

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

作者提示含AI生成内容。作者声明本文无利益相关，欢迎值友理性交流，和谐讨论～