Nginx как reverse proxy: настройка и типичные ошибки

Зачем ставить Nginx перед приложением

Reverse proxy — это промежуточный сервер, который принимает входящие запросы от клиентов и перенаправляет их на один или несколько серверов приложения, находящихся позади него и обычно недоступных из интернета напрямую. Клиент обращается только к Nginx, ничего не зная о том, что реальная обработка запроса происходит на другом процессе, порту или даже отдельном сервере.

Для приложений на Node.js, Python (Django, Flask, FastAPI) или Java такая связка стала стандартом де-факто по нескольким практическим причинам сразу. Встроенные HTTP-серверы большинства фреймворков разработки не рассчитаны на приём трафика напрямую из интернета: они не умеют эффективно раздавать статику, не имеют встроенной защиты от медленных клиентов и не поддерживают TLS-терминацию с той же гибкостью, что зрелый веб-сервер вроде Nginx.

Никогда не выставляйте сервер приложения напрямую в интернет — между ним и внешним миром всегда должен быть полноценный веб-сервер, который возьмёт на себя TLS, статику и защиту от аномального трафика.

Распространённая рекомендация в руководствах по деплою веб-приложений

Помимо изоляции, Nginx как reverse proxy решает ещё несколько задач одновременно: терминирует HTTPS, чтобы само приложение работало по простому HTTP внутри доверенной сети; отдаёт статические файлы (изображения, CSS, JS) напрямую, не нагружая процесс приложения; и служит единой точкой для логирования, лимитов скорости и балансировки нагрузки между несколькими экземплярами приложения, если оно масштабируется горизонтально.

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

Директива proxy_pass и минимальный конфиг

Базовая настройка reverse proxy в Nginx строится вокруг директивы proxy_pass внутри location-блока — она указывает адрес и порт, на который нужно перенаправить запрос, попавший под условие этого location.

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

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

Этого минимального конфига уже достаточно, чтобы запросы к app.example.ru передавались на локальный процесс, слушающий порт 3000, — типичная ситуация для приложения на Express.js, FastAPI или любом другом фреймворке, поднимающем встроенный HTTP-сервер. Однако такой конфиг ещё не решает ни одну из задач, ради которых обычно и ставят прокси: клиентский IP не передаётся, таймауты остаются на значениях по умолчанию, а буферизация работает без учёта особенностей конкретного бэкенда.

Важно, что адрес в proxy_pass может указывать не только на localhost — это может быть IP-адрес другого сервера в той же приватной сети, доменное имя внутреннего сервиса или имя upstream-блока, объединяющего сразу несколько бэкендов для балансировки нагрузки, о чём подробнее ниже в этой статье.

Ловушка со слэшем в конце proxy_pass

Один из самых частых источников путаницы при настройке reverse proxy в Nginx — поведение слэша в конце адреса в proxy_pass в сочетании с префиксом самого location. Если в proxy_pass указан URI (то есть путь после адреса, даже если это просто слэш), Nginx заменяет совпавшую часть URI запроса на этот путь; если URI не указан вовсе, Nginx передаёт исходный запрос на бэкенд целиком, без изменений.

# Вариант 1: префикс /api/ будет ОТБРОШЕН перед пересылкой
location /api/ {
    proxy_pass http://127.0.0.1:3000/;
}

# Вариант 2: префикс /api/ будет СОХРАНЁН и уйдёт на бэкенд как есть
location /api/ {
    proxy_pass http://127.0.0.1:3000;
}

В первом варианте запрос к /api/users будет передан на бэкенд как /users — слэш после порта в proxy_pass задаёт URI (в данном случае корневой), и Nginx заменяет им ту часть исходного пути, что совпала с location. Во втором варианте тот же запрос уйдёт на бэкенд как /api/users, потому что proxy_pass указывает только адрес без URI, и Nginx пересылает запрос без модификации пути.

Практическое следствие: если приложение на бэкенде ожидает запросы без префикса /api/ (обычный случай, когда префикс — это чисто внешний маршрутизирующий признак для Nginx), нужен именно первый вариант со слэшем; если приложение само построено с учётом этого префикса в своих маршрутах — нужен второй. Перепутать эти два варианта — самая частая причина внезапных 404 сразу после того, как reverse proxy вроде бы настроен правильно и не выдаёт никаких ошибок в логах Nginx.

Передача реальных данных о клиенте: X-Forwarded-For, X-Real-IP, Host

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

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

Заголовок Host передаёт приложению то доменное имя, к которому обратился клиент, — без него бэкенд может видеть только внутренний адрес вида 127.0.0.1:3000, что ломает генерацию абсолютных ссылок и редиректов внутри самого приложения. X-Real-IP содержит настоящий IP-адрес клиента одним значением, а X-Forwarded-For — цепочку адресов через запятую, если запрос уже проходил через другие прокси по пути, что полезно при многоуровневой инфраструктуре с CDN перед основным сервером.

