mirvmon/TECHNICAL_SPECIFICATION.md

ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Система мониторинга серверов

1. Общие требования

• Язык: PHP 8.1+
• Фреймворк: Slim Framework 4 (с PSR-7, Twig)
• Фронтенд: Bootstrap 5, Font Awesome 6 (через CDN), Chart.js для графиков
• База данных: MySQL 8+ / MariaDB 10.5+
• Архитектура: MVC в рамках Slim (Controllers, Models, Templates)
• Интерфейс: Полностью на русском языке (все надписи, кнопки, формы, меню)
• Безопасность: Prepared Statements для всех SQL-запросов, хеши паролей (password_hash), токены агентов хранятся только как SHA-256 хеши.

2. Структура базы данных (8 таблиц)

Таблица	Поля (ключевые)	Назначение
users	id, username (unique), password_hash, email, role(admin/user), created_at	Управление доступом
user_notification_settings	id, user_id, telegram_chat_id, email_for_alerts	Персональные настройки уведомлений
server_groups	id, name, description, icon, color	Группировка серверов
servers	id, name, address (nullable), group_id, description, last_metrics_at, created_at	Основные данные серверов
metric_names	id, name (unique), unit, description	Справочник метрик (cpu_load, ram_used, …)
metric_thresholds	id, server_id, metric_name_id, warning_threshold, critical_threshold, duration	Индивидуальные пороги для каждой метрики на каждом сервере
server_metrics	id, server_id, metric_name_id, value, created_at	Исторические данные метрик (с индексом (server_id, metric_name_id, created_at))
agent_tokens	id, server_id (unique), token_hash, created_at, last_used_at	Хеши токенов для авторизации агентов
alerts	id, server_id, metric_name, value, severity(warning/critical), resolved, created_at, resolved_at	История срабатывания алертов

3. Функциональные модули (что должна делать система)

3.1. Аутентификация и авторизация

• Доступ ко всем страницам, кроме /login и /api/v1/metrics, только после входа.
• Сессионная авторизация с middleware.

3.2. Дашборд (главная страница /)

• Цветные карточки серверов (Bootstrap cards):
  • Зеленый: last_metrics_at < 2 мин назад И все метрики ниже порогов.
  • Желтый: метрики свежие (<2 мин), но есть превышение порогов.
  • Красный: last_metrics_at > 5 мин назад (сервер «молчит»).
• В карточке: имя сервера, текущие значения CPU/RAM, время последнего обновления.
• Автообновление каждые 30 секунд (через setTimeout).

3.3. Управление серверами

• Добавление сервера: форма с полями (имя, адрес опционально, группа, описание).
• После сохранения:
  1. Генерация уникального токена (32 символа).
  2. Сохранение хеша токена в agent_tokens.
  3. Показ пользователю: «Токен для агента: [токен]. Скачайте скрипт установки: [install.sh?token=...]».
• Редактирование сервера: возможность изменить все поля, повторно скачать скрипт (токен остается прежним).

3.4. API для агентов

• Эндпоинт: POST /api/v1/metrics (публичный, без авторизации сессии).
• Ожидаемый JSON: {"token": "...", "metrics": {"cpu_load": 45.2, "ram_used": 89.1}}.
• Логика:
  1. Проверка токена (сравнение хеша).
  2. Обновление servers.last_metrics_at и agent_tokens.last_used_at.
  3. Сохранение каждой метрики в server_metrics.
  4. Проверка порогов: если значение превышает warning_threshold из metric_thresholds → создание записи в alerts.

3.5. Агент мониторинга

• Скрипт установки: GET /agent/install.sh?token=... → динамически генерирует bash-скрипт, который:
  1. Устанавливает Python3, psutil, lm-sensors, smartmontools.
  2. Скачивает Python-агента (agent.py) с вашего сервера.
  3. Подставляет токен и URL API в конфиг агента.
  4. Создает systemd-сервис для автостарта.
• Python-агент: собирает CPU, RAM, Disk, Network, Temperature раз в 60 секунд, отправляет на /api/v1/metrics.

3.6. Страница сервера (/server/{id})

• Текущие значения всех метрик.
• Графики Chart.js для метрик:
  • По умолчанию — последние 24 часа.
  • Кнопки выбора периода: 24 часа, 7 дней, 30 дней (через параметр ?period=7d).
  • Управление порогами: форма настройки warning_threshold и duration для каждой метрики этого сервера (сохраняет в metric_thresholds).

3.7. Система алертов

• Автоматическое создание при превышении порога.
• Страница /alerts: список активных алертов с кнопкой «Исправлено» (помечает resolved=1).
• Логика статуса на дашборде учитывает только неисправленные (resolved=0) алерты.

3.8. Уведомления

• Email: отправка через SMTP (PHPMailer) при срабатывании алерта.
• Telegram Bot: отправка сообщения в заданный чат.
• Настройка: в админке (/admin/notifications) указываются: SMTP параметры, Telegram Bot Token, Chat ID.

