Инструменты CLI и ссылка на консоль¶

Справочник по интерфейсу командной строки XC_VM, системным инструментам и процессу обновления базы данных после обновления версии. Описывает ежедневные операции, аварийный доступ и создание новых этапов обновления базы данных.

Точка входа в консоль¶

Все команды CLI выполняются через console.php:

/home/xc_vm/console.php <command> [args...]

Консоль поддерживает три типа команд:

Тип	Рассчитывать	Описание
Commands	28	Одноразовые операции (обновление, статус, инструменты и т.д.)
CronJobs	25	Запланированные задачи (автоматически вызываемые crontab)
Daemons	8	Длительно выполняющиеся фоновые процессы (команды, использующие `DaemonTrait`)

Примечание: Демоны - это обычные команды, которые используют DaemonTrait. Отдельного каталога Daemons/ не существует.

Чтобы просмотреть все доступные команды:

/home/xc_vm/console.php list

Полный реестр команд¶

Служебные команды¶

Команда	Класс	Описание	Пользователь
`status`	`StatusCommand`	Состояние системы, обновления базы данных, проверка конфигурации	корень
`update`	`UpdateCommand`	Обновление системы (update / после обновления)	xc_vm
`service`	`ServiceCommand`	Управление службой XC_VM: запуск, остановка, перезапуск, перезагрузка	корень
`tools`	`ToolsCommand`	Утилиты технического обслуживания (см. раздел команды "Инструменты")	корень/xc_vm
`certbot`	`CertbotCommand`	Сгенерируйте SSL-сертификат с помощью certbot	корень
`binaries`	`BinariesCommand`	Обновите пакет среды выполнения (php/nginx/...) из выпуска `XC_VM_Binaries`	xc_vm
`fanout_binary`	`FanoutBinaryCommand`	Установите/обновите двоичный файл демона `xc_fanout` с момента его выпуска	корень
`xcvm_core`	`XcvmCoreCommand`	Установите/обновите расширение `xcvm_core` PHP из хранилища двоичных файлов	корень
`ytdlp`	`YtDlpCommand`	Установите/обновите `yt-dlp` из своей предыдущей версии на GitHub	корень
`startup`	`StartupCommand`	Инициализация системы: daemons.sh, crontab, кэш	корень
`monitor`	`MonitorCommand`	Отслеживайте поток по идентификатору (start/restart/track). Только для потоков, которые супервизор xc_fanout не использует — он заменяет контролируемый поток	xc_vm
`thumbnail`	`ThumbnailCommand`	Создание рамок миниатюр для потока	xc_vm
`plex_item`	`PlexItemCommand`	Обработать один элемент Plex (фильм/сериал)	xc_vm
`vod_import_batch`	`VodImportBatchCommand`	Просмотр одного фильма/серии → Пакетный импорт, по `thread_count` файлов за раз.	xc_vm
`vod_import_item`	`VodImportItemCommand`	Импорт одного файла фильма/эпизода (поиск/вставка в TMDB); используется в меню Фильмы/сериалы → Импорт и в папке Просмотр	xc_vm
`watch_item`	`WatchItemCommand`	Только модуль наблюдения ≤ 1.0.5: свой собственный рабочий модуль для каждого файла, замененный на `vod_import_item` в версии 1.1.0	xc_vm
`migrate`	`MigrateCommand`	Перенос данных из базы данных `xc_vm_migrate`	xc_vm
`db:migrate`	`DbMigrateCommand`	Применить ожидающие переноса базы данных из каталога `migrations/`	xc_vm
`server:install`	`ServerInstallCommand`	Установка/настройка сервера (Proxy/LB) через SSH	корень
`server:diagnose`	`ServerDiagnoseCommand`	Диагностируйте, почему прокси-узел/LB-узел не подключен к главному (частота сердечных сокращений, доступность, iptables, служба, состояние кластера).	корень
`server:sync-openssl-extra`	`ServerSyncOpensslExtraCommand`	Отправьте значение main `OPENSSL_EXTRA` подсистемам балансировки нагрузки, которые сообщают о другом (только для MAIN).	корень/xc_vm

