remnawave · Liremant · Oct 29, 2025 · Oct 30, 2025 · Oct 30, 2025 · Nov 1, 2025
diff --git a/docs/common-issues.md b/docs/common-issues.md
@@ -0,0 +1,250 @@
+# Устранение неполадок (Troubleshooting)
+
+В этом разделе собраны часто встречающиеся проблемы при эксплуатации панели Remnawave, признаки их проявления и пошаговые инструкции по диагностике и устранению. Для каждой проблемы указаны симптомы, вероятные причины и практические проверки.
+
+---
+
+## 502 Bad Gateway на странице подписки
+
+### Симптомы
+
+- При переходе на домен страницы подписки возвращается 502 Bad Gateway.
+- Ссылки на страницу подписки не работают или возвращают ошибку сервера.
+
+### Частые причины и шаги решения
+
+1. Неправильный путь URL
+   - Проблема: Вы открываете корневой домен без UUID подписки.
+   - Решение: Используйте формат:
+```
+https://sub.example.com/<shortUuid>
+```
+
+2. Конфигурация реверс-прокси
+   - Проблема: Прокси не перенаправляет запросы на контейнер страницы подписки.
+   - Решение: Убедитесь, что прокси направляет трафик на `remnawave-subscription-page:3010`.
+   - Проверка: Посмотрите логи контейнера страницы подписки:
+```bash
+docker compose logs -t -f
+```
+
+3. Переменные окружения
+   - Проверьте значение `SUB_PUBLIC_DOMAIN` в `.env` панели.
+   - После правки перезапустите контейнер панели.
+
+4. Общие проверки при 502
+   - Убедитесь, что DNS указывает на правильный IP.
+   - Проверьте доступность контейнера/бэкенда подписки.
+   - Проверьте таймауты в конфигурации реверс-прокси.
+   - Проверьте правила файрвола/WAF.
+
+---
+
+## "timeout of 45000ms exceeded" в панели
+
+### Симптомы
+
+- В интерфейсе панели появляется сообщение об ошибке таймаута при операциях с нодами (например, при получении статуса или управлении).
+
+### Частые причины и шаги решения
+
+1. Неправильная конфигурация порта ноды
+   - Проблема: Панель не может подключиться к REST API ноды по указанному порту.
+   - Решение: Убедитесь, что значение `Node Port` на ноде совпадает с портом, который использовался при генерации docker-compose для панели.
+   - Проверка: С хоста панели проверьте доступность порта ноды (telnet/curl).
+
+2. Сетевые проблемы
+   - Проблема: Блокировки/высокая задержка между панелью и нодой.
+   - Решение: Обеспечьте стабильное сетевое соединение; по возможности разместите ноду на сервере с надёжным каналом.
+   - Опция: Для сложных топологий рассмотрите Cloudflare Tunnel.
+
+3. Конфигурация ноды
+   - Проверьте соответствие переменных окружения ноды настройкам панели.
+   - Просмотрите логи контейнера ноды:
+```bash
+docker compose logs -t -f
+```
+   - Убедитесь, что нода запустилась без ошибок привязки портов.
+
+### Чеклист (короткий)
+
+- [ ] В профиле пользователя выбран активный сквад.
+- [ ] Внутреннему скваду назначены инбаунды.
+- [ ] Есть минимум один хост и он включён.
+- [ ] Хост привязан к инбаунду, выданному скваду.
+
+---
+
+## 502 после обновления панели
+
+### Симптомы
+
+- После обновления панели часть запросов возвращает 502.
+
+### Решения
+
+1. Перезапуск сервисов
+   - Следуйте разделу Upgrading в документации.
+   - Перезапустите панель и зависимые сервисы.
+   - Убедитесь, что контейнеры используют обновлённые образы.
+
+2. Реверс-прокси
+   - Если прокси работает отдельно, перезапустите его.
+   - Проверьте, что его конфигурация по-прежнему указывает на правильные контейнеры/сети.
+
+---
+
+## Telegram OAuth: "domain invalid"
+
+### Симптомы
+
+- При попытке авторизации через Telegram появляется "domain invalid".
+- OAuth не проходит валидацию.
+
+### Решение
+
+1. Настройка домена в BotFather
+   - Откройте @BotFather → Bot Settings → Domain.
+   - Укажите домен панели, например:
+     ```
+     https://panel.domain.com
+     ```
+   - Сохраните настройки в панели: Settings → Telegram.
+
+2. Ограничения Telegram
+   - Важно: OAuth Telegram не поддерживает домены в зоне `.xyz`. Используйте `.com`, `.net`, `.org` и т.д.
+   - Неправильный домен приведёт к сбою верификации OAuth.
+
+---
+
+## ECONNREFUSED после переустановки ноды
+
+### Симптомы
+
+- Панель не может подключиться к ноде; в логах — ECONNREFUSED.
+
+### Решения
+
+1. Проверьте переменные окружения
+   - Убедитесь, что параметры ноды соответствуют тем, которые сгенерировала панель.
+   - Подтвердите корректность `Node Port`.
+
+2. Перезапуск и проверка ноды
+   - Перезапустите ноду:
+     ```bash
+     docker compose down && docker compose up -d
+     ```
+   - Просмотрите логи:
+     ```bash
+     docker compose logs -f -t
+     ```
+   - Убедитесь в отсутствии ошибок привязки портов и в доступности порта.
+
+3. Конфигурация URL панели
+   - Проверьте `REMNAWAVE_PANEL_URL` для страницы подписки — он должен указывать на достижимый домен панели или внутренний сервис.
+
+---
+
+## Ошибки collation после обновления PostgreSQL
+
+### Симптомы
+
+- После мажорного обновления PostgreSQL возникают ошибки, связанные с collation базы данных.
+
+### Решение (rescue CLI)
+
+1. Откройте контейнер панели:
+```bash
+docker exec -it remnawave remnawave
+```
+2. В rescue CLI выполните действие:
+```
+● Fix Collation (Fix Collation issues for current database)
+```
+3. Перезапустите панель:
+```bash
+docker compose down && docker compose up -d
+```
+
+Примечание: такие ошибки чаще появляются при смене мажорной версии PostgreSQL, когда collations старой БД не совпадают с требуемыми новой версии.
+
+---
+
+## Ключевые переменные окружения
+
+Конфигурация панели:
+
+```bash
+# Домен панели для CORS/UI
+FRONT_END_DOMAIN=panel.yourdomain.com
+
+# Публичный URL страницы подписки
+SUB_PUBLIC_DOMAIN=sub.yourdomain.com
+# или для bundled-установки:
+# SUB_PUBLIC_DOMAIN=panel.yourdomain.com/api/sub
+```
+
+Страница подписки:
+
+```bash
+# Кастомный префикс подписки (опционально)
+CUSTOM_SUB_PREFIX=/custom-path
+
+# URL панели для доступа к API
+REMNAWAVE_PANEL_URL=https://panel.yourdomain.com
+```
+
+Дополнительные опции:
+
+```bash
+# Включить документацию API
+IS_DOCS_ENABLED=true
+SWAGGER_PATH=/swagger
+SCALAR_PATH=/scalar
+
+# Метрики Prometheus
+METRICS_USER=admin
+METRICS_PASS=password
+```
+
+Важно: После изменения переменных окружения перезапускайте соответствующие сервисы.
+
+---
+
+## Быстрый диагностический чек-лист
+
+При 502:
+- [ ] DNS резолвится в правильный IP.
+- [ ] Контейнер бэкенда запущен.
+- [ ] Конфигурация реверс-прокси корректна.
+- [ ] Сервис доступен по правильному пути (домен vs подпуть).
+- [ ] Таймауты прокси настроены адекватно.
+- [ ] Переменные окружения установлены верно.
+- [ ] Сервисы перезапущены после изменений.
+
+При таймаутах:
+- [ ] Node Port совпадает в конфигурации панели и ноды.
+- [ ] Панель может достучаться до порта ноды (telnet/curl).
+- [ ] Контейнер ноды запущен.
+- [ ] Сетевое подключение стабильное.
+- [ ] Нет блокировок файрвола между панелью и нодой.
+
+При проблемах с Telegram OAuth:
+- [ ] Домен правильно настроен в BotFather.
+- [ ] Используется поддерживаемая доменная зона (не `.xyz`).
+- [ ] Настройки сохранены в панели.
+
+---
+
+## Дополнительные ресурсы
+
+- Руководство по установке: https://remna.st/docs/overview/quick-start/
+- Инструкция по использованию панели: https://remna.st/blog/learn
+- Установка панели: https://remna.st/docs/install/remnawave-panel/
+- Установка ноды: https://remna.st/docs/install/remnawave-node/
+- Настройка страницы подписки: https://remna.st/docs/install/subscription-page/bundled/
+- Переменные окружения: https://remna.st/docs/install/environment-variables/
+- Руководство по обновлению: https://remna.st/docs/install/upgrading/
+- Документация API: https://remna.st/api/
+- Telegram-канал: https://t.me/s/remnawave
+- GitHub Issues: https://github.com/remnawave/panel/issues