ospab.host/ospabhost/METRICS_GUIDE.md

Система статистики и мониторинга серверов

📊 Что добавлено

Backend (API):

1. Новая модель Prisma: ServerMetric

   • Хранит историю метрик каждого сервера
   • Поля: CPU, Memory, Disk, Network, Status, Uptime
   • Автоматическое удаление при удалении сервера (CASCADE)

2. 3 новых API endpoint'а:

   • GET /api/server/:id/metrics - Получить текущие метрики (+ сохранение в БД)
   • GET /api/server/:id/metrics/history?period=24h - История за период (1h, 6h, 24h, 7d, 30d)
   • GET /api/server/:id/metrics/summary - Сводка за 24 часа (средние, макс, мин)

3. Автоматическое сохранение:

   • При каждом запросе текущих метрик данные сохраняются в БД
   • Создаётся точка для графиков

Frontend (React):

1. Компонент ServerMetrics.tsx:

   • 4 карточки с текущими показателями (CPU, RAM, Disk, Network)
   • Цветовая индикация нагрузки (зелёный/жёлтый/красный)
   • Фильтр периода (1 час, 6 часов, 24 часа, 7 дней, 30 дней)
   • 3 интерактивных графика (Recharts):
     • CPU Usage (Area Chart)
     • Memory + Disk (Line Chart)
     • Network Traffic (Area Chart)
   • Автообновление каждую минуту

2. Интеграция:

   • Встроен в панель управления сервером
   • Вкладка "Мониторинг" теперь показывает реальные данные

🚀 Установка

1. SQL миграция:

cd /var/www/ospab-host/backend
mysql -u root -p ospabhost < prisma/migrations/add_server_metrics.sql

2. Обновление Prisma:

cd /var/www/ospab-host/backend
npx prisma generate

3. Сборка backend:

npm run build
pm2 restart ospab-backend

4. Сборка frontend:

cd /var/www/ospab-host/frontend
npm install recharts
npm run build
# Деплой dist/

📈 Как работает

Сбор данных:

1. Frontend запрашивает /api/server/:id/metrics
2. Backend получает данные от Proxmox API
3. Данные сохраняются в таблицу server_metrics
4. Возвращаются пользователю

Графики:

1. Frontend запрашивает историю за период
2. Backend агрегирует данные с интервалами:
   • 1h → каждую минуту
   • 6h → каждые 5 минут
   • 24h → каждые 15 минут
   • 7d → каждый час
   • 30d → каждые 6 часов
3. Recharts строит интерактивные графики

Автоочистка (рекомендуется):

Добавьте cron-задачу для удаления старых метрик:

-- Удалять метрики старше 30 дней
DELETE FROM server_metrics WHERE timestamp < DATE_SUB(NOW(), INTERVAL 30 DAY);

Или в crontab:

0 2 * * * mysql -u root -pПАРОЛЬ ospabhost -e "DELETE FROM server_metrics WHERE timestamp < DATE_SUB(NOW(), INTERVAL 30 DAY);"

🎨 Внешний вид

Карточки метрик:

• CPU: Процент загрузки с цветовой индикацией
• Память: Процент + используемый объём / всего
• Диск: Процент + используемый объём / всего
• Сеть: Входящий/исходящий трафик + Uptime

Графики:

• CPU: Плавная заливка оранжевым
• Memory/Disk: Двойной линейный график (синий/зелёный)
• Network: Двойная заливка (фиолетовый/розовый)

🔧 API примеры

Получить текущие метрики:

curl -H "Authorization: Bearer TOKEN" \
  http://localhost:5000/api/server/1/metrics

Ответ:

{
  "status": "success",
  "data": {
    "vmid": 105,
    "status": "running",
    "uptime": 3600,
    "cpu": 0.15,
    "memory": {
      "used": 536870912,
      "max": 1073741824,
      "usage": 50.0
    },
    "disk": {
      "used": 2147483648,
      "max": 10737418240,
      "usage": 20.0
    },
    "network": {
      "in": 1048576,
      "out": 524288
    }
  }
}

Получить историю:

curl -H "Authorization: Bearer TOKEN" \
  "http://localhost:5000/api/server/1/metrics/history?period=24h"

Ответ:

{
  "status": "success",
  "period": "24h",
  "data": [
    {
      "timestamp": "2025-11-01T10:00:00.000Z",
      "cpuUsage": 15.2,
      "memoryUsage": 48.5,
      "diskUsage": 20.1,
      "networkIn": 1048576,
      "networkOut": 524288,
      "status": "running"
    }
  ],
  "total": 96
}

Получить сводку:

curl -H "Authorization: Bearer TOKEN" \
  http://localhost:5000/api/server/1/metrics/summary

