Настройка WebSocket через reverse proxy Nginx

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

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

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

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

Что должно получиться

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

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

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

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

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

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

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

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

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

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

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

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_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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Перед тем как считать тему «Настройка WebSocket через reverse proxy Nginx» закрытой, пройдите список:

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

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

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

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

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

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

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

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

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

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

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

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

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

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

Перед работой по теме «Настройка WebSocket через reverse proxy 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;
}

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

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

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

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

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

Изменяемый файл и итоговая конфигурация

Определите, какой файл действительно читает процесс и какие include или переменные дополняют его. Редактирование похожего, но неактивного файла создаёт ложное ощущение применения.

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

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

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 обрабатывает запросы
• Руководство для начинающих