Reverse proxy в Nginx: proxy_pass и заголовки бэкенда

Что такое reverse proxy в Nginx и зачем он нужен

Reverse proxy — сервер, который принимает запросы от клиентов и передаёт их на один или несколько бэкендов: приложение на Node.js, Python, Java или другой инстанс Nginx. Клиент обращается только к прокси и не видит внутреннюю структуру сервиса. Nginx умеет работать как reverse proxy из коробки — для этого достаточно директивы proxy_pass внутри блока location.

Reverse proxy на Nginx решает несколько задач сразу: терминирует TLS перед приложением, отдаёт статику напрямую в обход медленного бэкенда, скрывает внутренние порты и IP-адреса, добавляет заголовки безопасности. На VDS ZevsHost.net такую схему часто ставят перед Node.js или Python-приложением: Nginx слушает порт 80 и 443, а сам сервис работает на localhost и наружу не смотрит.

• Балансировка нагрузки между несколькими копиями приложения.
• Единый SSL-сертификат на весь набор внутренних сервисов.
• Кэширование ответов бэкенда без изменения кода приложения.

Настройка proxy_pass: базовый пример

Минимальный конфиг — блок server с одним location, который пересылает все запросы на локальное приложение по HTTP.

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
    }
}

Если location задан с завершающим слэшем, а в proxy_pass указан путь, Nginx заменяет совпавшую часть URI на этот путь. Без пути в proxy_pass исходный URI передаётся бэкенду как есть — это самый предсказуемый вариант, особенно если приложение само разбирает маршруты. Подробнее про правила совпадения путей — в статье про приоритет location.

Передача заголовков клиента на бэкенд

По умолчанию Nginx заменяет заголовок Host на адрес бэкенда и не сообщает приложению реальный IP посетителя. Если это не поправить, в логах приложения будет виден только IP самого Nginx, а ссылки в письмах и редиректах могут указывать на localhost вместо настоящего домена.

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;
}

Приложение на бэкенде должно доверять этим заголовкам только если запрос пришёл именно от локального Nginx, иначе клиент сможет подделать X-Forwarded-For напрямую.

Таймауты и буферы: за что отвечает каждый параметр

Если бэкенд отвечает медленно или отдаёт большой ответ, стандартные таймауты и буферы Nginx могут оборвать соединение раньше времени. Значения ниже — рабочая точка отсчёта для обычного веб-приложения, не для стриминга.

Слишком короткий proxy_read_timeout — частая причина 504 Gateway Timeout на тяжёлых запросах вроде экспорта отчёта или загрузки файла. Слишком маленькие буферы заставляют Nginx писать временные файлы на диск, что заметно на VDS с медленным диском.

Reverse proxy к нескольким серверам через upstream

Если приложение работает в нескольких копиях, вместо одного адреса в proxy_pass используют блок upstream с списком серверов.

upstream backend {
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
    server 127.0.0.1:3002 backup;
}

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://backend;
    }
}

Nginx по умолчанию распределяет запросы по кругу (round robin) и пропускает сервер, помеченный backup, пока остальные живы. Про алгоритмы распределения нагрузки и проверку здоровья бэкендов — в отдельной статье про балансировщик Nginx. Если перед reverse proxy нужен ещё и HTTPS, сертификат настраивается на внешнем сервере — см. статью про SSL/TLS в Nginx.

Чек-лист: проверка reverse proxy перед продакшеном

• Заголовки Host, X-Real-IP и X-Forwarded-For переданы бэкенду и видны в его логах.
• Команда nginx -t проходит без ошибок после каждой правки конфига.
• Таймауты подобраны под реальное время ответа приложения, а не оставлены по умолчанию.
• При нескольких бэкендах в upstream настроен хотя бы один запасной сервер.
• Ответ проверен командой curl -I http://app.example.com/ — заголовки и код статуса совпадают с ожидаемыми.

Частые вопросы

Что будет, если не настроить передачу заголовков X-Real-IP и X-Forwarded-For на бэкенд?

Если заголовки Host, X-Real-IP и X-Forwarded-For не передать, приложение на бэкенде увидит в логах только адрес самого Nginx, а не реальный IP посетителя сайта. Из-за этого ссылки в письмах и редиректах могут указывать на внутренний адрес вместо настоящего домена, а любая логика, завязанная на IP клиента, перестанет работать корректно.

Можно ли полностью доверять заголовку X-Forwarded-For, который передаёт клиент?

Нет, доверять этому заголовку без ограничений нельзя: если запрос приходит не через локальный Nginx, а напрямую от клиента, он может подставить в X-Forwarded-For произвольное значение. Приложение должно принимать этот заголовок как достоверный только тогда, когда точно уверено, что запрос прошёл через ваш собственный прокси, а не от внешнего источника.

Почему при обращении через reverse proxy иногда возникает ошибка 504 Gateway Timeout?

Ошибка 504 обычно возникает, когда ответ бэкенда занимает больше времени, чем разрешает proxy_read_timeout — например, при экспорте тяжёлого отчёта или долгой загрузке файла. Nginx обрывает соединение раньше, чем приложение успевает ответить. Решение — увеличить именно этот таймаут для медленных запросов, не трогая остальные настройки прокси.

Подходят ли типичные значения таймаутов и буферов reverse proxy для потокового видео или больших файлов?

Нет, значения из статьи — это рабочая точка отсчёта именно для обычных веб-запросов, а не для стриминга. Потоковая передача видео или крупных файлов требует другого подхода к буферам и таймаутам, иначе соединение будет обрываться или Nginx начнёт писать временные файлы на диск, что особенно заметно на сервере с медленным диском.