Download the PHP package besnovatyj/yii2-cms-info without Composer

System Information Widget - Полная документация

Оглавление

• Обзор
• Архитектура
• Компоненты Backend
• Компоненты Frontend
• API Endpoints
• Конфигурация
• Метрики
• Безопасность
• Производительность
• Troubleshooting

Обзор

Виджет системной информации предоставляет комплексный мониторинг сервера в режиме реального времени через веб-интерфейс администратора.

Основные возможности

✅ Мониторинг в реальном времени

• Автоматическое обновление каждые 3 секунды
• Без кэширования - данные всегда актуальные
• Нет использования jQuery - только нативный TypeScript

✅ Метрики системы

• CPU: использование, модель, количество ядер, частота
• RAM: общая/используемая/свободная память, buffers, cached
• Disk: размер, использование, точка монтирования
• Load Average: 1/5/15 минут
• Network: статистика по интерфейсам (RX/TX)
• Temperature: температура процессора (если доступно)

✅ Метрики сервисов

• PHP: версия, SAPI, memory_limit, OPcache
• Nginx: версия, HTTP-протокол (HTTP/2), HTTPS, TLS-протокол/шифр текущего соединения
• MySQL: версия, размер БД, количество таблиц, соединения
• Redis: версия, uptime, клиенты, память, ключи
• Yii2: версия, окружение, debug, кэш, очередь

✅ Docker метрики

• Список всех контейнеров с их статусами
• Версия Docker
• Количество images, volumes, networks
• Просмотр логов контейнеров (100 последних строк)

✅ Визуализация

• Графики CPU/Memory (Chart.js) - 60 точек × 3 секунды = 3 минуты истории
• Bootstrap 5 интерфейс с вкладками
• Прогресс-бары с цветовой индикацией
• Responsive дизайн

✅ Дополнительные функции

• Экспорт метрик в JSON/CSV
• Настройка интервала обновления
• Пауза/возобновление auto-refresh
• Просмотр Docker логов в модальном окне

Архитектура

Clean Architecture Pattern

Проект следует принципам Clean Architecture с четким разделением слоев:

Принципы разделения ответственности

1. Providers - отвечают только за сбор raw данных из источников
2. Service - бизнес-логика, агрегация данных из провайдеров
3. Controller - HTTP слой, валидация запросов, отправка ответов
4. Frontend Components - UI логика, рендеринг, управление состоянием

Компоненты Backend

1. Metric Providers

BaseMetricProvider

Абстрактный базовый класс для всех провайдеров.

Расположение: /app/Besnovatyj/Info/providers/BaseMetricProvider.php

Ключевые методы:

Особенности:

• Все провайдеры stateless (без сохранения состояния)
• Встроенная обработка ошибок с try/catch
• Безопасное выполнение shell команд с timeout
• Форматирование байтов в человекочитаемый вид
• Метод isAvailable() проверяет доступность источника данных

SystemMetricProvider

Собирает метрики системы Linux из /proc.

Расположение: /app/Besnovatyj/Info/providers/SystemMetricProvider.php

Источники данных:

• /proc/cpuinfo - информация о процессоре
• /proc/stat - использование CPU
• /proc/meminfo - информация о памяти
• /proc/diskstats - статистика дисков
• /proc/loadavg - load average
• /proc/net/dev - сетевые интерфейсы
• /proc/uptime - время работы системы
• /sys/class/thermal/thermal_zone*/temp - температура

Прим.: обёртка phpUname() и явные проверки function_exists() для parse_ini_file/disk_*_space защищают от FPM-hardening (disable_functions) — при отключённой функции блок деградирует, а не роняет весь сбор метрик.

Возвращаемая структура:

PhpMetricProvider

Собирает информацию о PHP и его расширениях.

Расположение: /app/Besnovatyj/Info/providers/PhpMetricProvider.php

Источники данных:

• PHP_VERSION, PHP_SAPI, PHP_OS
• ini_get() для лимитов
• memory_get_usage(), memory_get_peak_usage()
• opcache_get_status() для OPcache статистики
• get_loaded_extensions() для списка расширений

