XC_VM/docs/ru/development/diagnostics-api.md

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

DiagnosticsService предоставляет утилиты для диагностики состояния системы: анализ SSL-сертификатов, проверка совместимости кодеков, работа с журналами панели и определение внешнего IP.

---

Методы

getCertificateInfo(?string $certificate = null): ?array

Возвращает информацию об SSL-сертификате.

Параметры:

• $certificate — путь к файлу сертификата. Если null — путь считывается автоматически из BIN_PATH/nginx/conf/ssl.conf

Возвращает:

[
    'serial'     => string,   // серийный номер
    'expiration' => int,      // UNIX timestamp истечения
    'subject'    => string,   // CN/subject сертификата
    'path'       => string,   // директория сертификата
]

Возвращает null если:

• Файл сертификата не найден
• openssl x509 завершился с ошибкой

Пример:

$info = DiagnosticsService::getCertificateInfo();
if ($info) {
    $days = ($info['expiration'] - time()) / 86400;
    echo "Сертификат истекает через {$days} дней";
    echo "Subject: " . $info['subject'];
}

---

checkCompatibility(array|string $data, bool $allowHEVC = false): bool

Проверяет совместимость кодеков стрима с плеером.

Параметры:

• $data — вывод FFProbe в виде массива или JSON-строки. Ожидает ключ codecs с подключами audio.codec_name и video.codec_name
• $allowHEVC — разрешить HEVC/H.265 и AC3 (по умолчанию отключено)

Поддерживаемые кодеки:

Тип	Поддерживаемые кодеки (по умолчанию)	Дополнительно (с $allowHEVC)
Видео	h264, vp8, vp9, ogg, av1	hevc, h265
Аудио	aac, libfdk_aac, opus, vorbis, pcm_s16le, mp2, mp3, flac	ac3

Пример:

$ffprobeData = [
    'codecs' => [
        'video' => ['codec_name' => 'h264'],
        'audio' => ['codec_name' => 'aac'],
    ]
];

if (DiagnosticsService::checkCompatibility($ffprobeData)) {
    echo 'Кодеки совместимы с плеером';
}

---

downloadPanelLogs(object $db): array

Извлекает до 1000 последних записей из таблицы panel_logs (исключая тип epg), форматирует их и очищает таблицу.

Параметры:

• $db — экземпляр Database (должен иметь методы ->query() и ->get_rows())

Возвращает:

[
    'errors'  => [
        [
            'type'       => string,  // тип записи
            'message'    => string,  // текст ошибки (экранирован)
            'file'       => string,  // дополнительный контекст (экранирован)
            'line'       => int,     // номер строки
            'date'       => int,     // UNIX timestamp
            'human_date' => string,  // читаемая дата в UTC
        ],
        // ...
    ],
    'version' => string,  // текущая версия XC_VM
]

Исключения: выбрасывает Exception при ошибке запроса к БД.

⚠️ Метод очищает таблицу panel_logs после чтения. Вызывайте только при намерении скачать и сбросить логи.

---

submitPanelLogs(object $db): array

Отправляет логи на удалённый сервер диагностики и очищает таблицу. Аналогичен downloadPanelLogs(), но данные передаются через HTTP.

Используется для автоматической отправки отчётов об ошибках в команду поддержки.

---

getApiIP(): ?string

Определяет внешний IP-адрес сервера через запрос к публичному API.

$externalIP = DiagnosticsService::getApiIP();
// Возвращает IP-строку или null при недоступности сети

Используется при регистрации сервера и в диагностике сетевых проблем.

---

Структура panel_logs

Столбец	Тип	Описание
type	string	Тип события (error, warning, и т.д.)
log_message	string	Основное сообщение
log_extra	string	Дополнительный контекст (файл, трейс)
line	int	Номер строки кода
date	int	UNIX timestamp

Тип epg исключается из downloadPanelLogs() — EPG-логи имеют высокую частоту и отдельный инструмент просмотра.

---

Связанные файлы

Файл	Назначение
src/core/Diagnostics/DiagnosticsService.php	Основной класс диагностики
src/core/Logging/Logger.php	Запись в panel_logs
src/core/Config/AppConfig.php	Константа XC_VM_VERSION