Как передать реальный IP клиента через Nginx

Задача и общий подход

Материал посвящён теме «Как передать реальный IP клиента через Nginx» с акцентом на логике работы и взаимосвязи компонентов.

Reverse proxy отделяет публичный вход от внутреннего приложения. Backend может слушать только localhost, а Nginx отвечает за TLS, заголовки, ограничения доступа и обработку ошибок.

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

Как устроена схема

Клиент соединяется с Nginx, а Nginx создаёт отдельное соединение с upstream. Это два участка с собственными тайм-аутами. Заголовки Host, X-Real-IP и X-Forwarded-Proto нужны приложению для правильных ссылок и журналов.

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

Когда применять этот порядок

Этот сценарий подходит для следующих ситуаций:

• плановое внедрение или перенос компонента категории «Reverse proxy» на новый VPS
• изменение портов, домена, сертификата, маршрута или способа публикации сервиса
• разбор инцидента, когда локальная и внешняя проверки дают разные результаты
• подготовка к обновлению пакета или восстановлению после неудачного изменения

Подготовка перед изменениями

Подготовительный этап снижает риск потерять доступ и смешать несколько причин одной неисправности.

• Откройте вторую административную сессию и не закрывайте текущую.
• Проверьте свободное место, DNS и системное время.
• Зафиксируйте текущие порты, процессы и состояние службы.
• Сохраните копии изменяемых файлов с датой и временем.
• Подготовьте команду отката до применения изменений.

Резервная точка

Сохраните именно те файлы и параметры, которые собираетесь менять.

TS=$(date +%F-%H%M%S)
mkdir -p /root/iiadmin-change-$TS
cp -a /path/to/config /root/iiadmin-change-$TS/
systemctl status SERVICE --no-pager > /root/iiadmin-change-$TS/status-before.txt
ss -lntup > /root/iiadmin-change-$TS/listeners-before.txt

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

Пошаговая настройка

Выполняйте блоки последовательно и после каждого шага проверяйте код возврата команды.

sudo nginx -t && sudo systemctl reload nginx
curl -vk https://example.org/app/

ss -lntp | grep ':8080'
curl -v http://127.0.0.1:8080/

location /app/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    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;
}

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

Имена доменов, адреса, порты и пути в примерах условные. Перед выполнением замените их фактическими значениями.

Проверка результата

Проверка должна охватывать конфигурацию, процесс, listener и реальный запрос.

• backend отвечает локально
• Nginx видит upstream
• URI после proxy_pass корректен
• клиентский IP передаётся
• длинные ответы не обрываются

systemctl is-active SERVICE
systemctl status SERVICE --no-pager
journalctl -u SERVICE -n 80 --no-pager
ss -lntup

Типичные ошибки

Чаще всего восстановление усложняют следующие действия:

• проверка только локального подключения без внешнего теста
• открытие административного порта для всего интернета
• игнорирование различий правил IPv4 и IPv6
• удаление рабочей конфигурации до успешного запуска новой
• использование устаревшей команды без проверки версии пакета
• перезапуск службы до проверки синтаксиса

Диагностика, если не заработало

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

1. Подтвердите симптом точной командой и запишите время.
2. Проверьте конфигурацию штатным тестом.
3. Проверьте процесс и последние записи журнала.
4. Убедитесь, что нужный адрес и порт слушаются.
5. Сравните локальный запрос с запросом извне.
6. Только затем проверяйте firewall, DNS и маршрут.
7. Меняйте одну переменную и повторяйте тот же тест.

Для темы «Как передать реальный IP клиента через Nginx» важно не путать открытый firewall с запущенным сервисом: правило доступа не создаёт listener, а активный процесс не гарантирует доступность извне.

Безопасность

После получения рабочего результата уменьшите количество исключений и временных разрешений.

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

Дальнейшее сопровождение

Рабочая конфигурация со временем устаревает и требует контроля.

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

Откат изменений

Откат выполняется в обратном порядке и с теми же проверками, что использовались после настройки.

1. отключить новый location
2. вернуть server-блок
3. проверить nginx -t
4. перезагрузить и проверить основной сайт

Не удаляйте неудачную конфигурацию до выяснения причины: она полезна для diff и разбора инцидента.

Контрольный список

Перед тем как считать тему «Как передать реальный IP клиента через Nginx» закрытой, пройдите список:

Что дополнительно сверить в документации