Возвращаемая структура:

DockerMetricProvider

Собирает метрики Docker через Docker CLI.

Расположение: /app/Besnovatyj/Info/providers/DockerMetricProvider.php

Требования:

• Docker CLI установлен в контейнере
• Переменная окружения DOCKER_HOST=tcp://socket-proxy:2375
• Доступ к socket-proxy с разрешениями CONTAINERS, IMAGES, VOLUMES, NETWORKS

Команды:

Возвращаемая структура:

Методы:

• getContainerLogs(string $containerId, int $lines = 100) - получить логи контейнера

DatabaseMetricProvider

Собирает статистику MySQL/MariaDB.

Расположение: /app/Besnovatyj/Info/providers/DatabaseMetricProvider.php

Источники данных:

Возвращаемая структура:

RedisMetricProvider

Собирает статистику Redis через Yii2 Redis компонент.

Расположение: /app/Besnovatyj/Info/providers/RedisMetricProvider.php

Источники данных:

Возвращаемая структура:

NginxMetricProvider

Собирает информацию о веб-сервере Nginx.

Расположение: /src/providers/NginxMetricProvider.php

Источники данных (без shell, работает под FPM-hardening):

• $_SERVER['SERVER_SOFTWARE'] — версия (стоковый fastcgi_params передаёт nginx/$nginx_version)
• $_SERVER['SERVER_PROTOCOL'] — протокол запроса (HTTP/2.0, HTTP/1.1)
• $_SERVER['HTTPS'] / REQUEST_SCHEME / SERVER_PORT — признак TLS
• $_SERVER['SSL_PROTOCOL'] / SSL_CIPHER — живой TLS-протокол и шифр (только если проброшены через fastcgi_param, см. ниже)

Резервные источники (если бинарь nginx доступен из PHP и shell_exec не в disable_functions):

• nginx -v — версия, когда SERVER_SOFTWARE скрыт/переопределён
• nginx -V — TLS-библиотека сборки (OpenSSL) и число --with-*_module

Если бинарь nginx недоступен из PHP-процесса (nginx и PHP разнесены, либо shell_exec отключён), резервные вызовы тихо деградируют в null — версия берётся из SERVER_SOFTWARE.

Возвращаемая структура:

Состояния tls.state (для отладки конфигурации):

Проброс живого TLS (опционально). Стоковый fastcgi_params не передаёт TLS-параметры. Чтобы блок tls.state = ok заполнялся, добавьте внутри location ~ \.php$ (nginx наследует fastcgi_param от родителя только если в location нет собственных — а он есть):

Это read-only, несекретные значения (клиент их и так знает) — безопасно для production. Если TLS терминируется до nginx (reverse-proxy, балансировщик), эти переменные будут пустыми — провайдер покажет tls.state = plain, это ожидаемо.

ApplicationMetricProvider

Собирает информацию о Yii2 приложении.

Расположение: /app/Besnovatyj/Info/providers/ApplicationMetricProvider.php

Источники данных:

• Yii::getVersion()
• YII_ENV, YII_DEBUG
• Компоненты приложения (cache, session, queue)

Возвращаемая структура:

2. Service Layer

SysInfoService

Центральный сервис для агрегации всех метрик.

Расположение: /app/Besnovatyj/Info/services/SysInfoService.php

Инжектируемые зависимости (через DI):

Ключевые методы:

getAllMetrics(): array Возвращает полные метрики всех провайдеров.

getRealtimeMetrics(): array Возвращает только динамические метрики для auto-refresh (легковесный).

Отличие от getAllMetrics:

• Не возвращает статические данные (версии, hostname, конфигурацию)
• Размер ответа ~500 байт вместо ~2.5 Кб
• Вызывается каждые 3 секунды

exportToJson(): string Форматирует все метрики в JSON с pretty print.

exportToCsv(): string Конвертирует метрики в CSV формат (плоская структура).

3. Controller Layer

SysInfoController

HTTP контроллер для обработки запросов.

Расположение: /app/Besnovatyj/Info/controllers/backend/SysInfoController.php

