轻量级、自托管的 Proxmox VE 中文管理面板–维立方 PVE

  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
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 完成与兜底。