XC_VM/docs/ru/api/system_api.md

# Системный API

Этот API предоставляет различные системные функции, включая управление потоками и VOD, статистику системы, обзор директорий, просмотр логов, управление процессами, перезагрузку EPG/nginx и многое другое.

---

## Расположение файлов

Системный API обрабатывается контроллером:

```text
src/public/Controllers/Api/InternalApiController.php
```

HTTP entry-point: `/api.php` — маршрутизируется nginx на `public/index.php` с параметром `XC_API=internal`.

## Обзор архитектуры API

**Базовый URI:** `http://<host>:<http port>/api.php`
**Аутентификация:** параметр `password`, соответствующий конфигурации `live_streaming_pass`
**Пример:**
`http://<host>:<http port>/api.php?password=<live_streaming_pass>&action=<api endpoint>`

---

## Основные конечные точки API

### 1. Просмотр лога потока

#### **GET** `/api.php?action=view_log`

**Описание:** Возвращает лог ошибок для заданного потока или VOD. Сначала проверяется `STREAMS_PATH`, затем — `VOD_PATH`.
**Параметры:**

| Параметр  | Тип     | Обязателен | Описание                              |
| --------- | ------- | ---------- | ------------------------------------- |
| stream_id | integer | да         | ID потока, для которого нужен лог     |

**Ответ:** Содержимое файла `<stream_id>.errors` в виде простого текста, или пустой ответ, если лог отсутствует.

---

### 2. FPM Status

#### **GET** `/api.php?action=fpm_status`

**Описание:** Возвращает страницу состояния PHP-FPM с локального HTTP broadcast-порта сервера.

---

### 3. Перезагрузка EPG

#### **GET** `/api.php?action=reload_epg`

**Описание:** Запускает в фоне перезагрузку EPG (Electronic Program Guide), асинхронно выполняя `console.php cron:epg`.

---

### 4. Восстановление изображений

#### **GET** `/api.php?action=restore_images`

**Описание:** Запускает в фоне восстановление изображений, асинхронно выполняя `console.php tools images`.

---

### 5. Перезагрузка Nginx

#### **GET** `/api.php?action=reload_nginx`

**Описание:** Перезагружает оба процесса nginx — RTMP nginx и основной — отправляя им сигнал перезагрузки.

---

### 6. Использование Ramdisk потоков

#### **GET** `/api.php?action=streams_ramdisk`

**Описание:** Возвращает размеры файлов по каждому потоку из директории ramdisk. Имеет лимит времени 30 секунд.
**Ответ:**

```json
{
  "result": true,
  "streams": {
    "123": 4096000,
    "456": 2048000
  }
}
```

---

### 7. Управление VOD

#### **GET** `/api.php?action=vod`

**Описание:** Запускает или останавливает VOD-потоки. При запуске поток сначала останавливается, затем либо запускается принудительно, либо ставится в очередь — в зависимости от параметра `force`.
**Параметры:**

| Параметр   | Тип               | Обязателен | Описание                                                       |
| ---------- | ----------------- | ---------- | -------------------------------------------------------------- |
| stream_ids | array of integers | да         | Список ID потоков                                              |
| function   | string            | да         | Выполняемое действие (`start` или `stop`)                      |
| force      | boolean           | нет        | Если true — запуск немедленно, без очереди (только для start)  |

**Ответ:**

```json
{ "result": true }
```

---

### 8. Статистика RTMP

#### **GET** `/api.php?action=rtmp_stats`

**Описание:** Возвращает статистику локального RTMP-сервера.

---

### 9. Завершение процесса по PID

#### **GET** `/api.php?action=kill_pid`

**Описание:** Завершает процесс, отправляя SIGKILL (сигнал 9) указанному PID.
**Параметры:**

| Параметр | Тип     | Обязателен | Описание                       |
| -------- | ------- | ---------- | ------------------------------ |
| pid      | integer | да         | ID процесса для завершения     |

**Ответ:**

```json
{ "result": true }
```

---

### 10. RTMP Kill

#### **GET** `/api.php?action=rtmp_kill`

**Описание:** Завершает подключение RTMP-публикатора по имени через интерфейс управления nginx RTMP.
**Параметры:**

| Параметр | Тип    | Обязателен | Описание                              |
| -------- | ------ | ---------- | ------------------------------------- |
| name     | string | да         | Имя RTMP-потока для отключения        |

---

### 11. Управление live-потоками

#### **GET** `/api.php?action=stream`

**Описание:** Запускает или останавливает live-потоки. При запуске между каждым потоком применяется задержка 50 мс.
**Параметры:**

