diff --git a/README.md b/README.md new file mode 100644 index 0000000..d8b048b --- /dev/null +++ b/README.md @@ -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 ( +
+
Status: {connected ? 'Connected' : 'Disconnected'}
+
CPU: {stats?.data?.cpu * 100}%
+
RAM: {stats?.data?.memory?.usage}%
+ {alerts.map(alert => ( +
Alert: {alert.message}
+ ))} +
+ ); +} +``` + +## 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 в репозитории или свяжитесь с командой разработки. diff --git a/ospabhost/backend/API_DOCUMENTATION.md b/ospabhost/backend/API_DOCUMENTATION.md new file mode 100644 index 0000000..8dafa7a --- /dev/null +++ b/ospabhost/backend/API_DOCUMENTATION.md @@ -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 +``` + +--- + +## 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