При подготовке материала были сопоставлены разделы русскоязычной документации. Для углублённой проверки полезно изучить:

• Модуль ngx_http_proxy_module
• nginx: документация
• Как nginx обрабатывает запросы
• Руководство для начинающих

Постоянство настройки после перезагрузки

Убедитесь, что параметр записан в постоянный файл, служба enabled, а временная команда shell не является единственным источником рабочего состояния.

Плановый reboot проводят только после создания резервной точки и подтверждения независимого административного доступа.

Финальная проверка с точки зрения реального клиента

Последнюю проверку темы «Как передать реальный IP клиента через Nginx» выполняйте тем же способом, которым сервисом будет пользоваться человек или приложение: с нужным доменом, протоколом, учётной записью и внешней сетью. Локальная команда остаётся диагностическим этапом, но не заменяет прохождение всей цепочки.

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

proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

Данные, которые нужно сохранить до изменения

Перед работой по теме «Как передать реальный IP клиента через Nginx» сохраните состояние именно тех компонентов, которые участвуют в схеме: активную конфигурацию, статус процесса, открытые порты, последние ошибки и результат контрольного запроса. Этот набор позволит отличить последствия новой правки от ранее существовавшего поведения.

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

location /app/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    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;
}

Повторная проверка после restart или перезагрузки

Часть настроек работает только в текущем процессе или до следующего reload. После успешного первичного теста повторите проверку после штатного restart, а для критичной инфраструктуры — после плановой перезагрузки сервера в окно работ.

Сравните автозапуск, владельцев файлов, постоянные правила firewall, DNS и фактический listener. Это выявляет зависимость от ручной команды, временного файла или правила, которое не сохраняется.

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Контрольные точки именно для этой темы

Для темы «Как передать реальный IP клиента через Nginx» заранее запишите исходные значения и ожидаемый результат. Это позволяет повторить один и тот же тест до изменения, после применения и после возможного отката.

Не считайте задачу завершённой по одному зелёному статусу. Проверка должна охватывать конфигурацию, процесс, сетевой уровень, журнал и прикладной ответ.

• backend отвечает локально
• Nginx видит upstream
• URI после proxy_pass корректен
• клиентский IP передаётся
• длинные ответы не обрываются

ss -lntp | grep ':8080'
curl -v http://127.0.0.1:8080/

Проверка синтаксиса и мягкое применение

Используйте встроенную команду проверки до reload или restart. Мягкое перечитывание предпочтительно, когда программа его поддерживает и изменение не требует полного перезапуска.

Сразу после применения проверяйте журнал и реальный запрос, а не только код возврата systemctl.

Границы задачи: Как передать реальный IP клиента через Nginx

В этой статье рассматривается именно задача «Как передать реальный IP клиента через Nginx», а не полная установка всех компонентов категории «Reverse proxy». Перед началом перечислите файлы, процессы, порты и внешние зависимости, которые реально входят в изменение.

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

Побочные эффекты и соседние компоненты

Изменение по теме «Как передать реальный IP клиента через Nginx» может затронуть соседние части схемы: права файлов, DNS, firewall, reverse proxy, сертификаты, автоматические задания или порядок запуска. До работы перечислите эти связи и выберите по одной короткой проверке для каждой критичной зависимости.

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

Результаты регрессионной проверки записывайте теми же командами, которые использовались до изменения. Это делает сравнение объективным и помогает быстро доказать, что соседний компонент не пострадал.

• основной сервис отвечает тем же способом, что и до изменения
• административный доступ и аварийная консоль остаются доступны
• временные listeners и правила не заняли рабочие порты
• журналы не показывают новые повторяющиеся ошибки

Отделение backend от публичного прокси

Reverse proxy состоит из двух независимых соединений: клиент подключается к Nginx, а Nginx — к backend. Поэтому сначала проверяйте приложение напрямую на локальном адресе, и лишь затем публичный URL.

Если прямой запрос не проходит, правка proxy_set_header или TLS не поможет. Проверьте процесс, listener, локальный firewall, Unix-сокет и журнал приложения.

ss -lntp | grep ':8080'
curl -v --max-time 10 http://127.0.0.1:8080/
journalctl -u BACKEND_SERVICE -n 80 --no-pager

Источники и документация

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

• Модуль ngx_http_proxy_module
• nginx: документация
• Как nginx обрабатывает запросы
• Руководство для начинающих