diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..3a68b1a --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,353 @@ +# ARCHITECTURE.md — Система мониторинга серверов (mirvmon) + +**Домен:** `mon.mirv.top` +**Версия:** 1.0 +**Дата:** Февраль 2026 +**Статус:** Production + +--- + +## 📋 Обзор + +Система мониторинга серверов на базе **Slim Framework 4** с веб-интерфейсом для управления серверами, сбора метрик, визуализации данных и системы алертов. + +### Ключевые возможности +- Веб-интерфейс на русском языке (Bootstrap 5 + Chart.js) +- REST API для приёма метрик от агентов +- Python-агент для сбора CPU/RAM/Disk метрик +- Система алертов с настраиваемыми порогами +- Уведомления (Email/Telegram) +- Ролевая модель (admin/user) + +--- + +## 🏗️ Архитектура + +### Общая схема +``` +┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ +│ Python Agent │─────▶│ API /metrics │─────▶│ Database │ +│ (каждые 10с) │ HTTP │ (public) │ │ (MySQL) │ +└─────────────────┘ └──────────────────┘ └─────────────────┘ + ▲ +┌─────────────────┐ ┌──────────────────┐ │ +│ Web Browser │─────▶│ Slim Framework │────────────┘ +│ (Dashboard) │ HTTP │ (PHP 8.1+) │ +└─────────────────┘ └──────────────────┘ +``` + +### Технологический стек +| Компонент | Технология | Версия | +|-----------|------------|--------| +| Backend | Slim Framework | 4.x | +| Templating | Twig | 3.x | +| Frontend | Bootstrap | 5.x | +| Графики | Chart.js | 4.x | +| Icons | Font Awesome | 6.x | +| Database | MySQL/MariaDB | 8+ / 10.5+ | +| Agent | Python + psutil | 3.x | + +--- + +## 📁 Структура проекта + +``` +/var/www/mon/ +├── public/ # Точка входа (nginx root) +│ └── index.php # Bootstrap приложения +├── src/ +│ ├── Controllers/ # Контроллеры (MVC) +│ │ ├── DashboardController.php +│ │ ├── ServerController.php +│ │ ├── ServerDetailController.php +│ │ ├── GroupController.php +│ │ ├── AlertController.php +│ │ ├── AdminController.php +│ │ ├── AgentController.php +│ │ └── Api/ +│ │ └── MetricsController.php +│ ├── Models/ # Модели данных +│ │ ├── Model.php # Базовый класс +│ │ ├── User.php +│ │ ├── Server.php +│ │ ├── Group.php +│ │ └── Alert.php +│ ├── Middlewares/ # Middleware +│ │ ├── SessionMiddleware.php +│ │ ├── AuthMiddleware.php +│ │ └── CsrfMiddleware.php +│ └── Utils/ # Утилиты +│ └── EncryptionHelper.php +├── templates/ # Twig шаблоны +│ ├── layout.twig # Основной layout +│ ├── login.twig +│ ├── dashboard.twig +│ ├── servers/ # Шаблоны серверов +│ ├── groups/ # Шаблоны групп +│ ├── alerts/ # Шаблоны алертов +│ └── admin/ # Админка +├── config/ # Конфигурация +├── agent.py # Python-агент +├── composer.json # PHP зависимости +├── schema.sql # Схема БД +└── TECHNICAL_SPECIFICATION.md # ТЗ +``` + +--- + +## 🗄️ База данных (8 таблиц) + +### Схема +``` +users # Пользователи (admin/user) +├── id, username (unique), password_hash, email, role + +user_notification_settings # Настройки уведомлений +├── id, user_id, telegram_chat_id, email_for_alerts + +server_groups # Группы серверов +├── id, name, description, icon, color + +servers # Серверы +├── id, name, address, group_id, description, last_metrics_at + +metric_names # Справочник метрик +├── id, name (unique), unit, description + +metric_thresholds # Пороги для серверов +├── id, server_id, metric_name_id, warning_threshold, critical_threshold, duration + +server_metrics # История метрик +├── id, server_id, metric_name_id, value, created_at + +agent_tokens # Токены агентов (хеши) +├── id, server_id (unique), token_hash (SHA-256), created_at, last_used_at + +alerts # Алерты +├── id, server_id, metric_name, value, severity, resolved, created_at, resolved_at +``` + +### Индексы +- `server_metrics(server_id, metric_name_id, created_at)` — для быстрого поиска по периоду +- `servers(last_metrics_at)` — для фильтрации статусов +- `alerts(resolved, created_at)` — для списка активных алертов + +--- + +## 🔐 Безопасность + +### Аутентификация +- Сессионная авторизация (`$_SESSION`) +- Хеширование паролей: `password_hash()` (bcrypt) +- Middleware `AuthMiddleware` защищает все маршруты кроме `/login`, `/api/v1/metrics` + +### CSRF защита +- Slim CSRF Guard с персистентными токенами +- AJAX endpoint `/csrf-token` для получения токенов +- Формы включают CSRF токены + +### Токены агентов +- Хранятся только как **SHA-256 хеши** в `agent_tokens` +- Исходный токен показывается пользователю **однократно** при создании сервера +- API `/api/v1/metrics` проверяет хеш, не требует сессии + +### SQL инъекции +- Prepared statements (PDO) во всех запросах +- Базовый класс `Model` предоставляет методы `fetchAll()`, `fetchOne()`, `insert()`, `update()` + +--- + +## 🌐 Маршруты (Routes) + +### Публичные (без авторизации) +| Метод | Путь | Контроллер | Описание | +|-------|------|------------|----------| +| GET | `/login` | — | Форма входа | +| POST | `/login` | — | Аутентификация | +| GET | `/logout` | — | Выход | +| POST | `/api/v1/metrics` | `MetricsController` | Приём метрик от агентов | +| GET | `/csrf-token` | — | Получить CSRF токен | + +### Защищённые (требуется вход) +| Метод | Путь | Контроллер | Описание | +|-------|------|------------|----------| +| GET | `/` | `DashboardController` | Дашборд (карточки серверов) | +| GET | `/server/{id}` | `ServerDetailController` | Детали сервера + графики | +| GET/POST | `/servers/create` | `ServerController` | Добавить сервер | +| GET/POST | `/servers/{id}/edit` | `ServerController` | Редактировать сервер | +| GET/POST | `/servers/{id}/delete` | `ServerController` | Удалить сервер | +| GET/POST | `/groups` | `GroupController` | Управление группами | +| GET | `/alerts` | `AlertController` | Список алертов | +| POST | `/alerts/{id}/resolve` | `AlertController` | Пометить алерт исправленным | +| GET | `/admin/users` | `AdminController` | Пользователи (admin only) | +| GET | `/admin/notifications` | `AdminController` | Настройки уведомлений | + +--- + +## 🤖 Агент мониторинга + +### agent.py +**Расположение:** `/var/www/mon/agent.py` + +**Функции:** +- Сбор метрик каждые 10 секунд: + - `cpu_load` — загрузка CPU (%) + - `ram_used` — использовано RAM (%) + - `disk_used` — использовано Disk (%) +- Отправка на `POST /api/v1/metrics` +- Конфигурация через JSON файл +- Автозапуск через systemd + +### install.sh +**Генерация:** `GET /agent/install.sh?token={token}` + +**Что делает:** +1. Проверяет Python 3 +2. Устанавливает `psutil` +3. Скачивает `agent.py` с сервера +4. Создаёт конфиг с токеном и URL +5. Создаёт systemd сервис `server-mon-agent.service` + +--- + +## 📊 Логика статусов серверов + +### Цвета карточек на дашборде +| Цвет | Условие | +|------|---------| +| 🟢 **Зелёный** | `last_metrics_at` < 2 мин И нет активных алертов | +| 🟡 **Жёлтый** | Метрики свежие, но есть алерты (warning/critical) | +| 🔴 **Красный** | `last_metrics_at` > 5 мин (сервер не отвечает) | + +### Проверка порогов +1. Агент отправляет метрику → `server_metrics` +2. Система ищет порог в `metric_thresholds` для этого сервера+метрики +3. Если `value > warning_threshold` → создаётся запись в `alerts` +4. Статус сервера обновляется на дашборде + +--- + +## 🎨 Frontend + +### Шаблоны Twig +- `layout.twig` — основной layout (меню, футер, подключение CSS/JS) +- `login-layout.twig` — упрощённый layout для страницы входа +- `dashboard.twig` — карточки серверов с автообновлением (30с) +- `servers/*.twig` — формы CRUD серверов +- `alerts/*.twig` — список алертов + +### JavaScript +- Chart.js для графиков (CPU/RAM/Disk за 24ч/7д/30д) +- Автообновление дашборда через `setTimeout` +- Внешний tooltip handler для загрузки данных процессов + +--- + +## 🚀 Развёртывание + +### Требования +- PHP 8.1+ с расширениями: pdo, pdo_mysql, mbstring +- Composer +- MySQL 8+ / MariaDB 10.5+ +- nginx + PHP-FPM +- Python 3 + pip (для агента) + +### Установка +```bash +# 1. Клонировать репозиторий +cd /var/www +git clone mon +cd mon + +# 2. Установить зависимости +composer install --no-dev + +# 3. Создать БД +mysql -u root -p < schema.sql + +# 4. Настроить nginx (см. /etc/nginx/sites-enabled/mon.mirv.top) + +# 5. Настроить PHP-FPM +# /run/php/php8.3-fpm.sock + +# 6. Получить SSL сертификат +certbot --nginx -d mon.mirv.top + +# 7. Создать админа +# Через phpMyAdmin или напрямую в MySQL +``` + +### Конфигурация nginx +- **Root:** `/var/www/mon/public` +- **PHP-FPM:** `unix:/run/php/php8.3-fpm.sock` +- **SSL:** Let's Encrypt +- **HTTP → HTTPS редирект** + +--- + +## 📈 Метрики + +### Стандартные метрики (metric_names) +| Имя | Единица | Описание | +|-----|---------|----------| +| `cpu_load` | % | Загрузка CPU | +| `ram_used` | % | Использовано RAM | +| `disk_used` | % | Использовано Disk | +| `top_cpu_proc` | JSON | Топ-5 процессов по CPU | +| `top_ram_proc` | JSON | Топ-5 процессов по RAM | + +### Период сбора +- **Агент:** каждые 10 секунд +- **Дашборд:** автообновление каждые 30 секунд +- **Графики:** 24 часа / 7 дней / 30 дней + +--- + +## 🔧 Расширение + +### Добавление новой метрики +1. Добавить запись в `metric_names` +2. Обновить агент для сбора метрики +3. Добавить отображение в шаблонах +4. Опционально: настроить пороги в `metric_thresholds` + +--- + +## 🐛 Известные проблемы + +### Исправленные +- ✅ CSRF token generation order (generateToken до getToken) +- ✅ PDO parameter naming (уникальные имена параметров) +- ✅ VARCHAR длина для service_name (255+) +- ✅ API endpoints без CSRF middleware + +### Требования к окружению +- PHP 8.3+ (проверено на php8.3-fpm) +- MariaDB 10.6+ (JSON функции для top_cpu_proc/top_ram_proc) + +--- + +## 📝 Changelog + +### v1.0 (Февраль 2026) +- ✅ Ядро системы (Slim 4 + Twig + Bootstrap 5) +- ✅ 8 таблиц базы данных +- ✅ Аутентификация и авторизация +- ✅ CRUD серверов и групп +- ✅ API для приёма метрик +- ✅ Python-агент с systemd +- ✅ Графики Chart.js (24ч/7д/30д) +- ✅ Система алертов с порогами +- ✅ Топ-5 процессов по CPU/RAM +- ✅ Уведомления (Email/Telegram) + +--- + +## 🔗 Ссылки + +- **Домен:** https://mon.mirv.top +- **Код:** `/var/www/mon/` +- **База данных:** MySQL (monitoring_system) +- **Агент:** `/var/www/mon/agent.py` +- **Схема:** `/var/www/mon/schema.sql` +- **ТЗ:** `/var/www/mon/TECHNICAL_SPECIFICATION.md`