Настройка маршрутизации в Nginx: location, proxy_pass и rewrite для микросервисов | AdminWiki
Logo
Timeweb Cloud — сервера, Kubernetes, S3, Terraform. Лучшие цены IaaS.
Попробовать

Настройка маршрутизации в Nginx: location, proxy_pass и rewrite для микросервисов

19 мая 2026 11 мин. чтения
Содержание статьи

Маршрутизация запросов - фундамент работы Nginx как реверс-прокси или API Gateway. Правильная настройка директив location, proxy_pass и rewrite определяет, как запросы попадают к нужным сервисам, как преобразуются URL и как обрабатываются ошибки. В микросервисных архитектурах это особенно критично: один сервер Nginx часто выступает единой точкой входа для десятков внутренних сервисов.

Некорректная конфигурация приводит к часам отладки, неработающим API и проблемам с SEO. Эта статья - пошаговое руководство, основанное на практическом опыте. Вы разберете алгоритм выбора location, научитесь передавать запросы на разные бэкенды без потери данных, реализуете чистые URL и организуете раздельную обработку статики и API. Каждый раздел содержит готовые примеры конфигураций, которые можно адаптировать под ваши задачи.

Понимание приоритетов и совместимости директивы location

Директива location определяет, как Nginx обрабатывает запросы к разным URI. Основная проблема, с которой сталкиваются администраторы, - непредсказуемое поведение, когда запрос попадает не в тот блок, который ожидался. Причина - строгий, но не всегда очевидный алгоритм поиска, который Nginx использует для сопоставления URI.

Алгоритм поиска location: от точного совпадения к регулярным выражениям

Nginx выбирает блок location для обработки запроса по четкому алгоритму. Понимание этого порядка исключает догадки при анализе конфигурации.

  1. Точное совпадение ( = ). Nginx сначала ищет location с модификатором =, который соответствует URI запроса полностью. Например, location = /api/users { ... } сработает только для запроса /api/users, но не для /api/users/ или /api/users/1. Это совпадение имеет наивысший приоритет.
  2. Префиксные совпадения без регулярных выражений. Далее сервер проверяет все location, заданные строкой без модификаторов регулярных выражений (~ или ~*). Среди них выбирается самый длинный совпадающий префикс. Например, для запроса /static/img/logo.png блок location /static/img/ { ... } будет иметь приоритет над блоком location /static/ { ... }.
  3. Регулярные выражения ( ~ и ~* ). Если ни одно из предыдущих совпадений не подошло, Nginx проверяет location с регулярными выражениями в порядке их следования в конфигурационном файле. Первое совпавшее выражение используется. Модификатор ~ означает регистрозависимое сравнение, ~* - регистронезависимое.
  4. Самый длинный префиксный location (если регулярные выражения не сработали). Если ни одно регулярное выражение не совпало, используется самый длинный префиксный location из пункта 2.

Пример. Рассмотрим конфигурацию и запрос /api/users:

location = /api {
    return 403;
}
location /api/ {
    proxy_pass http://backend;
}
location ~ ^/api { 
    proxy_pass http://legacy_backend;
}

Алгоритм отработает так: точного совпадения = /api/users нет. Самый длинный префикс - /api/ (совпадает). Nginx выберет второй блок и проксирует запрос на http://backend. Регулярные выражения проверяться не будут, так как префиксное совпадение уже найдено.

Конфликты правил и практические примеры их разрешения

Конфликты возникают, когда несколько location могут обработать один запрос. Стратегия разрешения строится на понимании приоритетов и грамотном структурировании конфига.

Типичный конфликт: обработка статических файлов в поддиректориях.

location /static/ {
    root /var/www;
    try_files $uri =404;
}
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    root /var/www/static;
    expires 1y;
}

Запрос /static/image.jpg совпадет с обоими location. Согласно алгоритму, сначала будет проверяться префиксный location /static/ (самый длинный). Но так как есть location с регулярным выражением, который также совпадает, и он проверяется после префиксных, фактически будет выбран блок с регулярным выражением, так как он первый подходящий в своей категории. Это может быть неочевидно.

Решение - использовать точное совпадение для критических путей или явно задавать порядок, исключая конфликты. Лучшая практика для статики:

location /static/ {
    root /var/www;
    try_files $uri =404;
    # Кэширование настраиваем здесь, а не в отдельном location
    expires 30d;
    add_header Cache-Control "public";
}
# Убираем общее регулярное выражение для статики, чтобы избежать конфликта.
# Либо размещаем его ДО префиксного location, если он должен иметь приоритет.

Еще один пример - разделение API и административной панели:

location = /admin {
    return 301 /admin/;
}
location /admin/ {
    proxy_pass http://admin_panel_backend/; # Обратите внимание на слэш в конце
}
location /api/ {
    proxy_pass http://api_backend;
}

Здесь точное совпадение = /admin выполняет редирект, а запросы, начинающиеся с /admin/, четко направляются на свой бэкенд, не конфликтуя с /api/.

Для глубокого понимания структуры конфигурационного файла рекомендую изучить полное руководство по структуре nginx.conf, где разобраны все ключевые секции.

Корректная конфигурация proxy_pass для различных бэкендов и микросервисов

Директива proxy_pass передает запрос другому серверу. Ее настройка кажется простой, но нюансы передачи URI и заголовков часто становятся источником ошибок, особенно в микросервисных средах, где каждый сервис ожидает определенный формат запроса.

Передача URI и заголовков: избегаем типичных ошибок