| Параметр   | Тип               | Обязателен | Описание                                  |
| ---------- | ----------------- | ---------- | ----------------------------------------- |
| stream_ids | array of integers | да         | Список ID потоков                         |
| function   | string            | да         | Выполняемое действие (`start` или `stop`) |

**Ответ:**

```json
{ "result": true }
```

---

### 12. Системная статистика

#### **GET** `/api.php?action=stats`

**Описание:** Получает системную статистику через `SystemInfo::getStats()`.
**Ответ:**

```json
{
  "cpu": 8.32,
  "cpu_cores": 56,
  "cpu_avg": 8.86,
  "cpu_name": "Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz",
  ...
}
```

---

### 13. Принудительный источник потока

#### **GET** `/api.php?action=force_stream`

**Описание:** Принудительно переключает поток на указанный источник, записывая force-сигнальный файл.
**Параметры:**

| Параметр  | Тип     | Обязателен | Описание                                       |
| --------- | ------- | ---------- | ---------------------------------------------- |
| stream_id | integer | да         | ID потока для принудительного переключения     |
| force_id  | integer | да         | ID источника, на который переключить поток     |

---

### 14. Закрытие подключения

#### **GET** `/api.php?action=closeConnection`

**Описание:** Закрывает активное подключение по его activity ID.
**Параметры:**

| Параметр    | Тип     | Обязателен | Описание                            |
| ----------- | ------- | ---------- | ----------------------------------- |
| activity_id | integer | да         | Activity ID подключения             |

---

### 15. Проверка жизненного цикла процессов

#### **GET** `/api.php?action=pidsAreRunning`

**Описание:** Проверяет, выполняются ли указанные PID и соответствуют ли они ожидаемому бинарнику программы.
**Параметры:**

| Параметр | Тип               | Обязателен | Описание                       |
| -------- | ----------------- | ---------- | ------------------------------ |
| pids     | array of integers | да         | Список PID для проверки        |
| program  | string            | да         | Ожидаемое имя программы        |

**Ответ:**

```json
{
  "1234": true,
  "5678": false
}
```

---

### 16. Получение файла

#### **GET** `/api.php?action=getFile`

**Описание:** Скачивание указанного файла. Поддерживает HTTP Range-запросы для частичной загрузки. Разрешены только файлы с расширениями: `log`, `tar.gz`, `gz`, `zip`, `m3u8`, `mp4`, `mkv`, `avi`, `mpg`, `flv`, `3gp`, `m4v`, `wmv`, `mov`, `ts`, `srt`, `sub`, `sbv`, `jpg`, `png`, `bmp`, `jpeg`, `gif`, `tif`.
**Параметры:**

| Параметр | Тип    | Обязателен | Описание         |
| -------- | ------ | ---------- | ---------------- |
| filename | string | да         | Путь к файлу     |

**Ответ:** Содержимое файла с типом `application/octet-stream`. Поддерживает заголовок `Range` для частичной загрузки (HTTP 206).

---

### 17. Рекурсивное сканирование директории

#### **GET** `/api.php?action=scandir_recursive`

**Описание:** Рекурсивно сканирует директорию с помощью `find`, опционально фильтруя по расширению. Имеет лимит времени 30 секунд.
**Параметры:**

| Параметр | Тип    | Обязателен | Описание                                                                |
| -------- | ------ | ---------- | ----------------------------------------------------------------------- |
| dir      | string | да         | URL-encoded путь к директории                                           |
| allowed  | string | нет        | URL-encoded список разрешённых расширений, разделённых `\|` (напр. `mp4\|mkv`) |

**Ответ:** JSON-массив путей файлов.

---

### 18. Список директории

#### **GET** `/api.php?action=scandir`

**Описание:** Возвращает список файлов и подкаталогов в заданной директории, опционально фильтруя по расширению. Имеет лимит времени 30 секунд.
**Параметры:**

| Параметр | Тип    | Обязателен | Описание                                                                |
| -------- | ------ | ---------- | ----------------------------------------------------------------------- |
| dir      | string | да         | URL-encoded путь к директории                                           |
| allowed  | string | нет        | URL-encoded список разрешённых расширений, разделённых `\|` (напр. `mp4\|mkv`) |

**Ответ:**

```json
{
  "result": true,
  "dirs": ["subdir1", "subdir2"],
  "files": ["video.mp4", "movie.mkv"]
}
```

---

### 19. Получить свободное место на диске

#### **GET** `/api.php?action=get_free_space`

**Описание:** Возвращает информацию об использовании диска из `df -h`.
**Ответ:** JSON-массив строк вывода `df -h`.

---

### 20. Получить список процессов

#### **GET** `/api.php?action=get_pids`