Endpoints:

GET /info/backend/sys-info/index

Отображает главную страницу виджета.

Возвращает: HTML страницу с виджетом

GET /info/backend/sys-info/api-metrics

Полные метрики всех провайдеров.

Возвращает: JSON (~2.5 Кб)

GET /info/backend/sys-info/api-realtime

Легковесные метрики для auto-refresh.

Возвращает: JSON (~500 байт)

GET /info/backend/sys-info/api-docker-logs?container=name&lines=100

Логи Docker контейнера.

Параметры:

• container (required) - ID или имя контейнера
• lines (optional) - количество строк (max 1000)

Возвращает: JSON

GET /info/backend/sys-info/export-json

Экспорт метрик в JSON файл.

Возвращает: Файл metrics-2026-01-19-010000.json

GET /info/backend/sys-info/export-csv

Экспорт метрик в CSV файл.

Возвращает: Файл metrics-2026-01-19-010000.csv

4. Dependency Injection

Container Configuration

Расположение: /app/Besnovatyj/Info/config/container.php

Подключение в Module.php:

Компоненты Frontend

TypeScript Architecture

Проект использует современный TypeScript + Vite без jQuery.

Структура:

1. index.ts

Entry point приложения.

Особенности:

• Автоматическая инициализация при загрузке DOM
• Поддержка нескольких виджетов на странице
• Обработка ошибок инициализации

2. SysInfoWidget.ts

Главный класс виджета.

Зависимости:

Поля класса:

Lifecycle:

Ключевые методы:

setupEventHandlers() Привязывает обработчики к кнопкам:

• Refresh - перезагрузка метрик
• Pause/Resume - управление auto-refresh
• Settings - открытие модалки настроек
• Export JSON/CSV - экспорт данных

loadInitialMetrics() Загружает полные метрики через apiService.getAllMetrics()

updateRealtimeMetrics() Загружает легковесные метрики через apiService.getRealtimeMetrics()

updateUI(metrics) Обновляет DOM со всеми метриками:

3. ApiService.ts

HTTP клиент на базе Fetch API.

Конфигурация:

Методы:

getAllMetrics(): Promise<any>

getRealtimeMetrics(): Promise<any> То же самое, но для realtime endpoint.

getDockerLogs(container: string, lines: number): Promise<any>

Обработка ошибок:

4. MetricsRenderer.ts

Отвечает за рендеринг метрик в DOM.

Ключевые методы:

renderOverview(metrics) Рендерит вкладку Overview - краткая сводка.

Проверки:

renderSystem(metrics) Вкладка System - детальная информация о сервере и CPU.

renderResources(metrics) Вкладка Resources - память, диск, Load Average, сеть.

Особенности:

renderServices(metrics) Вкладка Services - PHP, Nginx, MySQL, Redis, Yii2.

Карточка Nginx показывает бейдж протокола (зелёный HTTP/2 или жёлтый с фактическим протоколом) и строку TLS по nginx.tls.state: ok → «протокол / шифр», plain → «запрос без TLS», absent → предупреждение «SSL_* не проброшен».

Проверка наличия полных данных:

Важно: При realtime обновлении сервисы не имеют полных данных, поэтому метод пропускает рендеринг если данных нет (не очищает DOM).

renderDocker(docker) Вкладка Docker - контейнеры с кнопками логов.

updateTimestamp(timestamp) Обновляет timestamp последнего обновления.

updateStatus(success, message?) Обновляет статус индикатор (зеленый/красный).

Вспомогательные методы:

renderHtml(elementId, html)

getProgressColor(percent)

5. ChartManager.ts

Управление графиками Chart.js.

Создание графиков:

Добавление точек данных:

Расчет CPU процента:

6. RealtimeUpdater.ts

Таймер для auto-refresh.

7. DockerLogsModal.ts

Модальное окно для просмотра логов Docker.

8. SettingsManager.ts

Управление пользовательскими настройками через localStorage.

9. ErrorHandler.ts

Централизованная обработка ошибок.

Build Configuration

package.json