server:install учетные данные и ключ хоста. Панель не передает SSH пароль в командной строке или в bin/install/<id>.json: он записывает 0600 bin/install/<id>.cred, передает - - вместо имени пользователя и пароля плюс --cred-file=<path>, и команда считывает и удаляет этот файл перед выполнением подключается. <id>.json сохраняются только несекретные параметры, поэтому Переустановите снова запрашивает пароль. SSH-ключ узла (SHA-1) проверен на соответствие --expect-hostkey= (поле Ожидаемый SSH-ключ хоста: 40 шестнадцатеричных цифр или SHA1:… строка из ssh-keygen -l -E sha1 -f /etc/ssh/ssh_host_ed25519_key.pub выполняется на узле), иначе против servers.ssh_hostkey_sha1, сохраненного первым установите, иначе он будет надежным при первом использовании и сохранен. Таким образом, это перестроенный узел needs its new fingerprint entered on reinstall, or --forget-hostkey=1 (the Забыли сохраненный SSH-ключ хоста переключите форму переустановки): сохраненный ключ тогда запрос не запрашивается, и тот, который представляет узел, сохраняется после входа в систему. сработало.

console.php регистрирует каждый класс, который он обнаруживает в Cli/Commands/ и Cli/CronJobs/ (глобус + отражение) — есть нет file_exists() защита. Команда является "необязательной" только в том смысле, что она может быть снято со сборки LB (Makefile LB_FILES_TO_REMOVE) или обеспечивается установленным модулем. plex_item и watch_item, указанные выше, являются предоставляемый модулем (Plex/Watch ≤ 1.0.5) — их классы команд отсутствуют в выделенном дереве ядра и существуют только после установки этого модуля.

Команды демона (постоянные процессы)¶

Эти команды используют DaemonTrait и выполняются непрерывно через циклы while(true):

Команда	Класс	Описание
`signals`	`SignalsCommand`	Обрабатывать сигналы уничтожения/кэширования из DB и Redis
`watchdog`	`WatchdogCommand`	Мониторинг системы: процессор, подключения, обновления сервера
`queue`	`QueueCommand`	Обрабатывать фоновые задачи в очереди
`scanner`	`ScannerCommand`	Поиск новых потоков/устройств
`cache_handler`	`CacheHandlerCommand`	Обрабатывать операции с кэшем (необязательно)

Команды потоковой обработки¶

Команда	Класс	Описание
`proxy`	`ProxyCommand`	Проксирование потока MPEG-TS через sockets — прокси-потоки при выключенном разветвлении (запускается с помощью `live.php`)
`archive`	`ArchiveCommand`	Телевизионный архив — запись потока на сегменты
`created`	`CreatedCommand`	Созданный канал — создание канала из исходных текстов
`delay`	`DelayCommand`	Задержка воспроизведения потока HLS
`loopback`	`LoopbackCommand`	Получать MPEG-TS с другого сервера
`llod`	`LlodCommand`	Потоковый процессор с низкой задержкой по требованию
`record`	`RecordCommand`	Запись потока в формате MP4
`ondemand`	`OndemandCommand`	Прерывать трансляции без активных зрителей

Задания Cron¶

Таблицы команд/cron/daemon, приведенные ниже, поддерживаются вручную и могут изменяться. Источник truth — console.php list - запустите его, чтобы увидеть текущий реестр.

Все имена заданий cron имеют префикс cron:. Для них используется CronTrait, и они вызываются системой crontab.

Основные задания cron (в src/Cli/CronJobs/):

