# Proxmox-Mate
**Repository Path**: attacker/proxmox-mate
## Basic Information
- **Project Name**: Proxmox-Mate
- **Description**: 一个管理proxmox集群web平台
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-19
- **Last Updated**: 2025-12-22
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Proxmox-Mate
[](LICENSE)
[](https://www.python.org/)
[](https://vuejs.org/)
[](https://www.docker.com/)
**现代化的 Proxmox VE 集群管理平台**
*简洁、高效、开箱即用*
[功能特性](#features) • [技术栈](#tech-stack) • [快速开始](#quick-start) • [本地开发](#development)
---
## 📖 项目介绍
**Proxmox-Mate** 是一个轻量级的 Proxmox VE 集群管理 Web 应用,专注于提供简洁、高效的集群管理体验。通过直接对接 Proxmox API,提供更现代化的管理界面和批量操作能力。
**核心优势**:
- 🎯 **界面简洁** - 比官方界面更清爽,功能更专注
- 🚀 **开箱即用** - 默认 SQLite 数据库,无需额外配置
- ⚡ **批量操作** - 支持虚拟机批量管理,提升运维效率
- 🔐 **权限管理** - 内置 RBAC 权限系统,支持多角色分级管理
- ⏰ **定时任务** - 支持 Python/Shell 脚本定时执行
> **适用场景**: Homelab 环境、中小企业虚拟化平台、开发测试环境管理
## ✨ 功能特性
### 集群管理
- 🌐 多集群接入与切换
- 📊 集群资源实时监控(CPU、内存、存储)
- 🖥️ 节点状态查看与管理
### 虚拟机管理
- 💻 虚拟机列表查看与搜索
- ⚡ 电源操作(开机/关机/重启/暂停)
- 📦 模板管理与批量部署
- 🔄 批量操作(批量启动、关机、快照)
### 系统功能
- 👥 **用户管理** - 支持用户增删改查,密码安全校验
- 🔑 **角色权限** - 内置超级管理员、集群管理员、运维人员、只读用户等角色
- ⏰ **定时任务** - 支持 Cron 表达式,可执行 Python/Shell 脚本
- 📝 **脚本模板** - 内置脚本编辑器,支持模板化管理
## 🏗 技术栈
### 后端架构
| 技术 | 版本 | 说明 |
|------|------|------|
| Python | 3.11+ | 核心开发语言 |
| FastAPI | 最新 | 高性能异步 Web 框架 |
| SQLAlchemy | 2.0+ | ORM 框架 |
| proxmoxer | 最新 | Proxmox API 官方客户端 |
| SQLite | - | 默认数据库(可选 MySQL) |
### 前端架构
| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3+ | 渐进式 JavaScript 框架 |
| Pinia | 最新 | Vue 3 官方状态管理 |
| Element Plus | 最新 | 企业级 UI 组件库 |
| Vite | 最新 | 新一代前端构建工具 |
| Axios | 最新 | HTTP 请求库 |
## 🛠 兼容性要求
### Proxmox VE
- **支持版本**: Proxmox VE 7.0+
- **集群模式**: 支持单节点和多节点集群
### 部署环境
- **操作系统**: Linux (Ubuntu 22.04+ / Debian 12+ / CentOS 7+)
- **Docker**: 24.0+
- **Docker Compose**: v2.20+
## 🚀 快速开始
### 方式一:Docker Compose(推荐)
```bash
# 1. 克隆项目
git clone https://github.com/mykernel/Proxmox-Mate.git
cd Proxmox-Mate
# 2. 启动服务
docker-compose up -d
# 3. 访问应用
# 前端: http://localhost:9528
# 后端API: http://localhost:9601/docs
```
### 默认配置
- **前端端口**: `9528`
- **后端端口**: `9601`
- **数据库**: SQLite (位于 `backend/sqlite3.db`)
- **默认账号**: 首次启动自动创建超级管理员(见后端日志)
## ⚙️ 配置说明
### 环境变量配置
后端配置文件: `backend/.env`
```bash
# 数据库配置
DATABASE_URL=sqlite:///./sqlite3.db # 或使用 MySQL
# DATABASE_URL=mysql+pymysql://user:pass@localhost/dbname
# 服务配置
APP_PORT=9601
CORS_ORIGINS=http://localhost:9528
# JWT 配置
SECRET_KEY=your-secret-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=1440
```
### 切换到 MySQL
```bash
# 1. 修改 backend/.env
DATABASE_URL=mysql+pymysql://username:password@localhost:3306/proxmox_mate
# 2. 重启服务
docker-compose restart backend
```
## 💻 本地开发
### 后端开发
```bash
cd backend
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
# 启动开发服务器
python main.py
# 访问 http://localhost:9601/docs 查看 API 文档
```
### 前端开发
```bash
cd frontend
# 安装依赖
npm install
# 启动开发服务器
npm run dev
# 访问 http://localhost:9528
# 构建生产版本
npm run build
```
### 项目结构
```
Proxmox-Mate/
├── backend/ # 后端服务
│ ├── app/
│ │ ├── api/ # API 路由
│ │ ├── core/ # 核心配置(数据库、安全、RBAC)
│ │ ├── models/ # 数据模型
│ │ ├── schemas/ # Pydantic 模型
│ │ └── services/ # 业务逻辑
│ ├── main.py # 应用入口
│ └── requirements.txt
├── frontend/ # 前端应用
│ ├── src/
│ │ ├── api/ # API 请求
│ │ ├── components/ # 公共组件
│ │ ├── router/ # 路由配置
│ │ ├── stores/ # Pinia 状态管理
│ │ └── views/ # 页面组件
│ └── package.json
└── docker-compose.yml # Docker 编排配置
```
## 🔒 安全特性
- **JWT 认证**: 基于 Token 的无状态认证
- **密码加密**: 使用 bcrypt 哈希算法
- **RBAC 权限**: 细粒度的资源访问控制
- **CORS 配置**: 可配置的跨域请求白名单
## 📝 开发计划
- [ ] 虚拟机控制台(VNC/SPICE)集成
- [ ] 存储管理增强
- [ ] 网络配置管理
- [ ] 监控告警功能
- [ ] 操作审计日志
- [ ] 多语言支持
## 📄 开源协议
MIT License - 详见 [LICENSE](LICENSE) 文件
## 🙏 致谢
本项目参考了 [ESXi-Mate](https://github.com/mykernel/ESXi-Mate) 的设计思路
## 💬 问题反馈
- 🐛 **Bug 报告**: [提交 Issue](../../issues/new)
- 💡 **功能建议**: [功能讨论](../../discussions)
---
Built with ❤️ for the DevOps Community