К содержимому

Настройка nginx как reverse proxy: конфиг и проверка

Конфиг ниже проксирует домен app.example.com на приложение, слушающее 127.0.0.1:3000, и передаёт заголовки Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto и Upgrade. Скопируйте его в /etc/nginx/sites-available/app.example.com, замените домен и адрес приложения, затем включите сайт и перезагрузите nginx. Проверка синтаксиса через sudo nginx -t обязательна до reload.

Конфиг Nginx 3 мин чтения

Конфиг

/etc/nginx/sites-available/app.example.com
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    listen [::]:80;
    server_name app.example.com;

    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_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 60s;
    }
}

Что заменить под свой сервер

app.example.com
домен приложения
127.0.0.1:3000
адрес и порт, на котором слушает приложение
map
блок map объявляется один раз на весь nginx: если он уже есть в другом файле, второй раз его не добавляйте

Как применить и проверить

bash
sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Блок map: поддержка WebSocket и keep-alive

Блок map задаёт переменную $connection_upgrade: при наличии заголовка Upgrade она получает значение upgrade, иначе close. Это нужно, чтобы WebSocket и обычные HTTP-запросы работали через один location. Блок map объявляется на уровне http, поэтому в файле сайта он стоит до server. Если такой map уже есть в другом файле, второй раз его не добавляйте: nginx выдаст ошибку duplicate map.

server и listen: домен и порт

Директива server_name задаёт домен, на который приходят запросы. Замените app.example.com на своё имя, например example.com. Директивы listen 80 и listen [::]:80 принимают HTTP на IPv4 и IPv6. Для HTTPS понадобится отдельный server с listen 443 ssl и сертификатом, этот конфиг его не содержит.

location и proxy_pass: адрес приложения

location / отправляет все запросы в proxy_pass http://127.0.0.1:3000. Замените 127.0.0.1:3000 на адрес и порт, где слушает ваше приложение: например, 127.0.0.1:8080 для Node.js или unix:/run/app.sock для сокета. Если приложение слушает только localhost, снаружи порт закрыт, и трафик идёт через nginx. Приложение должно быть запущено до проверки: иначе nginx отдаст 502 Bad Gateway.

Заголовки proxy_set_header: что видит приложение

proxy_set_header Host $host передаёт исходный домен, чтобы приложение строило правильные ссылки. X-Real-IP и X-Forwarded-For сообщают IP клиента, X-Forwarded-Proto говорит, был ли запрос по HTTP или HTTPS. Upgrade и Connection вместе с map включают WebSocket. Без этих заголовков приложение видит IP nginx и схему http, а WebSocket-соединение обрывается.

proxy_http_version и proxy_read_timeout

proxy_http_version 1.1 нужен для WebSocket и keep-alive до бэкенда: по умолчанию nginx использует HTTP/1.0. proxy_read_timeout 60s задаёт время ожидания ответа от приложения: если бэкенд молчит дольше, nginx закрывает соединение и отдаёт 504 Gateway Time-out. Для долгих запросов увеличьте значение, например до 300s.

Как применить конфиг и проверить

Создайте файл /etc/nginx/sites-available/app.example.com с конфигом, затем включите сайт символической ссылкой в sites-enabled. Перед перезагрузкой проверьте синтаксис: sudo nginx -t покажет путь к файлу и строку с ошибкой. Если проверка прошла, выполните sudo systemctl reload nginx, чтобы применить изменения без разрыва соединений. Проверьте ответ через curl -I http://app.example.com и посмотрите логи /var/log/nginx/error.log при 502 или 504.

Где ошибаются, когда правят конфиг

  • Блок map добавлен в файл сайта повторно, хотя он уже объявлен в /etc/nginx/nginx.conf или другом файле. nginx -t завершается с ошибкой duplicate map.

    Оставьте один блок map на весь nginx. Если он уже есть, удалите его из файла сайта и используйте существующую переменную $connection_upgrade.

  • В proxy_pass указан адрес, на котором приложение не слушает, или приложение остановлено. Браузер получает 502 Bad Gateway.

    Проверьте порт через ss -ltnp и убедитесь, что процесс запущен. Исправьте адрес в proxy_pass и выполните sudo nginx -t, затем sudo systemctl reload nginx.

  • Пропущены proxy_set_header Host и X-Forwarded-Proto. Приложение строит ссылки на localhost и считает запрос HTTP, из-за чего редиректы и куки ломаются.

    Добавьте proxy_set_header Host $host и proxy_set_header X-Forwarded-Proto $scheme в location, затем перезагрузите nginx.

  • Сайт не включён: файл лежит в sites-available, но символической ссылки в sites-enabled нет. nginx отдаёт дефолтную страницу или 404.

    Создайте ссылку sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/ и перезагрузите nginx после sudo nginx -t.

Deploykin

Как это делается в Deploykin

В Deploykin сайт создаётся из панели, и конфиг nginx под Laravel, WordPress или PHP панель пишет сама. Править конфиги можно в редакторе панели: перед сохранением конфиг проверяется на сервере, а прежняя версия уходит в резервную копию.

7 дней бесплатно на тарифе Про, без привязки карты.

Вопросы и ответы

Зачем нужен блок map с $connection_upgrade?

Он выставляет заголовок Connection в upgrade при WebSocket-запросе и в close для обычного HTTP. Без него WebSocket через nginx не установится или будет закрываться.

Почему nginx отдаёт 502 Bad Gateway?

Приложение не запущено или слушает другой адрес, чем указан в proxy_pass. Проверьте порт через ss -ltnp и исправьте proxy_pass.

Нужно ли менять proxy_read_timeout?

Значение 60s подходит для большинства запросов. Если бэкенд обрабатывает запрос дольше минуты, увеличьте таймаут, иначе nginx вернёт 504 Gateway Time-out.

Как проверить конфиг перед перезагрузкой?

Выполните sudo nginx -t. При ошибке команда покажет файл и строку, после исправления повторите проверку и сделайте sudo systemctl reload nginx.

Ещё по теме

Настройка nginx на сервере: от установки до рабочего конфига: все материалы темы

Мы используем cookies и сервис веб-аналитики «Яндекс Метрика» (включая Вебвизор) для улучшения работы сайта. Подробности — в политике конфиденциальности.