tsconfig.json

vite.config.ts

API Endpoints

Полный список

Детали

GET /api-metrics

Response:

GET /api-realtime

Response:

Отличия:

• Не содержит статических данных (версии, конфигурацию)
• ~5x меньше размер
• Вызывается каждые 3 секунды

GET /api-docker-logs

Query параметры:

• container (string, required) - ID или имя контейнера
• lines (int, optional) - количество строк (default: 100, max: 1000)

Response:

Error response:

Конфигурация

Widget Configuration

Виджет конфигурируется через атрибут data-config:

Структура конфигурации:

Asset Bundle

SysInfoAsset.php:

Порядок загрузки:

1. Yii2 core JS
2. Bootstrap 5 CSS + JS
3. Chart.js (CDN)
4. Собственный JS bundle (ES6 module)

Метрики

System Metrics

CPU:

• Model name
• Cores count
• Frequency (MHz/GHz)
• Cache size
• BogoMIPS
• Current usage (user, system, idle, iowait, etc.)

Memory:

• Total/Used/Free (bytes + formatted)
• Usage percentage
• Buffers/Cached
• Available memory

Disk:

• Total/Used/Free space
• Usage percentage
• Mount point
• Filesystem

Load Average:

• 1/5/15 minutes

Network:

• Per interface RX/TX bytes
• Formatted sizes

Temperature:

• CPU temperature (Celsius)

Uptime:

• Seconds + formatted string

PHP Metrics

• Version, SAPI, OS, Architecture
• Current/Peak memory usage
• Memory limit + usage %
• max_execution_time, post_max_size, etc.
• OPcache status (enabled, memory, hit rate)
• Loaded extensions list

Nginx Metrics

• Version (из SERVER_SOFTWARE, резерв — nginx -v)
• Server software (сырая строка)
• HTTP-протокол запроса + флаги http2 / http3
• HTTPS / scheme / gateway (FastCGI)
• TLS текущего соединения: state (ok/plain/absent), протокол, шифр
• Build: TLS-библиотека (OpenSSL) и число модулей (только bare-metal через nginx -V)

Docker Metrics

• Docker version
• Containers list (ID, name, state, status, image)
• Total images count
• Total volumes count
• Total networks count
• Container logs (via modal)

Database Metrics

• Driver (mysql/pgsql)
• Version
• Database name + charset
• Total database size
• Tables count + total rows
• Data/Index sizes
• Connection stats (current/running/cached/max)

Redis Metrics

• Version
• Uptime
• Connected/Blocked clients
• Memory usage (used/peak/max/fragmentation)
• Hit rate
• Total keys + per-database breakdown

Application Metrics

• Yii version, app name/ID
• Environment (dev/prod)
• Debug mode
• Timezone, Language
• Cache class + config
• Session handler
• Queue driver

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

Backend Security

1. CSRF Protection Все POST запросы проверяют CSRF токен:

2. Access Control Контроллер защищен фильтром доступа:

3. Docker Security

Используется socket-proxy вместо прямого доступа к Docker socket:

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

• ✅ Только READ операции
• ✅ Нет прямого доступа к /var/run/docker.sock
• ✅ Изолированная сеть socket-proxy
• ✅ Timeout на команды (5 секунд)

4. Shell Command Execution

Все shell команды выполняются безопасно:

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

• ✅ Встроенный timeout
• ✅ Нет использования пользовательского ввода в командах
• ✅ Обработка ошибок через try/catch
• ✅ Suppress warnings с @

5. SQL Injection Protection

Все SQL запросы используют параметризованные запросы:

6. XSS Protection

Frontend использует безопасные методы:

Frontend Security

1. Content Security Policy

Рекомендуется настроить CSP headers:

2. HTTPS Only

Все запросы должны идти через HTTPS в production.

3. localStorage Security

Settings хранятся в localStorage:

• ✅ Нет чувствительных данных
• ✅ Только updateInterval и autoRefresh
• ✅ Client-side only

Производительность

Backend Optimization

1. No Caching Strategy

Метрики НЕ кэшируются намеренно:

