Nginx как обратный прокси: типичные ошибки и как их исправить

Коротко о главном

Nginx часто ставят перед приложением на Node.js, Python или Go. Он принимает TLS, отдаёт статику, балансирует нагрузку и скрывает backend от интернета. Настройка кажется простой, но ошибки в заголовках и таймаутах встречаются постоянно.

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

Nginx как обратный прокси редко ломается сам по себе. Чаще проблема в неверной конфигурации, устаревшей версии или команде, скопированной без понимания. Разберём типичные сбои и способы их исправления.

Почему это происходит

Ошибки почти всегда связаны с контекстом: другая версия пакета, не тот пользователь, устаревший конфиг или команда из руководства для другой системы. Nginx как обратный прокси не исключение. Поэтому сначала фиксируем исходное состояние, затем меняем одну вещь за раз.

Типичные ошибки

Ниже — сбои, которые встречаются чаще всего. Перед исправлением сохраните текущие конфиги и запишите, какие изменения вносите: так проще откатиться.

1. 502 Bad Gateway

Backend не запущен или слушает другой адрес. Проверьте systemctl status приложения и curl localhost:порт.

2. 504 Gateway Timeout

Увеличьте proxy_read_timeout или оптимизируйте запрос. Не ставьте бесконечный таймаут без причины.

3. Неправильный редирект на HTTP

Проверьте X-Forwarded-Proto и настройки приложения. Иногда нужен trust proxy.

Как настроить правильно

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

Установка

В Debian, Ubuntu и Linux Mint используется пакетный менеджер APT:

sudo apt install nginx certbot python3-certbot-nginx

В Fedora и RHEL-совместимых системах пакет ставится через DNF:

sudo dnf install nginx certbot python3-certbot-nginx

В Arch Linux и производных пакет доступен в официальных репозиториях:

sudo pacman -S nginx certbot certbot-nginx

1. Создайте конфиг сайта

Не правьте основной nginx.conf для каждого сайта. Используйте sites-available и симлинк в sites-enabled.

sudo nano /etc/nginx/sites-available/example.conf
sudo ln -s /etc/nginx/sites-available/example.conf /etc/nginx/sites-enabled/

2. Проверьте и перезагрузите

nginx -t проверяет синтаксис. Reload применяет конфигурацию без разрыва соединений.

sudo nginx -t
sudo systemctl reload nginx

3. Включите HTTPS

Certbot получит сертификат и добавит редирект. Убедитесь, что домен указывает на сервер, а порт 80 доступен.

sudo certbot --nginx -d example.com -d www.example.com
sudo certbot renew --dry-run

4. Настройте WebSocket

Для WebSocket нужны заголовки Upgrade и Connection, иначе соединение будет сбрасываться.

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Рабочий конфиг

Начните с минимального рабочего варианта. Не копируйте большой конфиг целиком: добавляйте параметры по одному и проверяйте результат после каждого изменения.

server {
    listen 80;
    server_name example.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Практические советы

Эти рекомендации проверены на повседневных задачах. Начните с тех, которые закрывают вашу текущую боль, а не со всего списка сразу.

Совет 1. Не открывайте backend-порт в интернет, если он слушает localhost.

Не открывайте backend-порт в интернет, если он слушает localhost.

Совет 2. Передавайте X-Forwarded-* заголовки, иначе приложение видит неверный I

Передавайте X-Forwarded-* заголовки, иначе приложение видит неверный IP и схему.

Совет 3. Ограничивайте размер тела запроса для загрузок.

Ограничивайте размер тела запроса для загрузок.

Совет 4. Настройте gzip или brotli для текстовых ответов.

Настройте gzip или brotli для текстовых ответов.

Профилактика

Большинство повторяющихся сбоев с Nginx как обратный прокси связано не с ошибкой в самой программе, а с окружением: обновились зависимости, изменился путь, закончилось место или другой администратор поправил конфиг. Поэтому профилактика начинается с фиксации исходного состояния.

Сохраните рабочий конфиг в систему контроля версий, добавьте короткий комментарий о том, зачем нужен каждый нестандартный параметр, и запишите команду проверки. Через месяц вы скажете себе спасибо: восстановить логику по чужому файлу без пояснений почти невозможно.

Итог

Большинство ошибок с Nginx как обратный прокси лечится не переустановкой, а проверкой конфигурации, логов и прав доступа. Действуйте по одному изменению за раз — и причина быстро найдётся.