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 实时接口;写操作全程留痕,看得见谁在什么时候做了什么。
二、功能特性
| 模块 | 能力 |
| 概览与节点 | 首页统计、资源趋势、节点切换、多节点管理 |
| 虚拟机 | 列表搜索、详情、创建向导、开关机、网页控制台 |
| 快照与备份 | 快照创建 / 回滚 / 删除,vzdump 手动备份 |
| 迁移与镜像 | 跨节点迁移、ISO 上传与管理 |
| 存储与磁盘 | 存储容量、磁盘型号与 SMART 健康 |
| 健康监测 | CPU / 内存 / 温度 / SMART、VM 资源 TOP |
六个模块基本覆盖了日常运维会碰到的全部动作,再往下拆只会让菜单变长。
三、界面预览首页概览

节点概览

虚拟机详情

四、技术栈
后端:Go 1.22,且刻意只依赖标准库——路由、会话校验、审计落盘、WebSocket 代理都是自己写的。好处是 go build 出来就是一个二进制,没有 vendor 目录,也不会有依赖升级带来的意外;扔到任何一台 Linux 上都能跑。
前端:原生 HTML / CSS / JavaScript,没有构建步骤。改一行样式保存,刷新浏览器就能看到,不用装 node、不用打包。
数据:不需要数据库。三份文件各自负责一件事——config.json 存连接信息,data/ui.json 存站点文案,data/audit.jsonl 存审计流水。文案和密码分开,改个页脚不需要动带密码的文件。
容器:多阶段构建,运行镜像里只有二进制和静态页,不夹带编译环境。
五、系统架构
┌──────────────────────── 浏览器(原生 JS,无构建) ────────────────────────┐
│ index / vms / create / vm-detail / iso / disks / nodes / │
│ monitor / settings / console / login │
│ 公共:api.js(fetch 封装)· app.js(顶栏 / 节点切换) │
└───────────────────────────────┬──────────────────────────────────────────┘
│ Cookie: panel_session
▼
┌──────────────────── 面板进程(单二进制,:8080) ──────────────────────┐
│ internal/api 路由 · 会话校验 · 参数校验 · 审计 · 短 TTL 缓存 │
│ internal/pve PVE REST 客户端(认证 / CSRF / 节点直连 / 解包) │
│ internal/store 审计流水(JSONL) │
│ internal/wsproxy VNC WebSocket 透传(RFC6455 极简实现) │
│ web/static 静态页面(后端直接托管) │
└──────────────┬──────────────────────────────────┬─────────────────────┘
│ /cluster/*(集群级) │ /nodes/<node>/*(节点级)
▼ ▼
入口节点 :8006 目标节点 :8006(自动直连)11
图里有四个设计上的取舍,值得单独说一下:
- 面板不缓存业务数据。页面上的数字都是当场向 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 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。
架构
浏览器(原生 JS,无构建)
│ Cookie: panel_session
▼
面板进程(单二进制 :8080)
├─ internal/api 路由 · 会话 · 参数校验 · 审计 · 短 TTL 缓存
├─ internal/pve PVE REST 客户端(认证 / CSRF / 节点直连 / 解包)
├─ internal/store 审计流水(JSONL)
├─ internal/wsproxy VNC WebSocket 透传(RFC6455 极简实现)
└─ web/static 静态页面(后端直接托管)
│
├─ /cluster/* → 入口节点 :8006
└─ /nodes/<node>/* → 目标节点 :8006(自动直连,绕开跨版本代理)
七、端口
| 端口 | 用途 |
| 8080 | 面板 Web / API(config.json 的 listen 可改) |
| 8006 | PVE API(面板主动连接,不是监听) |
八、仓库目录结构
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 + 各页面)
├── deploy.sh 一键安装 / 升级脚本
├── Dockerfile 多阶段构建镜像
├── docker-compose.yml 容器编排
├── config.example.json 配置样例
├── INSTALL.md 安装教程(脚本 / Docker / 排错)
├── PVE管理平台开发文档.md 开发文档:架构、接口契约、二开指引
└── .gitignore / .gitattributes 忽略项与换行策略
九、注意事项
- 控制台需要账号密码。纯 API Token 部署时网页控制台不可用,其余功能正常——这是 PVE 一侧的限制,不是面板的。
- 虚拟机 IP 依赖 QEMU Guest Agent。客户机里装好才会显示,没装时显示
—属于正常现象。
- 面板不替代 PVE 的权限校验。访问 PVE 用哪个账号由
config.json决定,最终权限以 PVE 为准。
- 面板不提供 TLS,公网访问请前置 Nginx / Caddy 反代;反代记得透传 WebSocket 的
Upgrade头,否则控制台连不上。
- 面板备份包含
config.json,其中有明文 PVE 密码,导出后请妥善保管。
- 删除虚拟机、回滚快照、发起备份这类操作,面板只负责把请求交给 PVE,请务必自行确认。
本项目仅为 PVE 官方面板的补充界面,所有虚拟化操作仍由 Proxmox VE 完成与兜底。