Самая частая ошибка - непреднамеренное изменение URI при проксировании. Поведение proxy_pass зависит от наличия URI в директивной строке.

  • Если в proxy_pass указан URI (например, proxy_pass http://backend/app/;), то часть location, совпавшая с запросом, заменяется на URI из директивы.
  • Если URI не указан (например, proxy_pass http://backend;), то запрос передается бэкенду в неизменном виде, включая полный оригинальный URI.

Пример. Допустим, есть location location /api/ { ... }.

# Вариант 1: URI не указан. Запрос /api/users/1 будет передан на backend как /api/users/1
proxy_pass http://backend;

# Вариант 2: URI указан. Запрос /api/users/1 будет передан на backend как /app/users/1
proxy_pass http://backend/app/;

# Вариант 3: Использование переменной $request_uri передает полный оригинальный URI с query-параметрами.
proxy_pass http://backend$request_uri;

Для корректной работы большинства бэкендов необходимо передавать определенные заголовки. Без них приложение может не определить исходный IP-адрес клиента или целевой домен.

location /api/ {
    proxy_pass http://backend;
    # Стандартный набор заголовков для реверс-прокси
    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;
    # Важно для WebSocket и некоторых API
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Обработка ошибок бэкенда настраивается директивами proxy_next_upstream, proxy_connect_timeout, proxy_read_timeout. Например, proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504; заставит Nginx попробовать следующий сервер в upstream, если текущий вернул ошибку или таймаут.

Маршрутизация как API Gateway для микросервисной архитектуры

Один экземпляр Nginx может эффективно работать как простой API Gateway, распределяя трафик между десятками микросервисов на основе пути запроса. Это реализуется через несколько location с разными proxy_pass.

Рассмотрим пример архитектуры с тремя сервисами: пользовательским (user_service:8080), товарным (product_service:8081) и сервисом заказов (order_service:8082).

upstream user_service {
    server 192.168.1.10:8080;
    server 192.168.1.11:8080 backup;
}

upstream product_service {
    server 192.168.1.20:8081;
}

upstream order_service {
    server 192.168.1.30:8082;
}

server {
    listen 80;
    server_name api.example.com;

    # Маршрутизация на микросервисы
    location /api/users {
        proxy_pass http://user_service;
        proxy_set_header Host $host;
        # Дополнительные настройки таймаутов и заголовков
    }

    location /api/products {
        proxy_pass http://product_service;
        proxy_set_header Host $host;
    }

    location /api/orders {
        proxy_pass http://order_service;
        proxy_set_header Host $host;
    }

    # Ловушка для несуществующих маршрутов API
    location /api/ {
        return 404 '{"error": "API endpoint not found"}';
        add_header Content-Type application/json;
    }
}

Такая конфигурация создает четкое разделение: запрос к /api/users/profile уйдет на user_service, а запрос к /api/products/list - на product_service. Использование upstream-блоков позволяет добавить элементарную балансировку нагрузки и резервирование внутри каждого сервиса.

Для типовых задач, таких как настройка SSL/TLS или кэширования, вы можете использовать готовые решения из нашей подборки рабочих конфигураций Nginx для 2026 года.

Применение rewrite для сложных правил маршрутизации, SEO и переадресации

Директива rewrite изменяет URI запроса внутри Nginx до дальнейшей обработки (в location или proxy_pass). Она незаменима для реализации «чистых» URL, перенаправлений при изменении структуры сайта и адаптации запросов под специфичные требования бэкенда.

Clean URLs и редиректы для SEO

«Чистые» URL (например, /article/kak-nastroit-nginx) улучшают читаемость и SEO. Часто бэкенд ожидает параметры в query-строке (/api/article?id=123). rewrite решает эту проблему.

# Преобразование чистого URL в параметры для API
location /article/ {
    # Правило преобразует /article/kak-nastroit-nginx в /api/article?slug=kak-nastroit-nginx
    rewrite ^/article/(.*)$ /api/article?slug=$1 last;
    # После rewrite обработка продолжается, и запрос с новым URI будет искать новый location
}

location /api/ {
    proxy_pass http://backend;
}

Флаг last указывает, что после выполнения rewrite нужно начать поиск location заново с измененным URI. Другие флаги: break (прекратить обработку rewrite в текущем блоке и продолжить выполнение текущего location), redirect (вернуть клиенту временный редирект 302), permanent (вернуть постоянный редирект 301).

Редиректы 301 критически важны для SEO при изменении структуры URL. Они сообщают поисковым системам, что страница перемещена навсегда, и передают «вес» старого адреса новому.

# Старый адрес блога. Перенаправляем на новую структуру.
location /old-blog/ {
    rewrite ^/old-blog/(.*)$ /blog/$1 permanent;
}

# Редирект со старой версии API на новую
location /v1/api/ {
    rewrite ^/v1/api/(.*)$ /v2/api/$1 permanent;
}

Модификация запросов перед proxy_pass

Иногда бэкенд требует, чтобы все входящие запросы содержали определенный параметр или заголовок. rewrite позволяет модифицировать запрос прозрачно для клиента.

location /external-api/ {
    # Добавляем query-параметр source=nginx ко всем запросам к этому бэкенду
    rewrite ^/external-api/(.*)$ /$1?source=nginx break;
    proxy_pass http://external_backend;
    proxy_set_header Host api.external-service.com;
}

В этом примере запрос клиента /external-api/data будет преобразован в /data?source=nginx и затем передан на http://external_backend. Флаг break останавливает дальнейшую обработку rewrite в этом location, и сразу выполняется proxy_pass.

Важно помнить, что rewrite выполняется до поиска location (если он находится на уровне server) или внутри location. Циклические редиректы - частая ошибка. Избегайте правил, которые могут повторно применять rewrite к уже измененному URI.

Раздельная обработка статического контента и API запросов

Оптимальная стратегия - обслуживать статические файлы (изображения, CSS, JavaScript, шрифты) напрямую Nginx, а динамические запросы к API проксировать на бэкенд. Это снижает нагрузку на сервисы приложений, ускоряет отдачу статики и упрощает кэширование.

Оптимальная конфигурация для статики и динамических данных

Базовая, но эффективная конфигурация разделяет маршруты на статические и динамические.

server {
    listen 80;
    server_name example.com;
    root /var/www/example.com/public;

    # Обработка статических файлов
    location /static/ {
        # Файлы ищутся относительно корня, заданного в server
        # Для запроса /static/css/style.css Nginx попробует найти /var/www/example.com/public/static/css/style.css
        try_files $uri $uri/ =404;
        # Агрессивное кэширование в браузере
        expires 1y;
        add_header Cache-Control "public, immutable";
        # Отключаем логирование для статики, чтобы не засорять логи
        access_log off;
    }

    location /media/ {
        try_files $uri $uri/ =404;
        expires 30d;
        add_header Cache-Control "public";
    }

    # Обработка API запросов
    location /api/ {
        proxy_pass http://backend_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;
    }

    # Все остальные запросы (например, для SPA) направляются на бэкенд приложения
    location / {
        proxy_pass http://frontend_app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Директива try_files проверяет существование файлов по заданному порядку. try_files $uri $uri/ =404 означает: «попробуй найти точный файл по URI, если нет - попробуй найти директорию, если и ее нет - верни ошибку 404». Для SPA (Single Page Application) часто используют try_files $uri /index.html;, чтобы все запросы, не ведущие к реальному файлу, возвращали основную HTML-страницу приложения.

Преимущества такого подхода:
1. Производительность. Nginx эффективно отдает статические файлы с минимальной нагрузкой на CPU.
2. Кэширование. Настройки expires и Cache-Control для статики уменьшают количество запросов к серверу.
3. Надежность. Даже при падении бэкенд-сервисов статические ресурсы (стили, картинки) остаются доступными, что сохраняет базовую функциональность фронтенда.

Для работы с большими файлами, например, при загрузке видео или дампов баз данных, требуются специальные настройки. Детали можно найти в статье про оптимизацию загрузки больших файлов в Nginx.

Избежание типичных ошибок и проверка работоспособности конфигурации

После написания конфигурации критически важно проверить ее на ошибки и протестировать поведение. Многие проблемы можно выявить до перезагрузки сервиса.

Диагностика и отладка неработающих правил

Следуйте этой методике для систематического поиска проблем.

  1. Проверка синтаксиса. Первая и обязательная команда:
    nginx -t
    Она проверяет корректность синтаксиса во всех конфигурационных файлах. Если есть ошибка, Nginx укажет файл и строку. Всегда выполняйте эту проверку перед перезагрузкой.
  2. Анализ логов ошибок. Основной лог ошибок указывается директивой error_log. При проблемах смаршрутизацией увеличьте уровень логирования до info или debug в секции http: error_log /var/log/nginx/error.log debug;. Это поможет увидеть, какие location выбираются для запросов.
  3. Анализ логов доступа (access_log). Лог доступа показывает фактические запросы, которые пришли к серверу, и конечный status code. Добавьте в формат лога переменную $upstream_addr, чтобы видеть, на какой бэкенд был отправлен запрос.
    log_format debug '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$upstream_addr"';
  4. Тестирование запросов. Используйте curl для отправки тестовых запросов и анализа ответов, заголовков и конечных точек.
    curl -v http://your-server.com/api/test
    curl -v -H "Host: api.example.com" http://server-ip/path

Распространенные ошибки и их решения:

  • «404 Not Found» после proxy_pass. Вероятная причина - потеря части URI. Проверьте, указан ли URI в proxy_pass. Сравните proxy_pass http://backend; и proxy_pass http://backend/; (со слэшем).
  • Запрос попадает не в тот location. Воспользуйтесь алгоритмом поиска location из первого раздела. Проверьте приоритеты, особенно конфликты префиксных location и регулярных выражений. Добавьте уникальный заголовок в каждый location для отладки: add_header X-Location-Debug "user_api" always;.
  • Циклические редиректы (redirect loop). Проверьте правила rewrite, особенно с флагами permanent или redirect. Убедитесь, что редирект не перенаправляет запрос на тот же URL или на другой location, который снова делает редирект.
  • Бэкенд получает неверный заголовок Host. Всегда явно устанавливайте proxy_set_header Host $host; или то значение, которое ожидает бэкенд.

После внесения исправлений и успешной проверки синтаксиса аккуратно примените конфигурацию:
nginx -s reload
Эта команда перезагружает конфигурацию без разрыва established-соединений.

Помните, что выбор между Nginx и Apache, а также миграция с одного сервера на другой - это стратегические решения. Если вы рассматриваете такие варианты, ознакомьтесь с практическим сравнением Nginx и Apache для проектов 2026 года и пошаговым руководством по миграции с Apache на Nginx.

Для автоматизации сложных ИТ-задач, включая анализ логов или генерацию конфигураций, может быть полезен доступ к современным языковым моделям. Сервис AiTunnel предоставляет единый API к более чем 200 моделям, включая GPT, Gemini и Claude, что позволяет интегрировать ИИ-помощника в рабочий процесс без необходимости настройки VPN и с оплатой в рублях.

Поделиться:
Сохранить гайд? В закладки браузера