3.9. Администрирование

• CRUD пользователей: страница /admin/users (только для role='admin').
• Управление группами серверов.
• Повторная выдача скрипта: на странице сервера кнопка «Скачать скрипт агента».

---

План поэтапной реализации (9 этапов)

Этап 1: Ядро системы

• Цель: Slim Framework + Twig + Bootstrap работают.
• Результат: Открываю http://localhost:8080/test → вижу «Система мониторинга».
• ✅ Выполнен

Этап 2: База данных

• Цель: Все 8 таблиц созданы.
• Результат: Импорт schema.sql → в MySQL есть все таблицы, включая metric_names с записями «cpu_load», «ram_used».
• ✅ Выполнен

Этап 3: Аутентификация + CRUD групп

• Цель: Вход/выход, управление группами.
• Результат:
  1. Неавторизован → редирект на /login (форма на русском).
  2. Вход как admin:123 → переход на дашборд.
  3. Меню «Группы» → создаю группу «Веб-серверы» → она отображается в списке.
• ✅ Выполнен

Этап 4: CRUD серверов + генерация токена

• Цель: Добавление сервера с получением токена.
• Результат:
  1. Форма «Добавить сервер» → заполняю → нажимаю «Сохранить».
  2. Вижу страницу: «Сервер добавлен. Токен: abc123... Скачайте скрипт: [install.sh?token=abc123...]».
  3. Перехожу по ссылке → скачивается install.sh.
• ✅ Выполнен

Этап 5: API + логика статусов

• Цель: Приём метрик, цветные карточки на дашборде.
• Результат:
  1. Через curl отправляю метрики с токеном.
  2. Обновляю дашборд → вижу карточку сервера зелёного цвета (метрики в норме).
  3. Отправляю cpu_load: 95 → карточка становится жёлтой.
• ✅ Выполнен

Этап 6: Агент и скрипт установки

• Цель: Рабочий агент, отправляющий метрики каждые 10 сек.
• Результат:
  1. В виртуальной машине запускаю bash install.sh → устанавливается Python-агент.
  2. systemctl status server-mon-agent → сервис работает.
  3. В логах агента вижу: «Отправлено: cpu_load=12.3» каждые 10 сек.
• ✅ Выполнен

Этап 7: Детали сервера + графики

• Цель: Страница с графиками и выбором периода.
• Результат:
  1. Кликаю на карточку сервера → открывается /server/1.
  2. Вижу график CPU за 24 часа.
  3. Нажимаю «7 дней» → график перерисовывается за неделю.
• ✅ Выполнен

Этап 8: Пороги и алерты

• Цель: Настройка порогов, срабатывание алертов.
• Результат:
  1. На странице сервера ставлю порог CPU: 80%.
  2. Отправляю метрику cpu_load: 90 → в таблице alerts появляется запись.
  3. Страница /alerts показывает «Превышение CPU на сервере X».
• ✅ Выполнен

Этап 9: Уведомления + админка

• Цель: Отправка email/Telegram, управление пользователями.
• Результат:
  1. В админке указываю свой Telegram Chat ID.
  2. При срабатывании алерта получаю сообщение в Telegram.
  3. В меню «Админка» → «Пользователи» создаю нового пользователя.
• ✅ Выполнен

---

История реализации

Выполненные этапы:

• ✅ Этап 1: Ядро системы (Slim Framework 4, Twig, Bootstrap 5, Font Awesome 6)
• ✅ Этап 2: База данных (схема создана, 8 таблиц, стандартные метрики)
• ✅ Этап 3: Аутентификация и авторизация (middleware, формы входа/выхода, CRUD групп)
• ✅ Этап 4: CRUD серверов (добавление/редактирование/удаление, генерация токенов)
• ✅ Этап 5: API для агентов (прием метрик, проверка токенов, обновление статусов)
• ✅ Этап 6: Скрипт установки агента (динамическая генерация bash-скрипта)
• ✅ Этап 7: Детали сервера и графики (страница с метриками и графиками Chart.js)
• ✅ Этап 8: Система алертов (обнаружение превышений, страница алертов)
• ✅ Этап 9: Администрирование (управление пользователями, настройки уведомлений)

Архитектура:

• Frontend: Bootstrap 5, Font Awesome 6, Chart.js (через CDN)
• Backend: Slim Framework 4, Twig templates, PSR-7
• Database: MySQL/MariaDB с 8 таблицами
• Security: Password hashing, SHA-256 token hashes, prepared statements
• Language: Полный перевод интерфейса на русский язык

Компоненты:

• Веб-интерфейс для управления серверами и мониторинга
• API для приема метрик от агентов
• Скрипт установки агента для мониторинга серверов
• Система алертов и уведомлений
• Административная панель