upstream блок
Тема дорожной карты · Nginx
Блок upstream — ключевая конструкция конфигурации Nginx, определяющая именованную группу бэкенд-серверов, между которыми Nginx распределяет трафик как обратный прокси или балансировщик нагрузки, обеспечивая высокую доступность и горизонтальную масштабируемость веб-приложений. Блок upstream объявляется в контексте http с уникальным именем и содержит одну или несколько директив server, задающих адреса бэкендов, опциональные порты и параметры вроде weight, max_fails, fail_timeout, backup и down. Именованная группа upstream затем указывается в директиве proxy_pass — например, proxy_pass http://my_backend — и Nginx применяет настроенный алгоритм балансировки нагрузки (round-robin по умолчанию, или least_conn, ip_hash либо random) для выбора бэкенда при каждом запросе. Пассивные проверки работоспособности встроены в блок upstream через параметры max_fails и fail_timeout: если сервер отказывает max_fails раз в течение fail_timeout секунд, Nginx помечает его как недоступный и прекращает отправку трафика до истечения таймаута. В продакшен-развёртываниях блок upstream является единственным наиболее важным строительным блоком для достижения надёжной и масштабируемой балансировки нагрузки Nginx между уровнями приложений.
Как это работает
upstream блок — самая частая production-роль nginx: принять HTTP от клиентов, пробросить на upstream-backend. proxy_pass http://backend; (с опциональным upstream-блоком для нескольких backend). Прокидывайте client-инфу через proxy_set_header X-Real-IP $remote_addr;, X-Forwarded-For $proxy_add_x_forwarded_for, X-Forwarded-Proto $scheme, Host $host. Таймауты (proxy_connect_timeout, proxy_send_timeout, proxy_read_timeout) предотвращают зависание. WebSocket-поддержка через proxy_http_version 1.1 + Connection: upgrade.
Когда применять
Всегда прокидывайте X-Forwarded-For + X-Real-IP — backend-логи/аудит зависят от реального client-IP. Всегда разумные таймауты; дефолты слишком мягкие (60s) для многих приложений — подгоняйте под SLO. proxy_buffering off — для streaming-ответов (SSE, long polling). keepalive 32; в upstream-блоке — для переиспользования соединений с backend.
Типичные ошибки
Ловушки upstream блок: не прокидывают X-Forwarded-Proto и backend решает HTTPS на основе своего req.protocol (всегда HTTP за nginx); proxy_pass http://backend без trailing slash иногда дополняет location URI (тонкие URL-rewrite — читайте доку); upstream без keepalive (TCP-handshake на каждый запрос); 502 / 504 не обработаны грациозно (дефолтная страница уродлива).