XC_VM/docs/ru/guides/cli-tools.md

Инструменты CLI и обновления баз данных

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

---

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

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

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

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

Тип	Рассчитывать	Описание
Команды	28	Одноразовые операции (обновление, статус, инструменты и т.д.)
Закадычные друзья	25	Запланированные задачи (автоматически вызываемые crontab)
Демоны	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	Отслеживайте поток по идентификатору (запуск/перезапуск/отслеживание)	xc_vm
thumbnail	ThumbnailCommand	Создание рамок миниатюр для потока	xc_vm
plex_item	PlexItemCommand	Обработать один элемент Plex (фильм/сериал)	xc_vm
watch_item	WatchItemCommand	Обработать один элемент наблюдения (поиск/обновление в базе данных TMDB)	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, сервис)	корень

Команды, помеченные необязательно, условно регистрируются с помощью file_exists() guard: cache_handler, server:install, migrate.

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

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

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

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

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

Задания Cron (всего 26: 22 ядра + 4 модуля)

Все имена заданий 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	Управление подключениями пользователей, синхронизацией Redis, расхождением
cron:vod	VodCronJob	Содержание процесса VOD

Модуль cron заданий (зарегистрирован через ModuleInterface::registerCommands()):

Команда	Класс	Модуль	Описание
cron:plex	PlexCronJob	сплетение	Обрабатывать обновления Plex
cron:tmdb	TmdbCronJob	тмдб	Получение метаданных TMDB (необязательно)
cron:tmdb_popular	TmdbPopularCronJob	тмдб	Выборка популярного содержимого TMDB (необязательно)
cron:watch	WatchCronJob	часы	Обрабатывать обновления библиотеки отслеживания

Дополнительные задания cron (условно зарегистрированные): cron:backups, cron:cache_engine, cron:epg, cron:providers, cron:root_mysql, cron:series, cron:tmdb, cron:tmdb_popular, cron:update.

---

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

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

Двоичный	Команда	Источник	Проверить	Опрос
xc_fanout демон	fanout_binary	XC_VM_Fanout освободить актив	SHA256SUMS	~ежечасно
xcvm_core расширение	xcvm_core	XC_VM_Binaries дерево репозиториев (bin/xcvm_core/)	SHA256SUMS + нагрузочный тест	~ежечасно
yt-dlp	ytdlp	вышестоящий yt-dlp/yt-dlp релиз	SHA2-256SUMS + --version	ежедневный

Марки живут в CRONS_TMP_PATH (fanout_binary_check, xcvm_core_check, ytdlp_check); первый проход (штамп отсутствует) выполняется немедленно, поэтому новый install/LB получает двоичный файл в течение минуты. Пакет heavy runtime bundle (php/nginx/ffmpeg) вместо этого обновляется командой 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
    }
}

Для команд daemon также используйте 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

Добавить к console.php:

// Always loaded
$rRegistry->register(new MyNewCommand());

// Or conditionally (for optional features)
if (file_exists(CLI_PATH . 'Commands/MyNewCommand.php')) {
    $rRegistry->register(new MyNewCommand());
}

Шаг 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	Создайте временный код аварийного доступа для доступа к панели экстренной помощи. Введите URL-адрес. Удалите этот код после использования!
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 для всех серверов load balancer.
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 немедленно измените пароль и по завершении удалите пользователя для восстановления.

---

Обновления базы данных после Обновления Версии

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

как это работает

• SQL-файлы для обновлений базы данных хранятся в /home/xc_vm/migrations/.

• Каждому файлу присваивается имя с префиксом последовательного номера, например:

001_drop_watch_folders_plex_token.sql
002_panel_logs_add_file_env.sql
003_drop_settings_segment_type.sql

• Применяемые шаги обновления базы данных отслеживаются в таблице базы данных migrations. Каждый шаг выполняется ровно один раз - если шаг уже был применен, он пропускается.

• Обновления базы данных выполняются автоматически:

  • console.php update post-update - после обновления панели
  • console.php status - во время проверки состояния системы (только для главного сервера)

Поток выполнения обновления базы данных

[ MigrationRunner::run() — DB update execution ]
        │
        ▼
