Приложение на Python, Go или Node и так слушает свой порт — зачем ставить перед ним ещё и nginx? Затем, что наружу удобнее выставить одного опытного привратника, чем учить каждое приложение HTTPS, раздаче статики и ведению журнала. Этот приём называют обратным проксированием: nginx не отдаёт ответ сам, а передаёт запрос приложению, ждёт его ответа и возвращает клиенту.
За это отвечает одна директива — proxy_pass, и ради неё nginx ставят почти везде: приложение слушает 127.0.0.1, а наружу смотрит nginx. Но у такой схемы есть подвох: приложение больше не видит клиента напрямую и должно узнать от nginx, кто пришёл, на какое имя и по какому протоколу. В уроке — как передать запрос целиком, как раздать его нескольким копиям приложения и что значат коды 502 и 504.
Простейшее проксирование
Начнём с самого короткого варианта: всё, что пришло на /api/, передать приложению на порту 8000.
location /api/ { proxy_pass http://127.0.0.1:8000/; }
Этого уже достаточно, чтобы запросы доходили. Но у этой строки есть подвох, на котором спотыкается почти каждый: слэш в конце адреса. Разберём его сразу, пока он не стал загадкой.
Слэш в конце proxy_pass
От одного символа в конце proxy_pass зависит, какой путь увидит приложение.
Если в адресе есть путь хотя бы из одного слэша, nginx отрезает совпавший префикс /api/ и подставляет вместо него этот путь: запрос /api/items уйдёт как /items. Если пути нет совсем, запрос уходит как пришёл, вместе с /api/.
Как это выглядит в жизни: «прокси настроил, приложение работает, а всё отвечает 404». Приложение ждёт /items, а получает /api/items. Проверяется это в журнале приложения: там виден путь, который до него доехал. Вторая частая беда — заголовки.
Заголовки, которые передаёт прокси
Без настройки приложение видит не клиента, а сам nginx: запрос пришёл с 127.0.0.1, на имя 127.0.0.1:8000. Чтобы приложение знало правду, nginx дописывает к запросу заголовки — строки вида «имя: значение», которые идут вместе с запросом.
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, он подставляет в них значения из текущего запроса. Host — имя сайта, по которому пришёл клиент. X-Real-IP — адрес клиента. X-Forwarded-For — цепочка адресов, если прокси несколько. X-Forwarded-Proto — пришёл клиент по http или https; без него приложение за HTTPS-прокси строит ссылки на http://.
Эти четыре строки копируют в каждый location с proxy_pass, и это нормально: проще один раз их запомнить, чем потом искать, почему в логах приложения все клиенты с адресом 127.0.0.1. Но всё это настроено для единственной копии приложения: упадёт она — и сайт ляжет вместе с ней.
Несколько копий приложения: upstream
Одна копия приложения — одна точка отказа. Обычно их запускают две и больше, а nginx раздаёт им запросы. Группу описывают блоком upstream на уровне файла, рядом с server.
upstream app { server 127.0.0.1:8000; server 127.0.0.1:8001; }
В proxy_pass вместо адреса пишут имя группы: proxy_pass http://app/;. По умолчанию запросы идут по кругу: первый на 8000, второй на 8001, третий снова на 8000. Такой способ называют round robin, «по кругу».
Если одна копия не отвечает, nginx пробует другую и на десять секунд выводит упавшую из ротации. Пользователь ошибки обычно не видит. Если же упали все копии, nginx вернёт 502 Bad Gateway — «за мной никого нет». Есть и другие способы раздачи, например «тому, у кого меньше соединений» (least_conn), но по умолчанию хватает круга. Хуже, когда копия не падает, а зависает: тогда всё решает, сколько nginx готов её ждать.
Таймауты и коды 502 и 504
nginx не ждёт приложение вечно. Два главных таймаута — на подключение и на ответ.
proxy_connect_timeout 5s; # сколько ждать подключения proxy_read_timeout 60s; # сколько ждать ответа
По умолчанию оба таймаута — 60 секунд. Подключение к приложению на той же машине занимает миллисекунды, поэтому его ждать минуту бессмысленно и обычно сокращают до нескольких секунд, как выше. Важнее понимать, какой код увидит клиент. Если приложение не запущено и порт закрыт, подключение сразу отвергается, и клиент получает 502. Если приложение приняло соединение, но не ответило за proxy_read_timeout, клиент получает 504 Gateway Timeout. Тот же 504 придёт, когда подключиться не удалось за proxy_connect_timeout: так бывает, если приложение на другой машине и пакеты к нему молча выбрасывает файрвол. В error.log тогда будет upstream timed out … while connecting to upstream, а не while reading response header.
Эти два кода — главные подсказки при отладке: 502 говорит «приложения нет или оно упало», 504 — «приложение думает слишком долго или до него не доходят пакеты». В обоих случаях причину nginx пишет в error.log, и её разберём в уроке про логи.
Словарь урока
Что спросят на собеседовании
- Всё за прокси отвечает 404, хотя приложение работает. Где искать?В слэше в конце proxy_pass: он решает, отрезается ли префикс location. Фактический путь видно в журнале приложения.
- Почему в логах приложения у всех клиентов адрес 127.0.0.1?Прокси не передаёт адрес клиента. Нужны proxy_set_header X-Real-IP и X-Forwarded-For, а приложение должно их читать.
- Чем 502 отличается от 504?502 — nginx получил отказ при подключении к приложению или некорректный ответ. 504 — не дождался: ответа за proxy_read_timeout или самого подключения за proxy_connect_timeout.
Что дальше
В практике поставишь nginx перед двумя копиями приложения, увидишь глазами, какие заголовки доходят, и уронишь копии по очереди, чтобы получить 502.