Nginx как reverse proxy для локального сервиса

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

Материал посвящён теме «Nginx как reverse proxy для локального сервиса» с акцентом на первичной установке и минимальной рабочей конфигурации.

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

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

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

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

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;

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

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

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

Проверка должна охватывать конфигурацию, процесс, 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Перед тем как считать тему «Nginx как reverse proxy для локального сервиса» закрытой, пройдите список:

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

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

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

Границы задачи: Nginx как reverse proxy для локального сервиса

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

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

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

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

Полезно хранить вывод в одном каталоге с временной меткой и коротким 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;
}

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

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

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

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

Таймауты и долгоживущие соединения

proxy_connect_timeout ограничивает установление соединения с backend, а proxy_read_timeout — ожидание данных после подключения. Увеличение всех таймаутов без диагностики может лишь дольше скрывать зависший процесс.

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

proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
proxy_http_version 1.1;

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

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

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