Команда	Класс	Описание
`cron:activity`	`ActivityCronJob`	Импорт журналов действий пользователей в базу данных
`cron:backups`	`BackupsCronJob`	Управление резервными копиями (необязательно)
`cron:cache`	`CacheCronJob`	Управление кэшем
`cron:cache_engine`	`CacheEngineCronJob`	Генерировать кэш для строк, потоков, серий, групп (необязательно)
`cron:certbot`	`CertbotCronJob`	Обновление SSL-сертификата
`cron:cleanup`	`CleanupCronJob`	Очистка временных файлов и журналов
`cron:epg`	`EpgCronJob`	Загрузка и обработка EPG (необязательно)
`cron:errors`	`ErrorsCronJob`	Журналы ошибок процесса
`cron:lines_logs`	`LinesLogsCronJob`	Импорт журналов клиентских запросов в базу данных
`cron:maxmind`	`MaxMindCronJob`	Обновление баз данных MaxMind GeoIP (только по вторникам; `--force` для запуска вручную)
`cron:providers`	`ProvidersCronJob`	Поставщики обновлений (необязательно)
`cron:root_mysql`	`RootMysqlCronJob`	Обслуживание базы данных (root, необязательно)
`cron:root_signals`	`RootSignalsCronJob`	Обрабатывать сигналы, iptables, nginx, управление службами и бинарное самоисцеление (root)
`cron:series`	`SeriesCronJob`	Обновление данных серии (необязательно)
`cron:servers`	`ServersCronJob`	Контролируйте сервер, запускайте демонов, обновляйте статистику
`cron:stats`	`StatsCronJob`	Вычислять и хранить статистику
`cron:streams`	`StreamsCronJob`	Проверка и обновление статуса потока
`cron:streams_logs`	`StreamsLogsCronJob`	Импорт журналов потоков
`cron:tmp`	`TmpCronJob`	Очистка временных файлов
`cron:update`	`UpdateCronJob`	Проверять и применять обновления (необязательно)
`cron:users`	`UsersCronJob`	Управление подключениями пользователей, повторная синхронизация, дивергенция
`cron:vod`	`VodCronJob`	Обрабатывать контент VOD
`cron:proxy`	`ProxyArchiveCronJob`	Архивирование/ротация потоковых данных прокси-сервера
`cron:module_licenses`	`ModuleLicensesCronJob`	Обновить лицензии на установленные модули
`cron:module_updates`	`ModuleUpdatesCronJob`	Проверьте наличие обновлений модуля
`cron:tmdb`	`TmdbCronJob`	Получение метаданных TMDB (необязательно)
`cron:tmdb_popular`	`TmdbPopularCronJob`	Выборка популярного содержимого TMDB (необязательно)

Задания cron, предоставляемые модулем. Регистрируются дополнительными модулями через CronProviderInterface::getCronEntries(); они существуют только тогда, когда этот модуль установлен, и находятся нет в дереве committed core (src/Modules/ отправляются пустыми). (cron:tmdb/cron:tmdb_popular — это ядро, перечисленные выше, а не задания cron модуля.)

Команда	Класс	Модуль	Описание
`cron:plex`	`PlexCronJob`	сплетение	Обрабатывать обновления Plex
`cron:watch`	`WatchCronJob`	часы	Обрабатывать обновления библиотеки отслеживания

"Необязательные" задания cron регистрируются нет условно — регистрируется каждый обнаруженный класс CronJob. "Необязательно" означает, что задание не выполняется, если не включена его функция/настройка (например, cron:epg, cron:series, cron:update), или если задание не удалено из сборки LB.

Бинарное самообновление (самовосстановление)¶

Некоторые связанные двоичные файлы нет поставляются внутри пакета heavy runtime bundle и будут в противном случае никогда не обновляйтесь между выпусками панели (новый узел LB или узел, оставленный включенным старая сборка, никогда не сходилась бы). cron:root_signals (root, каждую минуту) сохраняет они становятся текущими путем опроса их идемпотентных команд обновления для каждого двоичного файла на расписание с ограниченным использованием штампов - каждая загрузка выполняется только при несоответствии версии, проверяется контрольная сумма, запуск-тестирует новый двоичный файл, затем заменяет его атомарно (неработающая загрузка никогда не заменяет рабочий). Выполняется на каждом узле (main и LB).

