Provision
—— XP

Обратный прокси: передать запрос приложению

теория~7 минут+140 XP

Приложение на Python, Go или Node и так слушает свой порт — зачем ставить перед ним ещё и nginx? Затем, что наружу удобнее выставить одного опытного привратника, чем учить каждое приложение HTTPS, раздаче статики и ведению журнала. Этот приём называют обратным проксированием: nginx не отдаёт ответ сам, а передаёт запрос приложению, ждёт его ответа и возвращает клиенту.

За это отвечает одна директива — proxy_pass, и ради неё nginx ставят почти везде: приложение слушает 127.0.0.1, а наружу смотрит nginx. Но у такой схемы есть подвох: приложение больше не видит клиента напрямую и должно узнать от nginx, кто пришёл, на какое имя и по какому протоколу. В уроке — как передать запрос целиком, как раздать его нескольким копиям приложения и что значат коды 502 и 504.

Простейшее проксирование

Начнём с самого короткого варианта: всё, что пришло на /api/, передать приложению на порту 8000.

фрагмент блока server
location /api/ {
    proxy_pass http://127.0.0.1:8000/;
}

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

Слэш в конце proxy_pass

От одного символа в конце proxy_pass зависит, какой путь увидит приложение.

Три блока с одинаковым location /api/ и одинаковым запросом /api/items, но разной строкой proxy_pass: без слэша приложение получает /api/items, со слэшем — /items, со своим путём — /v2/items.
Слэш в конце адреса заменяет префикс location, без слэша путь уходит как есть.

Если в адресе есть путь хотя бы из одного слэша, nginx отрезает совпавший префикс /api/ и подставляет вместо него этот путь: запрос /api/items уйдёт как /items. Если пути нет совсем, запрос уходит как пришёл, вместе с /api/.

Как это выглядит в жизни: «прокси настроил, приложение работает, а всё отвечает 404». Приложение ждёт /items, а получает /api/items. Проверяется это в журнале приложения: там виден путь, который до него доехал. Вторая частая беда — заголовки.

Заголовки, которые передаёт прокси

Без настройки приложение видит не клиента, а сам nginx: запрос пришёл с 127.0.0.1, на имя 127.0.0.1:8000. Чтобы приложение знало правду, nginx дописывает к запросу заголовки — строки вида «имя: значение», которые идут вместе с запросом.

внутри location /api/
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 не ждёт приложение вечно. Два главных таймаута — на подключение и на ответ.

внутри location /api/
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, и её разберём в уроке про логи.

Словарь урока

proxy_pass
Директива, которая передаёт запрос приложению по указанному адресу или группе.
заголовок
Строка «имя: значение», которая идёт вместе с HTTP-запросом или ответом. Например, Host: stand.provision.internal.
upstream
Именованная группа серверов приложения, между которыми nginx раздаёт запросы.
round robin
Раздача запросов по кругу: каждый следующий — следующему серверу группы. ↩ к тексту
502 и 504
502 — до приложения не достучались или оно ответило мусором; 504 — не дождались ответа или подключения. ↩ к тексту
Nginx как обратный прокси
подборка на ютубе · ролик не закреплён
Как proxy_pass и upstream выглядят в живом конфиге.

Что спросят на собеседовании

  • Всё за прокси отвечает 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.

Проверь себя+140 XPдве попытки
1
proxy_pass
В «location /api/» стоит «proxy_pass http://127.0.0.1:8000/;». Какой путь получит приложение на запрос /api/items?
2
Заголовки
Зачем передают «proxy_set_header Host $host»?
3
Несколько копий приложения
В upstream два сервера, один упал. Что делает nginx?
4
Таймауты
Приложение приняло соединение, но не отвечает дольше proxy_read_timeout. Какой код получит клиент?
ответь на все вопросы, чтобы проверить

Нашёл ошибку или непонятное место? Наведи на абзац — слева появится «+», нажми и напиши, что не так. Замечание увидит автор курса.Нашёл ошибку или непонятное место? Нажми «+» справа от заголовка раздела и напиши, что не так. Замечание увидит автор курса.