Proxy_pass в Nginx: Полное руководство по перенаправлению запросов на другой сервер

Что такое proxy_pass и зачем он нужен

Директива proxy_pass в Nginx — ключевой инструмент для перенаправления HTTP-запросов с одного сервера на другой. Она действует как обратный прокси, принимая запросы клиентов и транслируя их на backend-серверы, возвращая результат обратно. Это незаменимо для:

• Балансировки нагрузки между несколькими серверами
• Организации микросервисной архитектуры
• Защиты backend-серверов от прямого доступа
• Обслуживания SSL/TLS терминации
• Интеграции приложений на разных технологических стеках

Как работает proxy_pass в Nginx

Когда Nginx получает запрос, соответствующий location-блоку с proxy_pass, он:

1. Анализирует URL назначения
2. Устанавливает TCP-соединение с целевым сервером
3. Передаёт исходные заголовки (с возможной модификацией)
4. Буферизует ответ от backend
5. Доставляет контент клиенту с корректными HTTP-статусами

Базовый пример конфигурации:

location /app/ {
    proxy_pass http://backend-server:8080;
    proxy_set_header Host $host;
}

Практические примеры настройки

Перенаправление на локальный сервис

location /api/ {
    proxy_pass http://localhost:3000;
}

Балансировка нагрузки

upstream backend {
    server 10.0.0.1:80;
    server 10.0.0.2:80;
}

location / {
    proxy_pass http://backend;
}

Обработка WebSocket

location /ws/ {
    proxy_pass http://websocket-server;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Критические параметры оптимизации

• proxy_buffer_size: Контролирует размер буфера для заголовков ответа
• proxy_connect_timeout: Таймаут соединения с backend (рекомендуется 5-10s)
• proxy_read_timeout: Максимальное время ожидания ответа
• proxy_redirect: Автоматически корректирует Location-заголовки
• proxy_set_header: Переопределение заголовков (обязательно для Host и X-Real-IP)

Типичные ошибки конфигурации

1. Отсутствие слэша в конце URL при location с префиксом
2. Некорректная обработка статических файлов
3. Забытые proxy_set_header для передачи IP-клиента
4. Игнорирование SSL-сертификатов при работе с HTTPS-backend
5. Неадекватные таймауты для «тяжёлых» запросов

FAQ: Ответы на частые вопросы

Чем proxy_pass отличается от redirect?

Redirect (301/302) сообщает клиенту о новом адресе, заставляя его выполнить новый запрос. Proxy_pass полностью прозрачен для клиента — все операции выполняются на стороне сервера.

Как передать исходный IP-адрес клиента?

Используйте в конфигурации:

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Почему Nginx возвращает 502 Bad Gateway?

Распространённые причины: backend-сервер недоступен, неверный порт, фаервол блокирует соединение или превышен proxy_connect_timeout.

Как обрабатывать HTTPS-бэкенды?

Добавьте параметры SSL:

proxy_ssl_verify off; # Для тестов
proxy_ssl_server_name on;
proxy_ssl_name backend-domain.com;

Можно ли использовать переменные в proxy_pass?

Да, например для динамической маршрутизации:

location ~ /service/(?w+) {
    proxy_pass http://$service-backend;
}

Заключение

Proxy_pass — мощный механизм Nginx для построения гибких и отказоустойчивых инфраструктур. Правильная настройка параметров таймаутов, буферизации и заголовков гарантирует стабильную работу прокси. Для сложных сценариев комбинируйте proxy_pass с map-блоками и переменными, а тестируйте конфигурации через nginx -t перед применением. Помните: каждый параметр должен соответствовать специфике вашего приложения и нагрузкам.