Настройка 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.
Конфиг
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: если он уже есть в другом файле, второй раз его не добавляйте
Как применить и проверить
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 Конфиг nginx для Laravel: готовый файл и порядок применения Готовый конфиг nginx для Laravel: что делает каждый блок, что заменить под свой сервер, как включить сайт, проверить синтаксис и перезагрузить nginx.
- Конфиг · Nginx Конфиг nginx для WordPress: готовый файл и порядок применения Готовый конфиг nginx для WordPress: что заменить под свой сервер, как подключить сайт, проверить синтаксис и перезагрузить nginx без простоя.
- Ошибка · Nginx Ошибка 502 Bad Gateway в nginx: причины и исправление Разбираем ошибку 502 Bad Gateway в nginx: почему PHP-FPM не отвечает, как читать error.log, проверять сокет и права, чинить таймауты и буферы.
- Руководство · Nginx Docker nginx: установка и настройка обратного прокси Пошагово: установка nginx в Docker на Ubuntu 24.04, конфиг обратного прокси, проверка через curl и разбор частых ошибок с логами.
- Ошибка · Nginx Ошибка 403 Forbidden в nginx: причины и исправление Разбираем ошибку 403 Forbidden в nginx: как найти причину по error.log, проверить права через namei и sudo -u www-data, исправить chmod и deny. Команды для Ubuntu…
- Руководство · Nginx Установка nginx на Ubuntu 24.04 и настройка сайта с PHP Пошаговая установка nginx на Ubuntu 24.04: apt, настройка PHP 8.3 через php-fpm, конфиг сайта, логи и проверка через nginx -t и systemctl status.
Настройка nginx на сервере: от установки до рабочего конфига: все материалы темы