XC_VM/docs/ru/info/faq.md

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

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

---

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

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

---

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

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

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

> 🧩 Где `291` — это **ID вашего стрима** (замените на свой).

---

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

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

---

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

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

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

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

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

```bash
sudo apt install <имя_библиотеки>
```

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

> 💬 Сообщите мне, если потребуется добавить библиотеку в установку.

---

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

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

---

### Резюме

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

---

</details>

<details>
<summary><b>❌ Стриминг обрывается с ошибкой «IP_MISMATCH» или «TOKEN_EXPIRED»</b></summary>

---

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

- **TOKEN_EXPIRED** — сессионный токен истёк. Пользователю нужно переподключиться.
- **IP_MISMATCH** — IP пользователя сменился во время стрима (часто расценивается как шаринг аккаунта).

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

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

---

</details>

---

## Проблемы с входом и доступом

<details>
<summary><b>❌ IP заблокирован — не могу войти</b></summary>

---

Защита от brute-force блокирует IP после превышения лимита неудачных попыток входа. Управляется настройками:

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

**Как разблокировать:**

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

---

</details>

<details>
<summary><b>❌ Приставка блокируется после сброса/смены прошивки (изменился serial или device_id, а в панели прописан старый)</b></summary>

---

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

Это **не баг**, а анти-клон защита портала **MAGSCAN**: она требует серийный номер и сверяет присланный `sn` с сохранённым в `mag_devices.sn`. Логика:

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

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

**Как исправить (для легитимной приставки, у которой реально сменились данные):**

1. **Сбросить привязку в панели:** в админке откройте это MAG-устройство и **очистите сохранённый серийный номер / `device_id`** (или удалите и заведите устройство заново). После этого условие «`sn` уже записан» перестаёт срабатывать, и при следующем подключении панель привяжет новые значения.
2. **Разблокировать IP.** Проще всего — **через веб-панель**: откройте страницу **Инструменты → Управление IP** (`/<код_админа>/ips`), там виден список заблокированных IP — удалите нужный (или очистите весь список). CLI/ручные способы, если нет доступа к панели:
   - CLI (сбросить все блокировки): `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>

---

Создайте нового пользователя-администратора через 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>❌ «Couldn't connect to database» при запуске</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.

**Отладка:**

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

Подробности: [Миграции БД](ru-ru/guides/cli-tools.md#обновление-бд-после-обновления-версии).

---

</details>

---

## SSL и Nginx

<details>
<summary><b>❌ Генерация SSL-сертификата падает</b></summary>

---

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

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

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

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

---

</details>

<details>
<summary><b>❌ Nginx не перезапускается — конфликт портов</b></summary>

---

XC_VM запускает **два** инстанса nginx:

1. **nginx** (`bin/nginx/`) — HTTP(S)-трафик
2. **nginx_rtmp** (`bin/nginx_rtmp/`) — RTMP-стриминг

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

**Диагностика:**

```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>

---

Команда service использует эскалацию сигналов завершения. Если процессы зависли:

```bash
# Проверить зависшие процессы
ps -u xc_vm

# Принудительное завершение при необходимости
sudo killall -9 -u xc_vm

# Чистый перезапуск
sudo /home/xc_vm/console.php service start
```

Частые причины: deadlock в PHP-транзакции, бесконечный цикл в обработке стрима, или сетевой сокет ожидает ответ.

---

</details>

---

## Права и система

<details>
<summary><b>❌ Ошибки «Permission denied» возвращаются снова и снова</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>❌ Load Balancer показан как offline / не синхронизируется с MAIN</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 секунд, сервер помечается как offline

**Отладка:** Запустите на MAIN для проверки связи:

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

---

</details>

---

📘 *Эта страница обновляется со временем. Если вы нашли новую типовую проблему — предложите её в [Issues](https://github.com/Vateron-Media/XC_VM/issues).*

---