X-Forwarded-Proto сообщает приложению, каким протоколом (http или https) реально пользовался клиент, — это критично, если TLS терминируется на Nginx, а приложение само формирует абсолютные ссылки: без этого заголовка приложение может решить, что весь трафик идёт по http, и генерировать небезопасные ссылки даже для посетителей, зашедших по https.

Многие фреймворки не доверяют этим заголовкам по умолчанию из соображений безопасности — ведь клиент теоретически тоже мог бы прислать поддельный X-Forwarded-For напрямую, минуя прокси. Поэтому на стороне приложения обычно нужно явно включить доверие к заголовкам от прокси (например, настройка trusted proxies в Django или Express) и одновременно убедиться, что порт приложения закрыт от прямого доступа из интернета — иначе поддельный заголовок от внешнего клиента будет восприниматься как достоверный.

Таймауты: connect, read и send

Nginx управляет тремя независимыми таймаутами при обращении к бэкенду, и путаница между ними — частая причина преждевременных обрывов легитимных, но медленных запросов. proxy_connect_timeout ограничивает время на установление TCP-соединения с бэкендом — обычно этого времени достаточно в пределах секунд, даже если бэкенд запаздывает с самим ответом, поскольку соединение с уже запущенным процессом на том же сервере устанавливается почти мгновенно.

proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

proxy_send_timeout ограничивает время между двумя последовательными операциями записи данных запроса на сторону бэкенда, а proxy_read_timeout — время между двумя последовательными операциями чтения ответа от бэкенда. Именно proxy_read_timeout чаще всего приходится увеличивать: значение по умолчанию (60 секунд) может оказаться недостаточным для эндпоинтов, выполняющих тяжёлую обработку — генерацию отчёта, конвертацию видео, синхронный вызов внешнего API с непредсказуемой задержкой.

Повышать таймауты стоит точечно, для конкретных location, а не глобально для всего сайта — если поднять proxy_read_timeout до нескольких минут для всех запросов подряд, зависшее по ошибке (а не по объективной причине) соединение с бэкендом будет удерживать worker-процесс Nginx и слот в приложении заметно дольше необходимого, что при некотором количестве таких зависаний способно исчерпать доступные соединения и повлиять на отзывчивость сайта для остальных посетителей.

Отдельно стоит проверить, что таймауты самого приложения на бэкенде (например, таймаут воркера в Gunicorn для Python или таймаут HTTP-сервера в Node.js) не короче, чем proxy_read_timeout в Nginx — если бэкенд обрывает обработку раньше, чем Nginx готов ждать ответ, клиент получит либо пустой ответ, либо ошибку 502 несмотря на, казалось бы, щедро настроенные таймауты именно на стороне Nginx.

Буферизация ответов и особый случай WebSocket и Server-Sent Events

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

proxy_buffering on;
proxy_buffers 8 16k;
proxy_buffer_size 16k;

Такая буферизация обычно полезна: приложение отдаёт ответ Nginx максимально быстро, освобождая свой worker или поток для следующего запроса, а дальнейшую, возможно медленную, передачу клиенту с плохим каналом связи берёт на себя Nginx. Для приложений, которые часто отдают крупные ответы (JSON-выгрузки, отчёты), стоит увеличить proxy_buffers и proxy_buffer_size относительно значений по умолчанию, чтобы избежать лишней записи временных файлов на диск при превышении размера буфера в памяти.

Для WebSocket-соединений и Server-Sent Events (SSE) буферизация в её обычном виде неприменима в принципе — эти протоколы держат соединение открытым и передают данные по мере появления событий, а не единым завершённым ответом, который можно буферизовать целиком. Для WebSocket дополнительно нужно явно перейти на HTTP/1.1 и передать заголовки апгрейда протокола.

location /ws/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

Увеличенный proxy_read_timeout здесь оправдан, поскольку WebSocket-соединение может оставаться открытым часами без активной передачи данных, и стандартный таймаут в 60 секунд просто разорвёт его как будто бы зависший запрос, хотя с точки зрения приложения всё работает штатно. Для SSE-эндпоинтов дополнительно стоит явно отключить буферизацию директивой proxy_buffering off в конкретном location, чтобы события доставлялись клиенту сразу по мере генерации, а не копились в буфере Nginx до его заполнения.

Практический пример: проксирование Node.js-приложения на localhost:3000

Соберём вместе разобранные выше настройки в один рабочий конфиг для типичного случая: приложение на Node.js слушает порт 3000 на том же сервере, а Nginx принимает внешний трафик, отдаёт статику напрямую и проксирует остальное на приложение.

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

    location /static/ {
        alias /var/www/app.example.ru/static/;
        expires 30d;
        access_log off;
    }

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        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;
        proxy_connect_timeout 5s;
        proxy_read_timeout 60s;
    }
}

Блок location /static/ обрабатывается Nginx самостоятельно, без единого обращения к процессу Node.js, — это разгружает приложение от задачи, для которой оно не оптимизировано, и одновременно позволяет использовать директиву expires для кэширования статики в браузере клиента на длительный срок. Директива access_log off для статики также разумна на нагруженном сайте: записи о каждом запросе картинки или файла стиля быстро раздувают лог-файл, не давая при этом полезной информации для диагностики проблем приложения.