Двоичный	Команда	Источник	Проверить	Опрос
`xc_fanout` демон и `xc_agent`	`fanout_binary`	`XC_VM_Fanout` высвобождение активов	`SHA256SUMS` (+ испытание агента в `run.sh`)	~ежечасно
`xcvm_core` расширение	`xcvm_core`	`XC_VM_Binaries` дерево репозиториев (`bin/xcvm_core/`)	`SHA256SUMS` + нагрузочный тест	~ежечасно
`yt-dlp`	`ytdlp`	вышестоящий `yt-dlp/yt-dlp` релиз	`SHA2-256SUMS` + `--version`	ежедневный
`ffmpeg`/`ffprobe` 4.0, 7.1, 8.1	`ffmpeg` (как xc_vm)	`XC_VM_FFMPEG` релиз, сборки этого дистрибутива	`hashes.md5` + оба двоичных файла должны быть запущены	ежедневный

Марки живут в CRONS_TMP_PATH (fanout_binary_check, xcvm_core_check, ytdlp_check, ffmpeg_check); первый проход (штамп отсутствует) выполняется немедленно, поэтому новый install/LB получает двоичный файл в течение минуты. Каждый узел запускает их, независимо от его групповой режим: ОСНОВНОЙ игрок не раздает ничего из этого. fanout_binary принимает fanout или agent для обновления одного из двух параметров; при выключенном разветвлении проверка выполняется ежечасно. fanout_binary agent. Выпуск агента, который был откатан run.sh на узле, не является извлекается оттуда снова, пока не появится более новая (xc_agent.tried; force повторяет попытку это).

ffmpeg выводит ffmpeg_<label>_<distro>.tar.gz для каждой метки на страницу настроек предложения (в архивах релизов отсутствует файл ffmpeg: установщик и установка LB запустите и его), встроенного в контейнер этого дистрибутива, чтобы его glibc соответствовал интерфейсу узла., и заменяет каждое из них на bin/ffmpeg_bin/<label>/ только после того, как оно начнется здесь. ffmpeg_bin/ffmpeg_version.json записывает релиз каждого лейбла; запуск, который сделал не завершено (уничтожено, GitHub недоступен), повторная попытка выполняется через час. Версия XUI 4.0 является хранится там, где он есть у узла (только для этого требуется -nofix_dts), до тех пор, пока не будет восстановлен DTS версии 4.0 обработка проверена. Параметр, дающий имя сборке, которой не хватает в узле, использует самую новую версию. из его основных (с 8.0 до тех пор, пока не будет выбрана версия 8.1).

Вместо этого тяжелый пакет runtime (nginx, nginx_rtmp и PHP) обновляется с помощью команда binaries, запускаемая сигналом update_binaries от ГЛАВНОГО устройства.

Регистрация новой команды¶

Все команды CLI реализуют CommandInterface. Основные команды автоматически обнаруживаются из src/Cli/ с помощью отражения в console.php. Команды модуля регистрируются с помощью ModuleLoader::registerAllCommands().

Командный интерфейс¶

interface CommandInterface {
    public function getName(): string;        // Unique command name (used in CLI)
    public function getDescription(): string; // One-line help text (shown in `list`)
    public function execute(array $rArgs): int; // Entry point, returns exit code
}

Шаг 1. Создайте класс¶

Создайте новый файл в src/Cli/Commands/ (или src/Cli/CronJobs/ для заданий cron):

<?php

class MyNewCommand implements CommandInterface {

    public function getName(): string {
        return 'my_command';
    }

    public function getDescription(): string {
        return 'Short description of what it does';
    }

    public function execute(array $rArgs): int {
        // Your logic here
        echo "Done.\n";
        return 0; // 0 = success, 1 = error
    }
}

Для команд демон также используйте DaemonTrait:

class MyDaemonCommand implements CommandInterface {
    use DaemonTrait;
    // ...
}

Для задания cron используйте CronTrait:

class MyCronJob implements CommandInterface {
    use CronTrait;

    public function getName(): string {
        return 'cron:my_job'; // Cron names are prefixed with cron:
    }
    // ...
}

