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

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

---

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

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

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

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

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

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

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

```bash
/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|
| `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, сервис)|корень|

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

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

Эти команды используют `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

> Таблицы команд/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` |Управление подключениями пользователей, синхронизацией Redis, расхождением|
| `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` демон| `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()`.

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

```php
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
<?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`:

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

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

```php
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](../development/core-wiring.md#cli-command-registration).

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

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

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

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

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

---

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

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

```bash
/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 для всех серверов load balancer.|
| `database` |Восстановите пустую базу данных XC_VM из `database.sql`. **Стирает ВСЕ данные!** Требуется установить флаг `--confirm`.|
| `flush` |Очистить все заблокированные IP—адреса - очищает правила iptables, удаляет файлы блокировки и обрезает таблицу `blocked_ips`.|

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

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

### Примеры

```bash
# 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`) теперь размещена на отдельной странице - см. [Обновления / миграции баз данных](database-migrations.md).

---

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

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

```bash
sudo /home/xc_vm/console.php status
```

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

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

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

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

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

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

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

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

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

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

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

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

```bash
# 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, запущен ли демон сердцебиения `watchdog` и находится ли `cron:servers` в crontab `xc_vm`. Доступно только для чтения; код завершения `0` = проблем не обнаружено, `2` = указаны вероятные причины. Подробности см. в [Руководстве по диагностике сервера](../administration/server-diagnostics.md).

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

```bash
sudo /home/xc_vm/console.php certbot
```

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

Выполните ожидающие действия `.sql` вручную или импортируйте данные из другой системы — см. [Обновления / миграции базы данных](database-migrations.md#applying-migrations-manually).

---

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

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