После завершения работы с HTTP-конфигом стоит добавить TLS-терминацию на Nginx через сертификат Let's Encrypt — приложение при этом продолжает работать по обычному HTTP на localhost, полностью не зная о существовании шифрования снаружи, поскольку весь TLS-трафик расшифровывается уже на уровне Nginx перед передачей запроса дальше.

Балансировка нагрузки между несколькими экземплярами приложения

Когда одного процесса приложения перестаёт хватать под нагрузку, reverse proxy на Nginx позволяет практически бесшовно перейти к нескольким экземплярам, запущенным на разных портах или даже разных серверах, — для этого используется блок upstream, объединяющий список бэкендов под одним именем.

upstream app_backend {
    least_conn;
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
    server 127.0.0.1:3002 max_fails=3 fail_timeout=30s;
}

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

    location / {
        proxy_pass http://app_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Директива least_conn выбирает для каждого нового запроса тот бэкенд, у которого сейчас меньше всего активных соединений, — этот метод обычно эффективнее простого round robin (используется по умолчанию, если метод явно не указан) для запросов с сильно различающимся временем обработки, поскольку не позволяет медленным запросам скапливаться на одном и том же экземпляре. Параметры max_fails и fail_timeout задают простую пассивную проверку здоровья бэкенда: после указанного числа неудачных попыток обращения к нему в течение заданного окна Nginx временно исключает этот бэкенд из ротации, не дожидаясь ручного вмешательства.

Для сессий, привязанных к конкретному экземпляру приложения (например, если сессии хранятся в памяти процесса, а не во внешнем хранилище вроде Redis), можно использовать метод ip_hash, который направляет запросы от одного и того же клиентского IP всегда на один и тот же бэкенд, — впрочем, куда более надёжное решение для многосерверной архитектуры — вынести хранение сессий во внешнее хранилище и не зависеть от привязки к конкретному экземпляру вовсе.

Типичные ошибки настройки reverse proxy

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

Отсутствие заголовков X-Real-IP и X-Forwarded-For — приложение видит все запросы как пришедшие с одного адреса, что ломает индивидуальный rate limiting, антифрод-логику и точность аналитики посещаемости на стороне самого приложения.

Слишком короткий proxy_read_timeout для эндпоинтов с объективно долгой обработкой — приводит к 504 Gateway Timeout на легитимных, но небыстрых операциях вроде генерации отчётов или синхронных вызовов внешних API с переменной задержкой ответа.

Прямой доступ к порту приложения из интернета в обход Nginx — если приложение слушает 0.0.0.0 вместо 127.0.0.1 и порт не закрыт firewall'ом, весь смысл reverse proxy как единой контролируемой точки входа теряется, а приложение получает трафик напрямую, минуя все настроенные на Nginx защиты и лимиты.

Отсутствие proxy_http_version 1.1 и заголовков Upgrade/Connection для WebSocket-эндпоинтов — соединение либо не устанавливается вовсе, либо неожиданно рвётся вскоре после старта, что часто принимают за ошибку в самом приложении, хотя причина в конфигурации прокси перед ним.

Игнорирование логов Nginx при диагностике проблем — error.log Nginx обычно явно указывает на конкретную причину: недоступность бэкенда, таймаут, ошибку резолвинга имени в upstream, и первым шагом при любой странности в работе проксируемого приложения стоит проверить именно этот лог, а не сразу переходить к логам самого приложения.

Чек-лист настройки Nginx как reverse proxy

Шаг 1. Убедитесь, что приложение на бэкенде слушает только localhost (127.0.0.1), а не 0.0.0.0, и порт закрыт для прямого доступа из интернета через firewall.

Шаг 2. Настройте базовый proxy_pass и сразу проверьте поведение слэша в связке с вашим location — протестируйте конкретный запрос и убедитесь, что путь на бэкенде получается именно тем, который ожидает приложение.

Шаг 3. Добавьте проброс заголовков Host, X-Real-IP, X-Forwarded-For и X-Forwarded-Proto — без них приложение не увидит реальных данных о клиенте и протоколе запроса.

Шаг 4. Настройте таймауты proxy_connect_timeout, proxy_send_timeout и proxy_read_timeout под реальный профиль ответов конкретных эндпоинтов, не оставляя их равными глобально заниженному или бесконечно завышенному значению.

Шаг 5. Для WebSocket или SSE-эндпоинтов явно настройте proxy_http_version 1.1, заголовки апгрейда протокола и, при необходимости, отключите буферизацию.

Шаг 6. Проверьте конфигурацию командой nginx -t перед каждым перезапуском и следите за error.log Nginx в первые часы после изменения конфигурации, особенно под реальной нагрузкой.

Итог: прокси как контролируемая граница между интернетом и приложением

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

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

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