# opsx-pve

**Repository Path**: opsx-tools/opsx-pve

## Basic Information

- **Project Name**: opsx-pve
- **Description**: 一个Proxmox PVE虚拟化管理平台
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-13
- **Last Updated**: 2026-01-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# opsx-pve

**现代化的 Proxmox VE 集群管理平台**

*简洁、高效、开箱即用*

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.12.8-blue.svg)](https://www.python.org/)
[![Node.js](https://img.shields.io/badge/node-v24-green.svg)](https://nodejs.org/)
[![Vue](https://img.shields.io/badge/vue-3+-42b883.svg)](https://vuejs.org/)
[![Docker](https://img.shields.io/badge/docker-ready-2496ed.svg)](https://www.docker.com/)

</div>

## 简介

opsx-pve 是一个轻量级的 Proxmox VE 集群管理 Web 应用，提供比官方界面更简洁的管理体验和批量操作能力。

**核心特性**：
- 🎯 界面简洁，功能专注
- 🚀 SQLite 零配置启动
- ⚡ 虚拟机批量操作
- 🔐 RBAC 权限管理
- ⏰ 定时任务支持
- 🖥️ VNC 控制台

---

## 快速开始

### Docker Compose 部署（推荐生产环境）

适用于远程服务器或本地 Docker 环境，一键部署：

```bash
# 1. 克隆项目
git clone https://gitee.com/opsx-tools/opsx-pve.git
cd opsx-pve

# 2. 构建并启动服务
docker-compose up -d --build

# 3. 访问应用
# 前端: http://localhost:9528
# 默认账号: admin / admin
```

**远程服务器部署示例**：

```bash
# 1. 通过 SSH 连接到服务器
ssh root@your-server-ip

# 2. 克隆项目
cd /opt
git clone https://gitee.com/opsx-tools/opsx-pve.git
cd opsx-pve

# 3. 一键启动
docker-compose up -d --build

# 4. 检查服务状态
docker-compose ps
docker logs opsx-pve-backend
```

**常用管理命令**：

```bash
# 查看服务状态
docker-compose ps

# 查看实时日志
docker-compose logs -f

# 查看特定服务日志
docker logs -f opsx-pve-backend
docker logs -f opsx-pve-frontend

# 重启服务
docker-compose restart

# 重新构建并启动（代码更新后）
docker-compose up -d --build

# 停止服务
docker-compose down

# 完全清理（包括数据卷）
docker-compose down -v
```

**服务端口说明**：

| 服务 | 容器名 | 端口映射 | 说明 |
|------|--------|----------|------|
| 前端 | opsx-pve-frontend | 9528:80 | Nginx 静态文件服务 |
| 后端 | opsx-pve-backend | 9601:9601 | FastAPI 服务 |

**数据持久化**：

数据库和日志文件存储在 `./data` 目录：

```bash
data/
├── sqlite3.db          # SQLite 数据库
└── logs/
    └── backend.log     # 后端日志（自动轮转，单文件 50MB，保留 3 份）
```

**故障排查**：

```bash
# 服务无法启动
docker-compose logs backend
docker-compose logs frontend

# 端口冲突
# 修改 docker-compose.yml 中的端口映射
ports:
  - "9528:80"   # 修改左侧端口号
  - "9601:9601"

# 权限问题
sudo chown -R $USER:$USER ./data

# 重新构建镜像
docker-compose build --no-cache
docker-compose up -d
```

### 本地开发模式

使用快速启动脚本（推荐）：

```bash
./start.sh           # 启动所有服务
./start.sh backend   # 仅启动后端
./start.sh frontend  # 仅启动前端
./start.sh stop      # 停止所有服务
./start.sh status    # 查看服务状态
```

**环境要求**：
- Python 3.12 (见 `backend/.python-version`)
- Node.js v24 (见 `frontend/.nvmrc`)

**手动启动**：

```bash
# 后端
cd backend
python3.12 -m venv venv
# 使用阿里云镜像源安装依赖（推荐）
venv/bin/pip3.12 install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt
venv/bin/python main.py

# 前端
cd frontend
# 使用 nvm 切换 Node.js 版本（如果已安装 nvm）
nvm use
npm install
npm run dev
```

---

## 功能特性

| 模块 | 功能 |
|------|------|
| **集群管理** | 多集群接入、节点管理、资源监控 |
| **虚拟机** | 列表查看、电源操作、批量管理 |
| **VNC 控制台** | 直接在浏览器中连接虚拟机 |
| **用户权限** | RBAC 权限系统、多角色管理 |
| **定时任务** | Cron 定时执行 Python/Shell 脚本 |
| **操作日志** | 登录日志、审计日志 |

---

## 配置说明

### 环境变量

后端配置文件：`backend/.env`

```bash
# 数据库（默认 SQLite）
DATABASE_URL=sqlite:///./sqlite3.db

# MySQL 示例
# DATABASE_URL=mysql+pymysql://user:password@localhost:3306/proxmox_mate

# 服务端口
APP_PORT=9601

# CORS 白名单
CORS_ORIGINS=http://localhost:9528,http://your-server-ip:9528

# JWT 密钥
SECRET_KEY=your-secret-key-here
```

前端环境配置：

环境变量文件：
- 开发环境配置：`frontend/.env.development`
- 生产环境配置：`frontend/.env.production`

| 环境 | API 地址 | 说明 |
|------|----------|------|
| 开发环境 | `http://localhost:9601/api` | 使用完整URL，包含协议和端口 |
| 生产环境 | `/api` | 使用相对路径，由 Nginx 代理 |

环境变量说明：
- `VITE_API_BASE_URL`: API 基础地址（优先使用）
- `VITE_APP_BASE_API`: API 基础地址（备选，向后兼容）
- 如果都未设置，默认使用 `/api`

在浏览器控制台可以看到当前使用的 API 地址配置。

### 端口说明

| 服务 | 端口 |
|------|------|
| 前端 | 9528 |
| 后端 API | 9601 |

---

## 技术栈

**后端**：Python 3.12.8 + FastAPI + SQLAlchemy + proxmoxer

**前端**：Node.js v24 + Vue 3 + Pinia + Element Plus + Vite

### 版本要求

| 组件 | 版本 | 配置文件 |
|------|------|----------|
| Python | 3.12.8 | `backend/.python-version` |
| Node.js | v24 | `frontend/.nvmrc` |

---

## 项目结构

```
opsx-pve/
├── backend/              # 后端服务
│   ├── app/
│   │   ├── api/         # API 路由
│   │   ├── core/        # 核心配置
│   │   ├── models/      # 数据模型
│   │   ├── services/    # 业务逻辑
│   │   └── schemas/     # Pydantic 模型
│   ├── main.py          # 应用入口
│   └── requirements.txt
├── frontend/             # 前端应用
│   ├── src/
│   │   ├── api/         # API 请求
│   │   ├── components/  # 公共组件
│   │   ├── router/      # 路由配置
│   │   ├── stores/      # Pinia 状态管理
│   │   └── views/       # 页面组件
│   └── package.json
├── docker-compose.yml    # Docker 编排
├── start.sh              # 快速启动脚本
├── CLAUDE.md             # Claude Code 项目指南
└── README.md
```

---

## 常用命令

```bash
# 本地开发（使用 start.sh）
./start.sh           # 启动所有服务
./start.sh stop      # 停止所有服务
./start.sh status    # 查看服务状态

# Docker Compose（远程服务器）
docker-compose up -d          # 启动服务
docker-compose down           # 停止服务
docker-compose logs -f        # 查看日志
docker-compose restart        # 重启服务

# 查看服务状态（远程）
docker-compose ps
```

---

## 兼容性

| 环境 | 要求 |
|------|------|
| Python | 3.12.8 (见 `backend/.python-version`) |
| Node.js | v24 (见 `frontend/.nvmrc`) |
| Proxmox VE | 7.0+ |
| 操作系统 | Linux (Ubuntu 22.04+ / Debian 12+ / CentOS 7+) |
| Docker | 24.0+ |
| Docker Compose | v2.20+ |

---

## 安全特性

- JWT Token 认证
- bcrypt 密码加密
- RBAC 权限控制
- CORS 跨域配置
- 操作审计日志

---

## 开源协议

MIT License

---

<div align="center">
  <sub>Built with ❤️ for the DevOps Community</sub>
</div>