轻量级、自托管的 Proxmox VE 中文管理面板–维立方PveKube
PVE 官方面板功能完整,但界面偏工程师思维,日常做一次开关机、开一次控制台,常常要在好几层菜单里翻。PveKube 是它的补充界面:只调用 PVE 官方 API(8006),自己不碰虚拟化,所有操作仍由 Proxmox VE 执行与兜底。
一个二进制加一份配置文件,不装 Agent、无数据库、无第三方依赖,开箱即用。仓库地址:https://gitee.com/cncsrf/PveKube
一、项目简介
做这个面板的出发点很简单:PVE 本身足够好用,只是它的界面是给熟悉 PVE 的人准备的。平时最常见的几件事——看看节点还剩多少资源、把某台虚拟机重启一下、连一下控制台、打一个快照——在官方界面里要走的路有点长。
PveKube 不改 PVE,也不接管虚拟化,只在它外面加一层更顺手的视图,把这几个高频动作收进少数几个页面。
这样一来,面板和 PVE 的关系就很清楚了:
无侵入:只调 PVE 的 REST API,宿主机上不装 Agent,不依赖 Prometheus、SSH。面板关了,PVE 照常跑。
开箱即用:单二进制 + 一份 config.json + 静态页面,systemd 一把起;也可以一条 Docker 命令跑起来。
零外部依赖:后端只用 Go 标准库,前端原生 HTML/CSS/JS 无构建,不需要数据库。
可核对:页面上的数字都来自 PVE 实时接口;写操作全程留痕,看得见谁在什么时候做了什么。
二、功能特性

六个模块基本覆盖了日常运维会碰到的全部动作,再往下拆只会让菜单变长。
三、界面预览
首页概览

节点概览

虚拟机详情

四、技术栈
后端:Go 1.22,且刻意只依赖标准库——路由、会话校验、审计落盘、WebSocket 代理都是自己写的。好处是 go build 出来就是一个二进制,没有 vendor 目录,也不会有依赖升级带来的意外;扔到任何一台 Linux 上都能跑。
前端:原生 HTML / CSS / JavaScript,没有构建步骤。改一行样式保存,刷新浏览器就能看到,不用装 node、不用打包。
数据:不需要数据库。三份文件各自负责一件事——config.json 存连接信息,data/ui.json 存站点文案,data/audit.jsonl 存审计流水。文案和密码分开,改个页脚不需要动带密码的文件。
容器:多阶段构建,运行镜像里只有二进制和静态页,不夹带编译环境。
五、系统架构

图里有四个设计上的取舍,值得单独说一下:
面板不缓存业务数据。页面上的数字都是当场向 PVE 要的,只有少数慢且变化慢的聚合结果做 5~30 秒复用。所以面板出问题时,你看到的是「没有页面」,而不是「数字还是旧的」。
PVE 凭据只存在服务端 config.json 里,浏览器手里只有面板自己的会话 Cookie。
节点级接口自动直连目标节点。把一个节点的请求交给另一个节点代转,在两节点 PVE 版本不一致时会撞上 PVE API 596。面板内置了自动改发,不需要人工干预。
控制台走自建的 WS 代理。票据只在目标节点签发、30 秒内有效,浏览器全程不接触 8006。
六、快速开始
两种装法,挑一种。
方式一:一键脚本
git clone https://gitee.com/cncsrf/PveKube.git cd PveKube sudo bash deploy.sh
按提示填 PVE 地址、PVE 密码、面板密码,脚本会装到 /opt/pvekube 并注册开机自启。
仓库里只有源码,脚本就地编译。机器上没装 Go 也不要紧,它会先帮你装好再编译,不用提前准备环境。
装完浏览器打开 http://<服务器IP>:8080,账号 admin,密码就是刚才脚本里设的那个。
方式二:Docker
配置文件不用自己准备,首次启动会自动生成。只有两项必须自己传:
docker run -d --name pvekube --restart unless-stopped --network host -v /opt/pvekube/data:/app/data -v /usr/share/novnc:/app/web/static/novnc:ro -e PVE_URL=https://192.168.1.10:8006 -e PVE_PASSWORD='PVE 的 root 密码' ad80a1/pvekube:latest
打开 http://<服务器IP>:8080,账号 admin / 密码 admin888,登录后先把密码改掉。
三点提醒:--network host 是为了让容器直接连到 PVE 的 8006;挂 novnc 那一行是为了网页控制台,宿主机先 apt install -y novnc,不挂只是控制台不可用,其余功能照常;其它参数(面板密码、监听端口、Token 认证)见 INSTALL.md。
七、端口

八、仓库目录结构
PveKube/ ├── cmd/server/main.go 入口:配置 → 审计 → PVE 客户端 → HTTP 服务 ├── internal/ │ ├── api/ 业务层:路由、鉴权、校验、审计、缓存 │ ├── pve/ PVE API 层:认证、节点直连、读写接口 │ ├── store/ 审计流水(JSONL) │ ├── wsproxy/ RFC6455 极简实现(VNC 透传) │ └── config/ 配置结构与默认值 ├── tools/hashpwd/ 密码哈希小工具(sha256(salt:password)) ├── web/static/ 前端(无构建:api.js / app.js / style.css + 各页面) ├── screenshots/ 界面截图 ├── deploy.sh 一键安装 / 升级脚本 ├── Dockerfile 多阶段构建镜像 ├── docker-compose.yml 容器编排 ├── config.example.json 配置样例 ├── INSTALL.md 安装教程(脚本 / Docker / 排错) ├── PVE管理平台开发文档.md 开发文档:架构、接口契约、二开指引 └── README.md
九、文档
README 只讲怎么最快跑起来,机制、接口和安全设计都在另外两份里。
INSTALL.md —— 给要落地的人:两种装法、Token 认证、升级卸载、常见问题。
PVE管理平台开发文档.md —— 给要改代码的人:分层结构、PVE 客户端契约、596 与节点直连、创建 / 快照 / 备份 / 迁移 / 控制台各流程的实现、完整 API 表、二开指引、安全设计、排错手册。
十、注意事项
控制台需要账号密码。纯 API Token 部署时网页控制台不可用,其余功能正常——这是 PVE 一侧的限制,不是面板的。
虚拟机 IP 依赖 QEMU Guest Agent。客户机里装好才会显示,没装时显示 — 属于正常现象。
面板不替代 PVE 的权限校验。访问 PVE 用哪个账号由 config.json 决定,最终权限以 PVE 为准。
面板不提供 TLS,公网访问请前置 Nginx / Caddy 反代;反代记得透传 WebSocket 的 Upgrade 头,否则控制台连不上。
面板备份包含 config.json,其中有明文 PVE 密码,导出后请妥善保管。
删除虚拟机、回滚快照、发起备份这类操作,面板只负责把请求交给 PVE,请务必自行确认。
本项目仅为 PVE 官方面板的补充界面,所有虚拟化操作仍由 Proxmox VE 完成与兜底。
作者提示含AI生成内容。作者声明本文无利益相关,欢迎值友理性交流,和谐讨论~
