# 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>❌ Забыл пароль админа / не могу войти вообще</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).*

---