Шаг 2. Регистрация происходит автоматически¶

Есть нечего добавить к console.php. При запуске он выдает Cli/Commands/*.php и Cli/CronJobs/*.php и, посредством отражения, register() для каждого неабстрактного класса, реализующего CommandInterface. Переместите ваш класс в нужный каталог (с помощью getName(), который возвращает его имя команды) — это все, что требуется - смотрите Подключение ядра → регистрация команды CLI.

Шаг 3. Добавить в Makefile (если LB-исключен)¶

Если команда не должна включаться в сборки подсистемы балансировки нагрузки, добавьте ее путь к LB_FILES_TO_REMOVE в поле Makefile.

Шаг 4. Тестирование¶

# Verify it appears in the list
/home/xc_vm/console.php list

# Run it
/home/xc_vm/console.php my_command

Команда инструментов¶

Команда tools предоставляет утилиты для обслуживания системы.

/home/xc_vm/console.php  tools <subcommand>

Подкоманды (запускаются как `root`)¶

Подкомандование	Описание
`rescue`	Create a temporary rescue access code for emergency panel access. Prints the URL. Delete this code after use!
`recaptcha`	Отключите reCAPTCHA (`recaptcha_enable = 0`), чтобы восстановить вход в панель администратора при сбое проверки captcha.
`access`	Восстановите все настройки кода доступа к nginx и перезагрузите nginx. Печатает URL-адреса для всех кодов панели администратора.
`ports`	Восстановите настройки портов nginx (HTTP, HTTPS, RTMP) из базы данных и перезагрузите nginx.
`migration`	Очистите промежуточную базу данных (`xc_vm_migrate`) и при необходимости восстановите в ней резервную копию `.sql`.
`user`	Создайте пользователя rescue admin со случайными учетными данными. Введите имя пользователя и пароль. Удалите этого пользователя после использования!
`mysql`	Повторно авторизуйте привилегии MySQL для всех серверов балансировки нагрузки.
`database`	Восстановите пустую базу данных XC_VM из `database.sql`. Стирает ВСЕ данные! Требуется флаг `--confirm`.
`flush`	Очистить все заблокированные IP—адреса - очищает правила iptables, удаляет заблокированные файлы и обрезает таблицу `blocked_ips`.

Подкоманды (запускаются как `xc_vm`)¶

Подкомандование	Описание
`images`	Загрузите отсутствующие изображения потоковых передач/фильмов/сериалов из базы данных TMDB. Сканирует базу данных в поисках URL-адресов изображений и загружает отсутствующие файлы.
`duplicates`	Найдите и удалите повторяющиеся VOD-трансляции. Группируйте по идентичным источникам, сначала сохраняйте, а остальные удаляйте. Разрушительный!
`bouquets`	Удалите устаревшие ссылки из букетов. Удаляет идентификаторы, которые больше не существуют в базе данных.

Примеры¶

# Emergency panel access (root)
sudo /home/xc_vm/console.php tools rescue

# Disable reCAPTCHA to recover admin login (root)
sudo /home/xc_vm/console.php tools recaptcha

# Regenerate access codes (root) — required after nginx template changes
sudo /home/xc_vm/console.php tools access

# Regenerate port configuration (root)
sudo /home/xc_vm/console.php tools ports

# Clear staging database (root)
sudo /home/xc_vm/console.php tools migration

# Clear staging database and restore a backup (root)
sudo /home/xc_vm/console.php tools migration /path/to/backup.sql

# Create rescue admin user (root)
sudo /home/xc_vm/console.php tools user

# Reauthorise MySQL privileges on all servers (root)
sudo /home/xc_vm/console.php tools mysql

# Restore blank database (root) — DESTRUCTIVE!
sudo /home/xc_vm/console.php tools database --confirm

# Flush all blocked IPs (root)
sudo /home/xc_vm/console.php tools flush

# Download missing images (xc_vm)
su - xc_vm -c '/home/xc_vm/console.php tools images'

# Remove duplicate VOD entries (xc_vm)
su - xc_vm -c '/home/xc_vm/console.php tools duplicates'

# Clean orphaned bouquet references (xc_vm)
su - xc_vm -c '/home/xc_vm/console.php tools bouquets'

⚠️ Предупреждение: duplicates стримы и все связанные с ними данные (журналы, статистика, эпизоды, записи) удаляются безвозвратно. Всегда создавайте резервную копию перед запуском.
⚠️ Предупреждение: database --confirm удаляет всю базу данных и заменяет ее пустой схемой. Это необратимо.
💡 Совет: После запуска rescue всегда удаляйте код через панель администратора или запустив tools access, как только вы восстановите доступ.
💡 Совет: После запуска user немедленно измените пароль и по завершении удалите пользователя для восстановления.

Обновления / миграции баз данных¶

Файловая система обновления базы данных (создание шага .sql, таблицы migrations, потока выполнения db:migrate) теперь доступна на отдельной странице — см. Обновления / миграции баз данных.

Общие операции CLI¶

Проверка состояния¶

sudo /home/xc_vm/console.php status

Проверяет, запущен ли XC_VM, подключается к базе данных, выполняет ожидающие обновления шаги, исправляет разрешения и проверяет конфигурацию nginx. Требуется после установки или восстановления.

С аргументом first-run пропускает текущую проверку, используемую для начальной настройки:

sudo /home/xc_vm/console.php status first-run

Управление услугами¶

sudo /home/xc_vm/console.php service start|stop|restart|reload

Обновление вручную¶

sudo -u xc_vm /home/xc_vm/console.php update update

Загружает и применяет последнее обновление с GitHub. Обычно запускается автоматически через веб-панель.

Диагностика потока¶

sudo -u xc_vm /home/xc_vm/console.php monitor <stream_id>

Запускает поток вручную и отображает все ошибки. Полезно для диагностики сбоев при запуске потока.

Диагностика сервера (узла)¶

# On the MAIN — remote-probe a node by its server id
sudo /home/xc_vm/console.php server:diagnose <server_id>

# On the LB/proxy node itself — local self-diagnosis (no arguments)
sudo /home/xc_vm/console.php server:diagnose

Обнаруживает почему? прокси—сервер/LB—узел, отображаемый в автономном режиме на панели: проверяет частоту сердечных сокращений, доступность (ICMP/TCP/HTTP /api), перекос часов, очередь сигналов, поддерживает ли LB основной OPENSSL_EXTRA и - локально на узле - поддерживает ли узел установил брандмауэр на IP-адрес главного сервера в его собственных iptables, независимо от того, запущена ли служба xc_vm/nginx, запущен ли демон watchdog heartbeat и находится ли cron:servers в crontab xc_vm. Доступно только для чтения; код выхода 0 = проблем не обнаружено, 2 = указаны вероятные причины. Более подробную информацию смотрите в Руководстве по диагностике сервера.

Синхронизация OPENSSL_EXTRA¶

# On the MAIN — one load balancer, or every LB that reports another value
sudo /home/xc_vm/console.php server:sync-openssl-extra <server_id>
sudo /home/xc_vm/console.php server:sync-openssl-extra --all [--force]

Переводит балансировщики нагрузки на основное значение OPENSSL_EXTRA, когда server:diagnose сообщает о несоответствии (воспроизведение, перенаправленное с основного, завершается сбоем на этом LB). Каждое LB применяет это значение в течение минуты и сохраняет прежнее значение в течение 10 минут. Смотрите Устранение несоответствия OPENSSL_EXTRA.

SSL-сертификат¶

sudo /home/xc_vm/console.php certbot

Миграция баз данных¶

Выполните ожидающие действия .sql вручную или импортируйте данные из другой системы — см. Обновления / миграции базы данных.

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

Файл	Роль
`src/console.php`	Точка входа CLI + обнаружение команды FQCN
`src/Cli/Commands/`	Консольные команды
`src/Cli/CronJobs/`	Классы заданий Cron
`src/migrations/`	Миграция баз данных