**Описание:** Возвращает список всех запущенных процессов с деталями (пользователь, PID, CPU%, память% и т.д.).
**Ответ:** JSON-массив строк вывода `ps -e`.

---

### 21. Перенаправление подключения

#### **GET** `/api.php?action=redirect_connection`

**Описание:** Перенаправляет подключение, записывая сигнальный файл, идентифицируемый по UUID.
**Параметры:**

| Параметр  | Тип     | Обязателен | Описание                       |
| --------- | ------- | ---------- | ------------------------------ |
| uuid      | string  | да         | UUID, идентифицирующий подключение |
| stream_id | integer | да         | ID целевого потока             |

---

### 22. Очистка временной директории

#### **GET** `/api.php?action=free_temp`

**Описание:** Удаляет все файлы в директории `tmp/` и запускает cron-задачу кэша.

---

### 23. Очистка директории потоков

#### **GET** `/api.php?action=free_streams`

**Описание:** Удаляет все файлы из директории `content/streams/`.

---

### 24. Отправка сигнала

#### **GET** `/api.php?action=signal_send`

**Описание:** Отправляет сигнальное сообщение подключению, идентифицированному по UUID.
**Параметры:**

| Параметр | Тип    | Обязателен | Описание                              |
| -------- | ------ | ---------- | ------------------------------------- |
| message  | string | да         | Сигнальное сообщение или команда      |
| uuid     | string | да         | UUID, идентифицирующий подключение    |

---

### 25. Получить информацию о сертификате

#### **GET** `/api.php?action=get_certificate_info`

**Описание:** Возвращает информацию о SSL/TLS-сертификате через `DiagnosticsService::getCertificateInfo()`.

---

### 26. Принудительный запуск Watch Cron

#### **GET** `/api.php?action=watch_force`

**Описание:** Запускает в фоне cron-задачу watch для конкретного элемента.
**Параметры:**

| Параметр | Тип     | Обязателен | Описание              |
| -------- | ------- | ---------- | --------------------- |
| id       | integer | да         | ID элемента watch     |

---

### 27. Принудительный запуск Plex Cron

#### **GET** `/api.php?action=plex_force`

**Описание:** Запускает в фоне cron-задачу Plex для конкретного элемента.
**Параметры:**

| Параметр | Тип     | Обязателен | Описание            |
| -------- | ------- | ---------- | ------------------- |
| id       | integer | да         | ID элемента Plex    |

---

### 28. Получить файлы архива

#### **GET** `/api.php?action=get_archive_files`

**Описание:** Возвращает список архивных `.ts`-сегментов для заданного потока.
**Параметры:**

| Параметр  | Тип     | Обязателен | Описание      |
| --------- | ------- | ---------- | ------------- |
| stream_id | integer | да         | ID потока     |

**Ответ:**

```json
{
  "result": true,
  "data": ["/path/to/archive/123/segment001.ts", "/path/to/archive/123/segment002.ts"]
}
```

---

### 29. Завершение процессов Watch

#### **GET** `/api.php?action=kill_watch`

**Описание:** Завершает все запущенные процессы модуля watch (основной PID и PID воркеров).

---

### 30. Завершение процессов Plex

#### **GET** `/api.php?action=kill_plex`

**Описание:** Завершает все запущенные процессы модуля Plex (основной PID и PID воркеров).

---

### 31. Probe потока

#### **GET** `/api.php?action=probe`

**Описание:** Зондирует URL потока с помощью FFprobe для получения медиаинформации.
**Параметры:**

| Параметр   | Тип    | Обязателен | Описание                                       |
| ---------- | ------ | ---------- | ---------------------------------------------- |
| url        | string | да         | URL зондируемого потока                        |
| user_agent | string | нет        | Пользовательский заголовок User-Agent          |
| http_proxy | string | нет        | URL HTTP-прокси                                |
| cookies    | string | нет        | Строка cookies для отправки с запросом         |
| headers    | string | нет        | Дополнительные HTTP-заголовки                  |

**Ответ:**

```json
{
  "result": true,
  "data": { ... }
}
```

---

## Коды ошибок

| Код                  | Описание                       |
| -------------------- | ------------------------------ |
| INVALID_API_PASSWORD | Неверный пароль API            |
| API_IP_NOT_ALLOWED   | IP-адрес не разрешён           |

Стандартный ответ для нераспознанного действия:

```json
{ "result": false }
```

---

## Примечания

* Все запросы должны быть аутентифицированы корректным паролем API (`live_streaming_pass`).
* IP-адрес запроса должен быть в списке разрешённых IP, возвращаемом `ServerRepository::getAllowedIPs()`.
* Некоторые действия выполняют команды асинхронно в фоне и возвращают результат немедленно.