Перейти к основному содержимому

Частые ошибки

Ниже — проблемы, с которыми сталкиваются чаще всего. Формат один: симптом → причина → решение. Начинайте с логов — почти всегда причина видна в них:

docker compose logs --tail=100 xpanel
docker compose ps
Совет

Полный набор диагностических команд — в разделе Полезные команды.

Краткая шпаргалка: что видите — на что смотреть.

Симптом в логе или интерфейсеВероятная причина
Reverse proxy and HTTPS are requiredнет заголовков X-Forwarded-* от прокси
❌ METRICS_USER / ❌ METRICS_PASSне заданы переменные метрик
Нода не подключаетсяNODE_PORT закрыт или SECRET_KEY неполный
address already in useпорт занят другим процессом
certbot завершается ошибкойDNS, порт 80 или чужой server_name
xpanel-db в состоянии unhealthy.env, том или версия PostgreSQL
502 Bad Gateway от nginxпанель не слушает 127.0.0.1:3000
Вход перестал работатьизменён APP_SECRET

«Reverse proxy and HTTPS are required»​

Симптом. Панель не открывается, в логе xpanel — строка Reverse proxy and HTTPS are required.

Причина. Запрос дошёл до панели без заголовков X-Forwarded-For и X-Forwarded-Proto: https. В коде панели есть middleware, который в этом случае разрывает соединение.

Решение. Убедитесь, что в конфиге nginx перед панелью есть обе строки:

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

Открывайте панель по https://, а не по http://. Если TLS завершается раньше (на CDN или балансировщике), не подменяйте X-Forwarded-Proto значением http. Готовые конфиги — в разделе Обратный прокси.

Не заданы METRICS_USER и METRICS_PASS​

Симптом. Контейнер xpanel перезапускается, в логе — ❌ METRICS_USER или ❌ METRICS_PASS.

Причина. Переменные метрик обязательны: без них панель не стартует.

Решение. Допишите в /opt/xlada/.env и перезапустите стек:

METRICS_USER=xpanel
METRICS_PASS=<надёжный пароль>
docker compose up -d

Нода не появляется в панели​

Симптом. Нода создана, но в панели остаётся неподключённой.

Причина. Обычно одно из трёх: NODE_PORT недоступен с сервера панели, SECRET_KEY скопирован не целиком либо контейнер ноды не запустился.

Решение. Проверяйте по порядку:

  1. docker logs -f xpanel-node — при неверном ключе нода сама печатает причину.
  2. С сервера панели: nc -vz <ip ноды> 2222.
  3. Убедитесь, что ключ вставлен целиком, без переносов строк.
  4. Откройте порт 2222 в firewall только для IP панели.

Подробнее — в разделе Установка ноды.

Примечание

У каждой ноды собственный SECRET_KEY и собственный сертификат. Общий ключ на несколько серверов не предусмотрен — переносить его с одной ноды на другую нельзя.

Конфликт портов​

Симптом. Контейнер не стартует с address already in use, либо Xray на ноде не слушает заданный порт.

Причина. Порт занят другим процессом: 3000, 3001, 3010 на сервере панели или порт inbound на ноде.

Решение. Найдите владельца порта и освободите его:

ss -tlnp | grep -E ':(3000|3001|3010|2222)\b'

Если изменить порт проще, чем освободить, поправьте APP_PORT или METRICS_PORT в .env и не забудьте обновить proxy_pass в nginx. На ноде проверьте, что контейнер запущен с --network host: проброс портов ломает определение реального IP клиента.

Сертификат не выпускается​

Симптом. certbot --nginx -d panel.example.com завершается ошибкой.

Причина. Домен не указывает на этот сервер, закрыт порт 80 либо домен уже обслуживается другим виртуальным хостом.

Решение.

dig +short panel.example.com   # должен вернуть IP сервера панели
ss -tlnp | grep ':80'
certbot certificates           # что уже выпущено
certbot renew --dry-run        # проверка автопродления

Сверьте server_name в конфиге nginx, затем nginx -t && systemctl reload nginx. Убедитесь, что таймер автопродления активен: systemctl list-timers | grep certbot.

База данных не поднимается​

Симптом. xpanel ждёт базу и падает, xpanel-db в состоянии unhealthy или постоянно перезапускается.

Причина. Чаще всего неверный DATABASE_URL, несовпадение POSTGRES_PASSWORD с уже существующим томом или несовместимая мажорная версия PostgreSQL на старом каталоге данных.

Решение.

docker compose ps
docker compose logs --tail=100 xpanel-db
docker exec xpanel-db pg_isready -U xpanel -d xpanel

Сверьте POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB и DATABASE_URL. Не переименовывайте тома и сервисы: при следующем запуске compose создаст новые пустые. Каталог данных PostgreSQL несовместим между мажорными версиями, поэтому переход на новую версию делают только через дамп и восстановление — см. Переезд с Remnawave.

502 Bad Gateway от nginx​

Симптом. nginx отдаёт 502 на https://panel.example.com.

Причина. За proxy_pass никого нет: контейнер панели не запущен, не прошёл миграции или слушает другой порт.

Решение.

docker compose ps
curl -sI http://127.0.0.1:3000
docker compose logs --tail=100 xpanel

Дождитесь в логе строк XLADA Backend v1.1.7 и Nest application successfully started. Если APP_PORT менялся, поправьте proxy_pass http://127.0.0.1:<порт> и перезагрузите nginx.

Вход не работает после смены APP_SECRET​

Симптом. Пароль администратора перестал подходить, коды TOTP не принимаются, активные сессии сброшены.

Причина. APP_SECRET изменили после первого запуска. От него зависят хеши паролей, JWT и шифрование секрета TOTP. Тот же эффект даёт значение change_me, оставленное в .env.

Решение. Верните прежнее значение APP_SECRET из резервной копии .env и выполните docker compose up -d. Если оригинал утерян, войти можно только сбросом через базу. Секрет генерируют заранее (openssl rand -hex 32) и хранят в менеджере секретов — см. Безопасность панели.

Что дальше​