# 维立方 PVE 管理面板

**Repository Path**: cncsrf/PveKube

## Basic Information

- **Project Name**: 维立方 PVE 管理面板
- **Description**: 轻量级、可自托管的 Proxmox VE 中文管理面板。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-11-10
- **Last Updated**: 2026-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PveKube · 维立方 PVE 管理面板

轻量级、自托管的 Proxmox VE 中文管理面板。一个二进制 + 一个配置文件，不装 Agent、无数据库，开箱即用。

PVE 官方面板功能完整，但偏向工程师思维，普通用户使用门槛高。PveKube 只调用 PVE 官方 API，所有操作仍由 Proxmox VE 执行。覆盖虚拟机开关机与网页控制台、创建与配置、快照与备份、跨节点迁移，以及镜像、存储、健康监测与操作审计。

## 功能特性

| 模块 | 能力 |
|------|------|
| 概览与节点 | 首页统计、资源趋势、节点切换、多节点管理 |
| 虚拟机 | 列表搜索、详情、创建向导、开关机、网页控制台 |
| 快照与备份 | 快照创建 / 回滚 / 删除，vzdump 手动备份 |
| 迁移与镜像 | 跨节点迁移、ISO 上传与管理 |
| 存储与磁盘 | 存储容量、磁盘型号与 SMART 健康 |
| 健康监测 | CPU / 内存 / 温度 / SMART、VM 资源 TOP |

## 界面预览

**首页概览**

![首页概览](screenshots/home.jpg)

**节点概览**

![节点概览](screenshots/nodes.jpg)

**虚拟机详情**

![虚拟机详情](screenshots/vm-detail.jpg)

## 技术栈

- **后端**：Go 1.22，**只用标准库、零第三方依赖**；路由、会话、审计、WebSocket 代理全部自实现
- **前端**：原生 HTML / CSS / JavaScript，**无构建步骤**，改完刷新即生效
- **数据**：不需要数据库。`config.json`（连接信息）+ `data/ui.json`（站点文案）+ `data/audit.jsonl`（审计流水）
- **容器**：多阶段构建，运行镜像只含二进制 + 静态页（`Dockerfile` / `docker-compose.yml`）

## 快速开始

两种部署方式，二选一。

### 方式一：一键脚本

```bash
git clone https://gitee.com/cncsrf/PveKube.git
cd PveKube
sudo bash deploy.sh
```

按提示填 PVE 地址、PVE 密码、面板密码，脚本自动装到 `/opt/pvekube` 并注册开机自启。
仓库里只有源码、脚本就地编译，**机器上没有 Go 会自动帮你装好再编译**，不用提前准备环境。

访问 `http://<服务器IP>:8080`，账号 `admin`，密码是你在脚本里设置的那个。

### 方式二：Docker

不用准备配置文件，首次启动会自动生成。**`PVE_URL` 和 `PVE_PASSWORD` 两项必须自己改**
（前者填 PVE 的地址，要带 `https://` 和 `8006` 端口；后者是 PVE 的 `root` 密码）：

```bash
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`](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（自动直连，绕开跨版本代理）
```

四个要点：

- **面板不缓存业务数据**：页面上的数字都来自 PVE 实时接口，只有少数「慢且变化慢」的聚合结果做 5~30 秒复用。
- **PVE 凭据只存在服务端** `config.json`，浏览器只持有面板自己的会话 Cookie。
- **节点级接口自动直连目标节点**：请求经另一个节点代理，在两节点 PVE 版本不一致时会返回 `PVE API 596`；
  面板已内置自动改发，无需人工干预。
- **控制台走自建 WS 代理**：票据只在目标节点签发、30 秒内使用，浏览器不接触 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  忽略项与换行策略
```

## 文档

README 只讲「怎么最快跑起来」；机制、接口契约、安全设计、二次开发都在开发文档里。

| 文档 | 给谁看 |
|------|--------|
| [`INSTALL.md`](INSTALL.md) | 部署实施：两种装法、Token 认证、升级卸载、常见问题 |
| [`PVE管理平台开发文档.md`](PVE管理平台开发文档.md) | 要改代码的人：分层、PVE 客户端契约、596 与节点直连、创建/快照/备份/迁移/控制台流程、完整 API 表、二开四步、安全设计、排错 |

## 注意事项

- **控制台需要账号密码**：纯 API Token 部署时网页控制台不可用，其余功能正常。
- **虚拟机 IP 依赖 QEMU Guest Agent**：客户机内装好才会显示（Debian/Ubuntu）：

```bash
apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent
```

## 免责声明

本项目仅为 PVE 官方面板的补充界面，所有虚拟化操作仍由 Proxmox VE 完成与兜底。
使用本面板执行的危险操作（删除虚拟机、回滚快照、发起备份等）请务必自行确认。

## 许可证

[MIT](LICENSE)