proxy_pass в nginx: как передать запросы приложению

Приложение на том же сервере

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

Вместо 3000 — порт вашего приложения. nginx передаёт приложению адрес запроса в том виде, в каком его прислал посетитель.

Строка include proxy_params подключает файл из пакета nginx в Ubuntu. В нём четыре строки:

Без этих строк приложение видит вместо имени сайта адрес из proxy_pass — 127.0.0.1:3000, а вместо IP посетителя — 127.0.0.1.

Запускайте приложение на адресе 127.0.0.1: тогда до него не достучаться снаружи в обход nginx, и порт 3000 в фаерволе открывать не нужно. Как поставить nginx перед приложением с самого начала — в инструкции по размещению сайта.

Слэш после порта меняет адрес

Важно, есть ли что-то после адреса и порта в proxy_pass, — даже один слэш:

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

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

Правило такое. Если после порта ничего нет, адрес уходит приложению как пришёл. Если есть путь, nginx заменяет им часть адреса, совпавшую с location.

Пишите слэш в конце одинаково у location и proxy_pass. Блок location /api со строкой proxy_pass http://127.0.0.1:3000/ отдаст приложению адрес //users с двумя слэшами.

В location с регулярным выражением и в именованном location с @ после порта ничего писать нельзя: проверка sudo nginx -t выдаст ошибку "proxy_pass" cannot have URI part.

Если location записан со слэшем в конце, на адрес без слэша — /api — nginx ответит переадресацией 301 на /api/. Как этого избежать — в разделе про слэш.

WebSocket

Если приложение использует WebSocket — чат, уведомления без перезагрузки страницы, — добавьте в его location ещё три строки:

location / {
    proxy_pass http://127.0.0.1:3000;
    include proxy_params;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Заголовки Upgrade и Connection nginx приложению сам не передаёт — их задают явно. Строка proxy_http_version 1.1 нужна в nginx из Ubuntu 24.04 и 26.04: он по умолчанию обращается к приложению по HTTP/1.0, а сменить протокол на WebSocket через заголовок Upgrade можно только в HTTP/1.1.

Пишите эти строки в том же блоке, где include proxy_params. Если в location есть хоть одна своя строка proxy_set_header, строки proxy_set_header из server и http в нём не действуют.

Если по WebSocket 60 секунд не идут данные, nginx закрывает соединение. Чтобы держать его дольше, поднимите таймаут, например proxy_read_timeout 1h;, или настройте в приложении периодическую отправку ping.

Таймауты

Таймауты считаются не на весь ответ, а на паузу между порциями данных. Если приложение молчит дольше proxy_read_timeout, посетитель получит 504 — какие таймауты за это отвечают и как поднять.

Ошибки и как их исправить