• Данные всегда актуальные
• Realtime мониторинг
• Провайдеры stateless

2. Lightweight Realtime Endpoint

api-realtime возвращает только динамические данные:

• ~500 байт вместо ~2.5 Кб
• Экономия трафика: 80%
• Быстрее парсинг JSON

3. Efficient Data Collection

Провайдеры используют оптимизированные методы:

4. Shell Command Timeout

Все команды имеют timeout 5 секунд:

5. Database Query Optimization

Используем агрегирующие запросы:

Frontend Optimization

1. Chart.js Data Limiting

Графики хранят максимум 60 точек:

60 точек × 3 секунды = 3 минуты истории

2. Chart Update Without Animation

3. Debouncing Auto-refresh

Realtime updater использует интервал 3 секунды:

• Не перегружает сервер
• Достаточно для мониторинга
• Настраивается пользователем

4. Lazy Loading Docker Logs

Логи загружаются только при открытии модалки:

5. ES6 Modules

TypeScript компилируется в ES6 модули:

• Современный синтаксис
• Tree-shaking в Vite
• Меньший размер bundle (~32 KB)

6. CDN для Chart.js

Chart.js загружается с CDN:

• Параллельная загрузка
• Кэширование браузером
• Уменьшает размер собственного bundle

Build Optimization

Vite Production Build:

Результат:

Оптимизации:

• Minification
• Tree-shaking
• Source maps для отладки
• ES6 модули

Troubleshooting

Общие проблемы

1. "Array to string conversion"

Симптом: Ошибка в /app/Besnovatyj/Info/widgets/sysinfo/views/index.php:13

Причина: Попытка вывести массив как строку в HTML атрибуте

Решение:

2. "TypeError: can't access property 'hostname', e is undefined"

Симптом: Ошибка в MetricsRenderer.ts:40 при realtime обновлении

Причина: Realtime endpoint не возвращает статические данные (server, cpu info)

Решение:

3. "Chart.js is not loaded"

Симптом: Предупреждение в консоли, графики не отображаются

Причина: Chart.js не подключен в Assets

Решение:

4. "Docker недоступен"

Симптом: Вкладка Docker показывает "Docker недоступен"

Причина: Docker CLI не установлен или нет доступа к socket-proxy

Решение: См. DOCKER-SETUP.md

5. "[object Object]" в данных сервисов

Симптом: Вместо значений показывается "[object Object]"

Причина: Неправильный путь к вложенным свойствам

Решение:

6. TypeScript compilation errors

Симптом:

Решение:

7. Services данные исчезают при auto-refresh

Симптом: При автообновлении пропадает информация о PHP, MySQL, Redis

Причина: Realtime endpoint не возвращает полные данные сервисов

Решение: Методы рендеринга должны проверять наличие данных:

Debug Mode

Включите логирование в консоль:

Все компоненты логируют свои действия с префиксом [ComponentName].

Network Tab

Проверьте запросы в DevTools → Network:

Успешный запрос:

Неуспешный запрос:

PHP Logs

Проверьте логи приложения:

Все ошибки провайдеров логируются через Yii::error().

Заключение

Виджет системной информации - это полноценное решение для мониторинга сервера с современной архитектурой:

✅ Clean Architecture - четкое разделение слоев ✅ Dependency Injection - все зависимости через DI контейнер ✅ TypeScript + Vite - современный frontend без jQuery ✅ Chart.js - красивые графики в реальном времени ✅ Docker Security - безопасный доступ через socket-proxy ✅ No Caching - всегда актуальные данные ✅ Responsive UI - Bootstrap 5 с адаптивным дизайном ✅ Extensible - легко добавить новые провайдеры метрик

Производительность:

• Backend: ~1 секунда на полные метрики
• Frontend: ~32 KB bundle (gzip: 7.6 KB)
• Realtime: обновление каждые 3 секунды

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

• CSRF protection
• Access control
• Socket-proxy для Docker
• Parametrized SQL queries
• XSS protection
• Command timeouts

Проект готов к использованию в production (кроме Docker метрик на dev-only серверах).