[ CREATE TABLE IF NOT EXISTS `migrations` ]
        │
        ▼
[ Read all *.sql files from migrations/ ]
        │
        ▼
[ For each file not in `migrations` table: ]
    ├── Execute SQL statements
    ├── Record in `migrations` table
    └── Output [OK] or [WARN]

---

Создание нового шага обновления базы данных

Когда вам нужно изменить схему базы данных (добавить столбцы, создать таблицы, вставить данные и т.д.), создайте новый SQL-файл для этапа обновления базы данных.

Шаг 1. Выберите имя файла

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

NNN_short_description.sql

Правила форматирования:

• Числовой префикс: 3 цифры, дополненные нулем (например, 006, 007)
• Разделитель: символ подчеркивания _
• Название: нижний регистр, подчеркивание, описывающее, что делает шаг обновления
• Добавочный номер: .sql

Примеры:

006_add_user_timezone.sql
007_create_audit_log_table.sql
008_insert_default_codec_settings.sql

Шаг 2. Напишите SQL-код

Поместите в файл необработанные инструкции SQL. Несколько инструкций разделяются символом ;.

Правила для этапов обновления базы данных SQL:

• Используйте IF EXISTS / IF NOT EXISTS, чтобы сделать шаги обновления базы данных идемпотентными:

-- Adding a column (safe)
ALTER TABLE `settings` ADD COLUMN IF NOT EXISTS `timezone` VARCHAR(64) DEFAULT 'UTC';

-- Dropping a column (safe)
ALTER TABLE `settings` DROP COLUMN IF EXISTS `old_column`;

-- Creating a table (safe)
CREATE TABLE IF NOT EXISTS `audit_log` (
    `id` INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    `action` VARCHAR(255) NOT NULL,
    `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

• Используйте условное обозначение INSERT, чтобы избежать дублирования:

INSERT INTO `streams_arguments` (argument_key, argument_name, argument_cmd)
SELECT 'my_key', 'My Argument', '-my_flag %s'
FROM DUAL
WHERE NOT EXISTS (SELECT 1 FROM `streams_arguments` WHERE argument_key = 'my_key');

• Не смешивайте DDL и DML, которые зависят друг от друга, в одном файле. Если вам нужно добавить столбец и затем заполнить его, используйте два файла шага обновления базы данных.

• Комментарии поддерживаются с префиксом -- (они пропускаются во время выполнения).

Шаг 3. Поместите файл

Скопируйте SQL-файл для шага обновления базы данных в:

/home/xc_vm/migrations/

💡 В хранилище исходных текстов это значение равно src/migrations/.

Шаг 4. Подтвердите обновление базы данных

Запустите db:migrate, чтобы применить ожидающие обновления БД шаги:

su - xc_vm -c '/home/xc_vm/console.php db:migrate'

Или через status first-run (также запускает миграции):

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

Ожидаемый результат:

Migrations
------------------------------
  [OK]   006_add_user_timezone.sql

Если инструкция не выполняется, шаг все равно будет записан, но покажет [WARN] — проверьте SQL и устраните любые проблемы.

---

Общие операции 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), перекос часов, очередь сигналов и - локально на узле - выполняет ли узел брандмауэр на главном IP-адресе в своем собственном iptables, запущена ли служба xc_vm/nginx, запущен ли демон heartbeat watchdog и находится ли cron:servers в crontab xc_vm. Доступно только для чтения; код выхода 0 = проблем не обнаружено, 2 = указаны вероятные причины. Более подробную информацию смотрите в Руководстве по диагностике сервера.

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

sudo /home/xc_vm/console.php certbot

Применяйте перенос базы данных вручную

su - xc_vm -c '/home/xc_vm/console.php db:migrate'

Применяет все ожидающие .sql файлы из /home/xc_vm/migrations/. Используйте это, когда вам нужно выполнить миграцию без полного обновления системы.

Обновление базы данных данными из других систем

/home/xc_vm/console.php migrate

Передает данные из промежуточной базы данных xc_vm_migrate. Подробности см. в Руководстве по обновлению базы данных.

---

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

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