# FAQ - Часто задаваемые вопросы

Здесь вы найдете ответы на наиболее распространенные вопросы и проблемы при работе с XC_VM.

---

## Проблемы с потоками

<details>
<summary><b>❌ Мой стрим не запускается на MAIN или LB</b></summary>

---

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

Подключитесь к консоли вашего сервера и выполните следующую команду:

```bash
sudo -u xc_vm /home/xc_vm/console.php monitor 291
````

> 🧩 Где `291` - это ваш **идентификатор потока** (замените его на свой собственный).

---

### Что делает команда

Команда **монитор** пытается запустить поток вручную и в случае сбоя выдает сообщение об ошибке.

---

### Возможные причины

#### 1️⃣ Отсутствующие системные библиотеки

Если выходные данные содержат ошибку типа:

```
error while loading shared libraries: libxyz.so.1: cannot open shared object file
```

Установите отсутствующую библиотеку с помощью:

```bash
sudo apt install <library_name>
```

После установки запустите тест повторно.

> 💬 Дайте мне знать, нужно ли добавить библиотеку в сценарий установки.

---

#### 2️⃣ Ошибка, не связанная с библиотеками

Если ошибка другого типа — пришлите ее вывод, чтобы я мог помочь ее диагностировать.

---

### Резюме

1. Запустите диагностическую команду.
2. Проверьте, нет ли каких-либо ошибок.
3. При необходимости установите отсутствующие библиотеки.
4. Сообщайте о любых других ошибках для дальнейшего анализа.

---

</details>

<details>
<summary><b>❌ Streaming fails with "IP_MISMATCH" or "TOKEN_EXPIRED"</b></summary>

---

Это функции безопасности, а не баги:

- **ТОКЕН_ИСПОЛЬЗОВАН** — токен сеанса имеет ограничение по времени. Пользователю необходимо повторно пройти аутентификацию.
- **IP_MISMATCH СОВПАДЕНИЕ IP_MISMATCH** — IP-адрес пользователя изменился в середине потока (часто определяется как общий доступ к учетным данным).

**Relevant settings:**
- `restrict_same_ip` — насколько строго соблюдается соответствие IP-адресов
- `disallow_2nd_ip_con` — блокирует одновременные подключения с разных IP-адресов.

Если это вызывает проблемы у законных пользователей (например, мобильные сети часто меняют IP-адреса), измените уровень ограничений в настройках панели администратора.

---

</details>

---

## Проблемы с логином и доступом

<details>
<summary><b>❌ Я заблокирован — IP продолжает блокироваться</b></summary>

---

XC_VM защита методом перебора блокирует IP-адреса после слишком большого числа неудачных попыток входа в систему. Это контролируется:

- `bruteforce_mac_attempts` — количество попыток для каждого MAC за определенный промежуток времени
- `bruteforce_username_attempts` — количество попыток для каждого имени пользователя за определенный промежуток времени
- `flood_limit` — общее количество запросов в окне

**To unblock yourself:**

1. **Из панели администратора:** Инструменты → Управление IP-адресами → удалить из списка заблокированных.
2. **Из CLI:** `sudo /home/xc_vm/console.php tools flush` — удаляет все заблокированные IP-адреса.
3. **Если полностью заблокирован:** Используйте `console.php tools rescue` для создания аварийного кода доступа (см. [CLI Tools](../guides/cli-tools.md)).

---

</details>

<details>
<summary><b>❌ Set-top box gets blocked after a reset/firmware change (its serial or device_id changed, but the panel has the old one)</b></summary>

---

Окно, которое раньше работало, начинает получать значение **Заблокированный IP-адрес** после **сброс настроек, изменение/обновление встроенного ПО, замена оборудования** (или при перемещении MAC в другое поле): теперь оно сообщает значение **другой серийный номер (`sn`) или `device_id`**, отличное от того, которое сохранила панель. На `get_profile` сервер блокирует IP, и портал возвращает 404.

Это **это не ошибка** — защита портала от клонирования, **MAGSCAN**. Для этого требуется ввести серийный номер и сравнить опубликованные `sn` данные с сохраненными `mag_devices.sn`:

- **Нет серийного номера** в запросе → запретить (`[MS] No Serial Number`).
- **Опубликовано `sn` ≠ сохранено на устройстве `sn`** → запретить (`[MS] Invalid Serial Number`).

В обоих случаях IP-адрес записывается в таблицу `blocked_ips` (а оттуда в таблицу iptables), и устройство получает код 404. Если на устройстве установлен флаг **`lock_device`**, то `device_id`, `device_id2` и `hw_version` также проверяются — несоответствие не подтверждается, и устройство показывает, что "ваше устройство неактивно" (без запрета IP-адреса).

**How to fix (for a legitimate box whose data genuinely changed):**

1. **Сбросьте привязку на панели:** откройте это устройство MAG в admin и **очистите сохраненный серийный номер / `device_id`** (или удалите и повторно добавьте устройство). После этого условие "серийный номер уже записан" больше не срабатывает, и при следующем подключении будут привязаны новые значения.
2. **Разблокируйте IP-адрес.** Самый простой способ — **через веб-панель**: откройте **Инструменты → Управление интеллектуальной собственностью** (`/<admin-code>/ips`), в котором перечислены заблокированные IP—адреса - удалите тот, который вам нужен (или очистите весь список). CLI / ручные настройки, если вы не можете добраться до панели:
   - CLI (clear all blocks): `sudo /home/xc_vm/console.php tools flush`;
   - Вручную, для каждого IP: `sudo iptables -D INPUT -s <IP> -j DROP && sudo rm -f /home/xc_vm/tmp/flood/block_<IP>`.

> ⚠️ Настройка `enable_debug_stalker` обходит проверку `lock_device` / изображений, но **НЕ** - последовательный жесткий запрет MAGSCAN (который выполняется ранее) — вам все равно придется очистить сохраненные `sn` в панели.

---

</details>

<details>
<summary><b>❌ Забыли пароль администратора / вообще не можете войти в систему</b></summary>

---

Создайте нового пользователя rescue admin с помощью CLI:

```bash
sudo /home/xc_vm/console.php tools user
```

В результате будут введены случайные имя пользователя и пароль с полными правами администратора. Войдите в систему, измените пароль и по завершении удалите пользователя rescue.

Если сам URL-адрес панели администратора неизвестен, создайте аварийный код доступа:

```bash
sudo /home/xc_vm/console.php tools rescue
```

---

</details>

---

## База данных и конфигурация

<details>
<summary><b>❌ "Не удалось подключиться к базе данных" при запуске</b></summary>

---

Самая распространенная проблема. Причины:

1. **Неверные учетные данные в `config.ini`** — проверить `host`, `port`, `db_user`, `db_pass`, `db_name`
2. **MySQL/MariaDB не запущен** — `sudo systemctl status mariadb`
3. **Сеть недоступна** — Сервер базы данных на другом хосте и порту защищен брандмауэром
4. **Пользователю не хватает привилегий** — повторное предоставление с помощью `console.php tools mysql`

**Чинить:** Отредактируйте `/home/xc_vm/config/config.ini`, затем запустите:

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

---

</details>

<details>
<summary><b>❌ Во время обновления произошел сбой переноса базы данных</b></summary>

---

Перенос `.sql` файлов из `migrations/` выполняется автоматически во время обновления. В случае сбоя одного из них:

- Перенос зарегистрирован со статусом `[WARN]` — он не будет повторен автоматически.
- Распространенные причины: синтаксическая ошибка, таблица уже существует, конфликт внешних ключей, отсутствует привилегия ALTER.

**Debug:**

1. Проверьте, какая миграция завершилась неудачно, в выходных данных консоли.
2. Откройте файл в `migrations/` и проверьте SQL-код.
3. Устраните проблему вручную в MySQL, после чего следующее обновление продолжится с того места, где оно было остановлено.

Дополнительные сведения см. в разделе [Миграция базы данных](../guides/database-migrations.md).

---

</details>

---

## SSL и Nginx

<details>
<summary><b>❌ Сбой генерации SSL-сертификата</b></summary>

---

`console.php certbot` может произойти сбой с разными кодами ошибок:

|Ошибка|Причина|Чинить|
|---|---|---|
|Ошибка 3|Домен - это простой IP-адрес|Для Certbot требуется доменное имя, а не IP-адрес|
|Ошибка 4|Не удалось выполнить пробный запуск — используется порт 80/443| Stop conflicting service: `sudo lsof -i :80` |
|Ошибка 0|Файлы, не найденные после генерации|Проверить `/home/xc_vm/bin/certbot/logs/xc_vm.log`|
|Ошибка 2|Неожиданная ошибка certbot|Проверьте журналы, убедитесь, что DNS разрешает доступ к вашему серверу|

**Также:** Удаление устаревших файлов блокировки, если certbot был прерван:

```bash
sudo rm -f /home/xc_vm/bin/certbot/*/.certbot.lock
```

---

</details>

<details>
<summary><b>❌ Nginx won't reload — port conflicts</b></summary>

---

XC_VM запускает **два** nginx экземпляра:

1. **nginx** (`bin/nginx/`) — HTTP(ы) трафик
2. **nginx_rtmp** (`bin/nginx_rtmp/`) — RTMP потоковое вещание

Каждый из них может выйти из строя, если его порт уже используется.

**Diagnose:**

```bash
sudo netstat -tlnp | grep -E ':80|:443|:1935'
```

**Чинить:** Измените широковещательный порт в настройках панели администратора, затем заново создайте настройки:

```bash
sudo /home/xc_vm/console.php tools ports
```

---

</details>

---

## Обновления и обслуживание

<details>
<summary><b>❌ Ошибка загрузки обновления или несоответствие контрольной суммы</b></summary>

---

Система обновлений загружается с GitHub releases. Если это не удается:

- **Сеть/брандмауэр** блокирует доступ к GitHub
- **Частичная загрузка** — соединение прервано на полпути
- **Несоответствие MD5** — поврежденный файл (обновление благополучно прервано)

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

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

---

</details>

<details>
<summary><b>❌ Обслуживание неожиданно прекращается или не завершается полностью</b></summary>

---

Сервисная команда использует нарастающие сигналы об остановке. Если процессы зависают:

```bash
# Check for stuck processes
ps -u xc_vm

# Force kill if necessary
sudo killall -9 -u xc_vm

# Restart cleanly
sudo /home/xc_vm/console.php service start
```

Common causes: PHP transaction deadlock, infinite loop in stream processing, or network socket timeout waiting for a response.

---

</details>

---

## Разрешения и система

<details>
<summary><b>❌ Ошибки, связанные с отказом в разрешении, продолжают появляться</b></summary>

---

Запустите команду status — она автоматически устранит все известные проблемы с правами доступа:

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

Что это исправляет:
- PHP-FPM права доступа к сокету (`bin/php/sockets/*`)
- Владелец каталога содержимого (`content/streams/`)
- Владение конфигурационным файлом (`config/`)
- Исполняемый бит на `daemons.sh`
- Права доступа к сетевому интерфейсу (`/sys/class/net`)

Если после каждой перезагрузки разрешения нарушаются, проверьте, существует ли системный пользователь `xc_vm`, которому принадлежит `/home/xc_vm`.

---

</details>

<details>
<summary><b>❌ Балансировщик нагрузки отображается как автономный / не удается синхронизировать с основным</b></summary>

---

Серверы LB опрашивают MAIN по протоколу HTTP и обрабатывают сигналы. При сбое синхронизации:

1. **Сеть:** LB не может связаться с HTTP—портом MAIN - проверьте правила брандмауэра
2. **База данных:** LB не удается подключиться к MySQL — повторно предоставить привилегии MAIN:
   ```bash
   sudo /home/xc_vm/console.php tools mysql
   ```
3. **Перерыв:** Если `last_check_ago` превышает 180 секунд, сервер помечается как отключенный

**Отлаживать:** Запустите на главной, чтобы проверить подключение:

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

---

</details>

---

📘 *Эта страница обновляется с течением времени. Если вы обнаружите новую распространенную проблему, пожалуйста, сообщите об этом в разделе [Проблемы](https://github.com/Vateron-Media/XC_VM/issues).*

---