Ответ:

{
  "status": "success",
  "data": {
    "cpu": { "avg": 12.5, "max": 45.2, "min": 2.1 },
    "memory": { "avg": 48.3, "max": 72.1, "min": 35.2 },
    "disk": { "avg": 20.0, "max": 21.5, "min": 19.8 },
    "network": {
      "totalIn": 104857600,
      "totalOut": 52428800
    },
    "uptime": 86400
  }
}

🔒 Безопасность

• ✅ Все endpoints требуют авторизации (authMiddleware)
• ✅ Пользователь видит только метрики своих серверов
• ✅ CASCADE DELETE - метрики удаляются вместе с сервером
• ✅ Нет лимитов на количество запросов (можно добавить rate limiting)

📊 База данных

Структура таблицы:

CREATE TABLE `server_metrics` (
  `id` INT AUTO_INCREMENT PRIMARY KEY,
  `serverId` INT NOT NULL,
  `cpuUsage` DOUBLE DEFAULT 0,
  `memoryUsage` DOUBLE DEFAULT 0,
  `memoryUsed` BIGINT DEFAULT 0,
  `memoryMax` BIGINT DEFAULT 0,
  `diskUsage` DOUBLE DEFAULT 0,
  `diskUsed` BIGINT DEFAULT 0,
  `diskMax` BIGINT DEFAULT 0,
  `networkIn` BIGINT DEFAULT 0,
  `networkOut` BIGINT DEFAULT 0,
  `status` VARCHAR(191) DEFAULT 'unknown',
  `uptime` BIGINT DEFAULT 0,
  `timestamp` DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
  INDEX `server_metrics_serverId_timestamp_idx` (`serverId`, `timestamp`),
  FOREIGN KEY (`serverId`) REFERENCES `server`(`id`) ON DELETE CASCADE
);

Размер записи: ~100 байт При частоте 1 метрика/минуту: ~144 KB/день/сервер

🎯 Рекомендации

1. Cron для сбора метрик: Создайте задачу, которая каждые 5 минут запрашивает метрики всех серверов:

   // backend/src/cron/collectMetrics.ts
   import { PrismaClient } from '@prisma/client';
   import { getContainerStats } from './modules/server/proxmoxApi';
   
   const prisma = new PrismaClient();
   
   async function collectAllMetrics() {
     const servers = await prisma.server.findMany({
       where: { status: 'running' }
     });
   
     for (const server of servers) {
       if (!server.proxmoxId) continue;
       try {
         const stats = await getContainerStats(server.proxmoxId);
         if (stats.status === 'success' && stats.data) {
           await prisma.serverMetric.create({ /* ... */ });
         }
       } catch (err) {
         console.error(`Ошибка сбора метрик для сервера ${server.id}:`, err);
       }
     }
   }
   
   // Запускать каждые 5 минут
   setInterval(collectAllMetrics, 5 * 60 * 1000);
   

2. Партиционирование таблицы (для высоких нагрузок):

   ALTER TABLE server_metrics
   PARTITION BY RANGE (YEAR(timestamp) * 100 + MONTH(timestamp)) (
     PARTITION p202511 VALUES LESS THAN (202512),
     PARTITION p202512 VALUES LESS THAN (202601),
     PARTITION pmax VALUES LESS THAN MAXVALUE
   );
   

3. Кэширование: Добавьте Redis для кэширования текущих метрик (TTL 30 секунд).

📝 Changelog

1 ноября 2025:

• ✅ Добавлена модель ServerMetric в Prisma
• ✅ Созданы 3 API endpoint'а для метрик
• ✅ Реализован компонент ServerMetrics с графиками
• ✅ Интегрирован в панель управления сервером
• ✅ Установлена библиотека Recharts для графиков
• ✅ Добавлена SQL миграция

🐛 Troubleshooting

Проблема: Графики не отображаются

• Проверьте консоль браузера на ошибки API
• Убедитесь, что сервер запущен и метрики собираются
• Проверьте, что таблица server_metrics создана

Проблема: "Cannot read property 'cpu' of undefined"

• Сервер ещё не имеет метрик в БД
• Подождите 1-2 минуты после создания сервера
• Вручную запросите /api/server/:id/metrics

Проблема: Слишком большая база данных

• Настройте автоочистку старых метрик (см. выше)
• Уменьшите частоту сбора данных
• Используйте партиционирование

🎉 Готово!

Теперь у вас полноценная система мониторинга с:

• ✅ Реал-тайм метриками
• ✅ Интерактивными графиками
• ✅ Историей данных
• ✅ Красивым интерфейсом
• ✅ Автоматическим обновлением

Пользователи могут отслеживать нагрузку на свои серверы в режиме реального времени! 🚀