Add comprehensive API documentation and README
Co-authored-by: Ospab <189454929+Ospab@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
366
README.md
Normal file
366
README.md
Normal file
@@ -0,0 +1,366 @@
|
|||||||
|
# Ospabhost 8.1 - Server Management Platform
|
||||||
|
|
||||||
|
Полнофункциональная платформа управления серверами на базе Proxmox VE с поддержкой LXC контейнеров.
|
||||||
|
|
||||||
|
## Возможности
|
||||||
|
|
||||||
|
### Управление серверами
|
||||||
|
- ✅ Создание LXC контейнеров
|
||||||
|
- ✅ Управление состоянием (запуск, остановка, перезагрузка)
|
||||||
|
- ✅ Изменение конфигурации (CPU, RAM, диск)
|
||||||
|
- ✅ Управление снэпшотами (создание, восстановление, удаление)
|
||||||
|
- ✅ Доступ к консоли через noVNC
|
||||||
|
- ✅ Смена root-пароля
|
||||||
|
|
||||||
|
### Мониторинг
|
||||||
|
- ✅ Real-time статистика серверов через WebSocket
|
||||||
|
- ✅ Графики использования ресурсов (CPU, RAM, диск, сеть)
|
||||||
|
- ✅ Автоматические алерты при превышении лимитов (>90%)
|
||||||
|
- ✅ Email уведомления о проблемах
|
||||||
|
- ✅ Периодическая проверка состояния (каждые 30 секунд)
|
||||||
|
|
||||||
|
### Пользовательский интерфейс
|
||||||
|
- ✅ Панель управления серверами
|
||||||
|
- ✅ Real-time обновления статуса
|
||||||
|
- ✅ Интерактивные графики
|
||||||
|
- ✅ Модальные окна для настроек
|
||||||
|
- ✅ Управление снэпшотами
|
||||||
|
- ✅ Встроенная консоль
|
||||||
|
|
||||||
|
## Технологический стек
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
- TypeScript
|
||||||
|
- Express.js
|
||||||
|
- Prisma ORM
|
||||||
|
- Socket.IO (WebSocket)
|
||||||
|
- Nodemailer (Email)
|
||||||
|
- Axios (Proxmox API)
|
||||||
|
- MySQL/MariaDB
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
- React 19
|
||||||
|
- TypeScript
|
||||||
|
- Vite
|
||||||
|
- TailwindCSS
|
||||||
|
- Socket.IO Client
|
||||||
|
- Recharts (графики)
|
||||||
|
- React Router DOM
|
||||||
|
|
||||||
|
## Установка и настройка
|
||||||
|
|
||||||
|
### Требования
|
||||||
|
- Node.js 18+
|
||||||
|
- MySQL/MariaDB
|
||||||
|
- Proxmox VE 7+ с настроенными API токенами
|
||||||
|
- SMTP сервер (опционально, для email уведомлений)
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
|
||||||
|
1. Перейдите в директорию backend:
|
||||||
|
```bash
|
||||||
|
cd ospabhost/backend
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Установите зависимости:
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Создайте файл `.env` с конфигурацией:
|
||||||
|
```env
|
||||||
|
# Database
|
||||||
|
DATABASE_URL="mysql://user:password@localhost:3306/ospabhost"
|
||||||
|
|
||||||
|
# Proxmox Configuration
|
||||||
|
PROXMOX_API_URL="https://your-proxmox.example.com:8006/api2/json"
|
||||||
|
PROXMOX_TOKEN_ID="user@pam!token-id"
|
||||||
|
PROXMOX_TOKEN_SECRET="your-secret-token"
|
||||||
|
PROXMOX_NODE="proxmox"
|
||||||
|
PROXMOX_WEB_URL="https://your-proxmox.example.com:8006"
|
||||||
|
|
||||||
|
# Server Configuration
|
||||||
|
PORT=5000
|
||||||
|
|
||||||
|
# JWT Secret
|
||||||
|
JWT_SECRET="your-jwt-secret-key-change-this"
|
||||||
|
|
||||||
|
# SMTP Configuration (optional)
|
||||||
|
SMTP_HOST="smtp.gmail.com"
|
||||||
|
SMTP_PORT=587
|
||||||
|
SMTP_USER="your-email@gmail.com"
|
||||||
|
SMTP_PASS="your-app-password"
|
||||||
|
```
|
||||||
|
|
||||||
|
4. Создайте базу данных и примените миграции:
|
||||||
|
```bash
|
||||||
|
npx prisma migrate dev
|
||||||
|
npx prisma db seed
|
||||||
|
```
|
||||||
|
|
||||||
|
5. Соберите проект:
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
6. Запустите сервер:
|
||||||
|
```bash
|
||||||
|
# Development режим с hot-reload
|
||||||
|
npm run dev
|
||||||
|
|
||||||
|
# Production режим
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
|
||||||
|
1. Перейдите в директорию frontend:
|
||||||
|
```bash
|
||||||
|
cd ospabhost/frontend
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Установите зависимости:
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Запустите dev-сервер:
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
4. Или соберите для production:
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
npm run preview
|
||||||
|
```
|
||||||
|
|
||||||
|
## Структура проекта
|
||||||
|
|
||||||
|
```
|
||||||
|
ospabhost/
|
||||||
|
├── backend/
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── modules/
|
||||||
|
│ │ │ ├── auth/ # Авторизация и аутентификация
|
||||||
|
│ │ │ ├── server/ # Управление серверами
|
||||||
|
│ │ │ │ ├── proxmoxApi.ts # Интеграция с Proxmox
|
||||||
|
│ │ │ │ ├── server.controller.ts
|
||||||
|
│ │ │ │ ├── server.routes.ts
|
||||||
|
│ │ │ │ └── monitoring.service.ts # WebSocket мониторинг
|
||||||
|
│ │ │ ├── notification/ # Email уведомления
|
||||||
|
│ │ │ ├── tariff/ # Тарифные планы
|
||||||
|
│ │ │ ├── os/ # Операционные системы
|
||||||
|
│ │ │ ├── ticket/ # Система тикетов
|
||||||
|
│ │ │ └── check/ # Проверка платежей
|
||||||
|
│ │ ├── index.ts # Точка входа, Socket.IO сервер
|
||||||
|
│ │ └── prisma/
|
||||||
|
│ │ ├── schema.prisma # Схема БД
|
||||||
|
│ │ └── seed.ts # Начальные данные
|
||||||
|
│ ├── API_DOCUMENTATION.md # Документация API
|
||||||
|
│ └── package.json
|
||||||
|
└── frontend/
|
||||||
|
├── src/
|
||||||
|
│ ├── pages/
|
||||||
|
│ │ └── dashboard/
|
||||||
|
│ │ └── serverpanel.tsx # Главная панель управления
|
||||||
|
│ ├── hooks/
|
||||||
|
│ │ └── useSocket.ts # WebSocket хуки
|
||||||
|
│ ├── components/ # Переиспользуемые компоненты
|
||||||
|
│ └── context/ # React контексты
|
||||||
|
└── package.json
|
||||||
|
```
|
||||||
|
|
||||||
|
## API Endpoints
|
||||||
|
|
||||||
|
Полная документация API доступна в файле [API_DOCUMENTATION.md](backend/API_DOCUMENTATION.md).
|
||||||
|
|
||||||
|
Основные эндпоинты:
|
||||||
|
- `GET /api/server` - Список серверов
|
||||||
|
- `GET /api/server/:id/status` - Статус и статистика
|
||||||
|
- `POST /api/server/create` - Создание сервера
|
||||||
|
- `POST /api/server/:id/start` - Запуск
|
||||||
|
- `POST /api/server/:id/stop` - Остановка
|
||||||
|
- `POST /api/server/:id/restart` - Перезагрузка
|
||||||
|
- `PUT /api/server/:id/resize` - Изменение конфигурации
|
||||||
|
- `POST /api/server/:id/snapshots` - Создание снэпшота
|
||||||
|
- `GET /api/server/:id/snapshots` - Список снэпшотов
|
||||||
|
- `POST /api/server/:id/snapshots/rollback` - Восстановление
|
||||||
|
- `DELETE /api/server/:id/snapshots` - Удаление снэпшота
|
||||||
|
|
||||||
|
## WebSocket Events
|
||||||
|
|
||||||
|
Подключение к `http://localhost:5000`:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
import { io } from 'socket.io-client';
|
||||||
|
|
||||||
|
const socket = io('http://localhost:5000');
|
||||||
|
|
||||||
|
// Подписка на обновления сервера
|
||||||
|
socket.emit('subscribe-server', serverId);
|
||||||
|
|
||||||
|
// Получение статистики
|
||||||
|
socket.on('server-stats', (data) => {
|
||||||
|
console.log('Stats:', data);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Получение алертов
|
||||||
|
socket.on('server-alerts', (data) => {
|
||||||
|
console.log('Alerts:', data);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Система мониторинга
|
||||||
|
|
||||||
|
Мониторинг работает автоматически после запуска сервера:
|
||||||
|
|
||||||
|
1. **Периодическая проверка** - каждые 30 секунд проверяет все активные серверы
|
||||||
|
2. **Обновление БД** - сохраняет метрики (CPU, RAM, диск, сеть) в базу данных
|
||||||
|
3. **WebSocket broadcast** - отправляет обновления подключенным клиентам
|
||||||
|
4. **Алерты** - генерирует предупреждения при превышении 90% использования ресурсов
|
||||||
|
5. **Email уведомления** - отправляет письма при критических событиях
|
||||||
|
|
||||||
|
## Email уведомления
|
||||||
|
|
||||||
|
Система отправляет уведомления о:
|
||||||
|
- Создании нового сервера
|
||||||
|
- Превышении лимитов ресурсов (CPU/RAM/Disk > 90%)
|
||||||
|
- Приближении срока оплаты
|
||||||
|
- Ответах в тикетах поддержки
|
||||||
|
|
||||||
|
Для работы email требуется настройка SMTP в `.env`.
|
||||||
|
|
||||||
|
## Безопасность
|
||||||
|
|
||||||
|
- JWT токены для аутентификации
|
||||||
|
- Bcrypt для хеширования паролей
|
||||||
|
- CORS настроен для локальной разработки
|
||||||
|
- Proxmox API токены вместо паролей
|
||||||
|
- Автоматическая генерация безопасных паролей
|
||||||
|
|
||||||
|
## Разработка
|
||||||
|
|
||||||
|
### Запуск в dev режиме
|
||||||
|
|
||||||
|
Backend:
|
||||||
|
```bash
|
||||||
|
cd ospabhost/backend
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Frontend:
|
||||||
|
```bash
|
||||||
|
cd ospabhost/frontend
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### Сборка
|
||||||
|
|
||||||
|
Backend:
|
||||||
|
```bash
|
||||||
|
cd ospabhost/backend
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
Frontend:
|
||||||
|
```bash
|
||||||
|
cd ospabhost/frontend
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
### Линтинг
|
||||||
|
|
||||||
|
Frontend:
|
||||||
|
```bash
|
||||||
|
cd ospabhost/frontend
|
||||||
|
npm run lint
|
||||||
|
```
|
||||||
|
|
||||||
|
## Примеры использования
|
||||||
|
|
||||||
|
### Создание сервера
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const createServer = async () => {
|
||||||
|
const response = await fetch('http://localhost:5000/api/server/create', {
|
||||||
|
method: 'POST',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
'Authorization': `Bearer ${token}`
|
||||||
|
},
|
||||||
|
body: JSON.stringify({
|
||||||
|
osId: 1,
|
||||||
|
tariffId: 2
|
||||||
|
})
|
||||||
|
});
|
||||||
|
const server = await response.json();
|
||||||
|
console.log('Server created:', server);
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Создание снэпшота
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const createSnapshot = async (serverId) => {
|
||||||
|
const response = await fetch(`http://localhost:5000/api/server/${serverId}/snapshots`, {
|
||||||
|
method: 'POST',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
'Authorization': `Bearer ${token}`
|
||||||
|
},
|
||||||
|
body: JSON.stringify({
|
||||||
|
snapname: 'backup-before-update',
|
||||||
|
description: 'Before major system update'
|
||||||
|
})
|
||||||
|
});
|
||||||
|
const result = await response.json();
|
||||||
|
console.log('Snapshot created:', result);
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Real-time мониторинг
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
import { useServerStats } from './hooks/useSocket';
|
||||||
|
|
||||||
|
function ServerMonitor({ serverId }) {
|
||||||
|
const { stats, alerts, connected } = useServerStats(serverId);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div>
|
||||||
|
<div>Status: {connected ? 'Connected' : 'Disconnected'}</div>
|
||||||
|
<div>CPU: {stats?.data?.cpu * 100}%</div>
|
||||||
|
<div>RAM: {stats?.data?.memory?.usage}%</div>
|
||||||
|
{alerts.map(alert => (
|
||||||
|
<div key={alert.type}>Alert: {alert.message}</div>
|
||||||
|
))}
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Backend не подключается к Proxmox
|
||||||
|
- Проверьте PROXMOX_API_URL в .env
|
||||||
|
- Убедитесь, что API токен действителен
|
||||||
|
- Проверьте сетевую доступность Proxmox сервера
|
||||||
|
|
||||||
|
### WebSocket не подключается
|
||||||
|
- Убедитесь, что backend запущен
|
||||||
|
- Проверьте CORS настройки в backend/src/index.ts
|
||||||
|
- Проверьте firewall rules
|
||||||
|
|
||||||
|
### Email уведомления не отправляются
|
||||||
|
- Проверьте SMTP настройки в .env
|
||||||
|
- Для Gmail используйте App Password, не обычный пароль
|
||||||
|
- Проверьте логи сервера на ошибки
|
||||||
|
|
||||||
|
## Лицензия
|
||||||
|
|
||||||
|
MIT
|
||||||
|
|
||||||
|
## Поддержка
|
||||||
|
|
||||||
|
Для вопросов и поддержки создайте issue в репозитории или свяжитесь с командой разработки.
|
||||||
534
ospabhost/backend/API_DOCUMENTATION.md
Normal file
534
ospabhost/backend/API_DOCUMENTATION.md
Normal file
@@ -0,0 +1,534 @@
|
|||||||
|
# API Documentation - Server Management
|
||||||
|
|
||||||
|
## Base URL
|
||||||
|
```
|
||||||
|
http://localhost:5000/api
|
||||||
|
```
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
All endpoints require Bearer token authentication via the Authorization header:
|
||||||
|
```
|
||||||
|
Authorization: Bearer <access_token>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Server Management Endpoints
|
||||||
|
|
||||||
|
### 1. Get All Servers
|
||||||
|
**GET** `/server`
|
||||||
|
|
||||||
|
Returns a list of all servers for the authenticated user.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"userId": 1,
|
||||||
|
"tariffId": 2,
|
||||||
|
"osId": 1,
|
||||||
|
"status": "running",
|
||||||
|
"proxmoxId": 100,
|
||||||
|
"ipAddress": "10.0.0.5",
|
||||||
|
"rootPassword": "encrypted_password",
|
||||||
|
"createdAt": "2024-01-01T00:00:00.000Z",
|
||||||
|
"updatedAt": "2024-01-01T00:00:00.000Z",
|
||||||
|
"os": {
|
||||||
|
"id": 1,
|
||||||
|
"name": "Ubuntu 22.04",
|
||||||
|
"type": "linux"
|
||||||
|
},
|
||||||
|
"tariff": {
|
||||||
|
"id": 2,
|
||||||
|
"name": "Базовый",
|
||||||
|
"price": 300
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. Get Server Details
|
||||||
|
**GET** `/server/:id`
|
||||||
|
|
||||||
|
Returns detailed information about a specific server.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"status": "running",
|
||||||
|
"proxmoxId": 100,
|
||||||
|
"ipAddress": "10.0.0.5",
|
||||||
|
"createdAt": "2024-01-01T00:00:00.000Z",
|
||||||
|
"os": { "name": "Ubuntu 22.04", "type": "linux" },
|
||||||
|
"tariff": { "name": "Базовый", "price": 300 }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Get Server Status and Statistics
|
||||||
|
**GET** `/server/:id/status`
|
||||||
|
|
||||||
|
Returns real-time status and resource usage statistics.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"status": "running",
|
||||||
|
"stats": {
|
||||||
|
"status": "success",
|
||||||
|
"data": {
|
||||||
|
"vmid": 100,
|
||||||
|
"status": "running",
|
||||||
|
"uptime": 3600,
|
||||||
|
"cpu": 0.15,
|
||||||
|
"memory": {
|
||||||
|
"used": 536870912,
|
||||||
|
"max": 2147483648,
|
||||||
|
"usage": 25.0
|
||||||
|
},
|
||||||
|
"disk": {
|
||||||
|
"used": 5368709120,
|
||||||
|
"max": 21474836480,
|
||||||
|
"usage": 25.0
|
||||||
|
},
|
||||||
|
"network": {
|
||||||
|
"in": 104857600,
|
||||||
|
"out": 52428800
|
||||||
|
},
|
||||||
|
"rrdData": [...]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. Create New Server
|
||||||
|
**POST** `/server/create`
|
||||||
|
|
||||||
|
Creates a new LXC container.
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"osId": 1,
|
||||||
|
"tariffId": 2
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"status": "creating",
|
||||||
|
"proxmoxId": 100,
|
||||||
|
"ipAddress": null,
|
||||||
|
"rootPassword": "generated_password"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 5. Start Server
|
||||||
|
**POST** `/server/:id/start`
|
||||||
|
|
||||||
|
Starts a stopped server.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"action": "start",
|
||||||
|
"taskId": "UPID:..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 6. Stop Server
|
||||||
|
**POST** `/server/:id/stop`
|
||||||
|
|
||||||
|
Stops a running server.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"action": "stop",
|
||||||
|
"taskId": "UPID:..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 7. Restart Server
|
||||||
|
**POST** `/server/:id/restart`
|
||||||
|
|
||||||
|
Restarts a server.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"action": "restart",
|
||||||
|
"taskId": "UPID:..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 8. Delete Server
|
||||||
|
**DELETE** `/server/:id`
|
||||||
|
|
||||||
|
Permanently deletes a server and its container.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "deleted"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 9. Change Root Password
|
||||||
|
**POST** `/server/:id/password`
|
||||||
|
|
||||||
|
Generates and sets a new root password for the server.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"password": "new_generated_password"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 10. Resize Server Configuration
|
||||||
|
**PUT** `/server/:id/resize`
|
||||||
|
|
||||||
|
Changes server resources (CPU, RAM, disk).
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"cores": 4,
|
||||||
|
"memory": 4096,
|
||||||
|
"disk": 80
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Note: All fields are optional. Only specified fields will be updated.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"data": "..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 11. Create Snapshot
|
||||||
|
**POST** `/server/:id/snapshots`
|
||||||
|
|
||||||
|
Creates a snapshot of the server's current state.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"snapname": "backup-2024-01-01",
|
||||||
|
"description": "Before major update"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"taskId": "UPID:...",
|
||||||
|
"snapname": "backup-2024-01-01"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 12. List Snapshots
|
||||||
|
**GET** `/server/:id/snapshots`
|
||||||
|
|
||||||
|
Returns a list of all snapshots for the server.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"data": [
|
||||||
|
{
|
||||||
|
"name": "backup-2024-01-01",
|
||||||
|
"description": "Before major update",
|
||||||
|
"snaptime": 1704067200
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 13. Rollback Snapshot
|
||||||
|
**POST** `/server/:id/snapshots/rollback`
|
||||||
|
|
||||||
|
Restores the server to a previous snapshot state.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"snapname": "backup-2024-01-01"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"taskId": "UPID:..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 14. Delete Snapshot
|
||||||
|
**DELETE** `/server/:id/snapshots`
|
||||||
|
|
||||||
|
Deletes a specific snapshot.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `id` (path) - Server ID
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"snapname": "backup-2024-01-01"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"taskId": "UPID:..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 15. Get Console Access
|
||||||
|
**POST** `/server/console`
|
||||||
|
|
||||||
|
Returns a URL for accessing the server console via noVNC.
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"vmid": 100
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"url": "https://proxmox.example.com/?console=lxc&vmid=100&node=proxmox&ticket=..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## WebSocket Events
|
||||||
|
|
||||||
|
### Connection
|
||||||
|
Connect to `http://localhost:5000` with Socket.IO client.
|
||||||
|
|
||||||
|
### Subscribe to Server Updates
|
||||||
|
```javascript
|
||||||
|
socket.emit('subscribe-server', serverId);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Unsubscribe from Server Updates
|
||||||
|
```javascript
|
||||||
|
socket.emit('unsubscribe-server', serverId);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Receive Server Statistics
|
||||||
|
```javascript
|
||||||
|
socket.on('server-stats', (data) => {
|
||||||
|
console.log(data);
|
||||||
|
// {
|
||||||
|
// serverId: 1,
|
||||||
|
// stats: { ... }
|
||||||
|
// }
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Receive Server Alerts
|
||||||
|
```javascript
|
||||||
|
socket.on('server-alerts', (data) => {
|
||||||
|
console.log(data);
|
||||||
|
// {
|
||||||
|
// serverId: 1,
|
||||||
|
// alerts: [
|
||||||
|
// { type: 'cpu', message: 'CPU usage is at 95%', level: 'warning' }
|
||||||
|
// ]
|
||||||
|
// }
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Responses
|
||||||
|
|
||||||
|
All endpoints may return error responses in the following format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": "Error message description"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Common HTTP status codes:
|
||||||
|
- `200` - Success
|
||||||
|
- `400` - Bad Request (invalid parameters)
|
||||||
|
- `401` - Unauthorized (invalid or missing token)
|
||||||
|
- `404` - Not Found (resource doesn't exist)
|
||||||
|
- `500` - Internal Server Error
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Email Notifications
|
||||||
|
|
||||||
|
The system automatically sends email notifications for:
|
||||||
|
- Server creation
|
||||||
|
- Resource usage alerts (CPU/Memory/Disk > 90%)
|
||||||
|
- Payment reminders
|
||||||
|
- Support ticket responses
|
||||||
|
|
||||||
|
Email notifications require SMTP configuration in `.env`:
|
||||||
|
```
|
||||||
|
SMTP_HOST=smtp.gmail.com
|
||||||
|
SMTP_PORT=587
|
||||||
|
SMTP_USER=your-email@gmail.com
|
||||||
|
SMTP_PASS=your-app-password
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Monitoring Service
|
||||||
|
|
||||||
|
The monitoring service runs automatically and:
|
||||||
|
- Checks all servers every 30 seconds
|
||||||
|
- Updates database with current metrics
|
||||||
|
- Broadcasts real-time updates via WebSocket
|
||||||
|
- Sends alerts when resource usage exceeds 90%
|
||||||
|
- Sends email notifications for critical alerts
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Resource Management**: Always check server status before performing actions (start/stop/restart)
|
||||||
|
2. **Snapshots**: Create snapshots before major changes or updates
|
||||||
|
3. **Monitoring**: Subscribe to WebSocket updates for real-time monitoring
|
||||||
|
4. **Error Handling**: Always handle potential errors from API calls
|
||||||
|
5. **Authentication**: Store and refresh access tokens securely
|
||||||
|
6. **Rate Limiting**: Avoid excessive API calls; use WebSocket for real-time data
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example Usage
|
||||||
|
|
||||||
|
### JavaScript/TypeScript Example
|
||||||
|
```typescript
|
||||||
|
import axios from 'axios';
|
||||||
|
import { io } from 'socket.io-client';
|
||||||
|
|
||||||
|
const API_URL = 'http://localhost:5000/api';
|
||||||
|
const token = localStorage.getItem('access_token');
|
||||||
|
|
||||||
|
// Get server status
|
||||||
|
const getServerStatus = async (serverId: number) => {
|
||||||
|
const response = await axios.get(
|
||||||
|
`${API_URL}/server/${serverId}/status`,
|
||||||
|
{
|
||||||
|
headers: { Authorization: `Bearer ${token}` }
|
||||||
|
}
|
||||||
|
);
|
||||||
|
return response.data;
|
||||||
|
};
|
||||||
|
|
||||||
|
// Subscribe to real-time updates
|
||||||
|
const socket = io('http://localhost:5000');
|
||||||
|
socket.emit('subscribe-server', 1);
|
||||||
|
socket.on('server-stats', (data) => {
|
||||||
|
console.log('Real-time stats:', data);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Create snapshot
|
||||||
|
const createSnapshot = async (serverId: number) => {
|
||||||
|
const response = await axios.post(
|
||||||
|
`${API_URL}/server/${serverId}/snapshots`,
|
||||||
|
{
|
||||||
|
snapname: `backup-${Date.now()}`,
|
||||||
|
description: 'Automatic backup'
|
||||||
|
},
|
||||||
|
{
|
||||||
|
headers: { Authorization: `Bearer ${token}` }
|
||||||
|
}
|
||||||
|
);
|
||||||
|
return response.data;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Last updated: 2024
|
||||||
|
Version: 8.1
|
||||||
Reference in New Issue
Block a user