К содержимому

Настройка WebSocket в nginx на Ubuntu 24.04

WebSocket в nginx проксируется через proxy_pass с заголовками Upgrade и Connection. Без них handshake не проходит и клиент получает 400 или обрыв. Настройка занимает один блок location и проверку через curl.

Руководство Nginx 2 мин чтения

01Проверьте, что nginx установлен

На сервере уже должен работать nginx 1.24 из репозитория Ubuntu 24.04. Проверьте версию и статус службы. Если пакета нет, установите его командой sudo apt install nginx и вернитесь к проверке.

bash
nginx -v
sudo systemctl status nginx

02Узнайте адрес и порт WebSocket-бэкенда

Приложение, которое принимает WebSocket, слушает свой порт или unix-сокет. Для примера возьмём 127.0.0.1:3000. Убедитесь, что процесс запущен и слушает именно этот адрес.

bash
sudo ss -ltnp

03Добавьте location с проксированием WebSocket

Откройте конфиг сайта /etc/nginx/sites-available/example.com и добавьте блок location /ws/. Директивы proxy_http_version 1.1, proxy_set_header Upgrade $http_upgrade и proxy_set_header Connection "upgrade" передают handshake на бэкенд. proxy_read_timeout 3600s держит соединение открытым дольше стандартных 60 секунд.

nginx
location /ws/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 3600s;
}

04Проверьте конфиг и перезагрузите nginx

Синтаксис проверяется командой sudo nginx -t. Если ошибок нет, примените конфиг через sudo systemctl reload nginx: соединения не оборвутся, а при ошибке nginx продолжит работать со старым конфигом.

bash
sudo nginx -t
sudo systemctl reload nginx

05Проверьте handshake через curl

Запрос с заголовками Upgrade: websocket и Connection: Upgrade должен вернуть 101 Switching Protocols. Код 101 означает, что nginx передал соединение бэкенду. Код 400 или 502 говорит о проблеме в конфиге или на бэкенде.

bash
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" http://example.com/ws/

06Проверьте работу в браузере и в логах

Откройте страницу сайта, которая устанавливает WebSocket-соединение, и посмотрите вкладку Network в инструментах разработчика: статус должен быть 101. Если соединение падает, причина будет в /var/log/nginx/error.log.

bash
sudo tail -n 50 /var/log/nginx/error.log

Частые ошибки

  • В location нет proxy_http_version 1.1, и nginx отправляет бэкенду HTTP/1.0. Handshake не проходит, клиент получает 400 или соединение сразу закрывается.

    Добавьте proxy_http_version 1.1; в блок location рядом с proxy_set_header Upgrade.

  • Заголовок Connection задан как $connection_upgrade без map, и nginx пишет unknown variable. Либо Connection не передан вовсе, и бэкенд отвечает 400.

    Используйте proxy_set_header Connection "upgrade"; в блоке WebSocket. Если нужен map, объявите его в блоке http в /etc/nginx/nginx.conf.

  • Соединение обрывается через 60 секунд простоя. Это срабатывает proxy_read_timeout по умолчанию.

    Увеличьте proxy_read_timeout в блоке WebSocket, например до 3600s, и перезагрузите nginx.

  • В error.log строка connect() failed (111: Connection refused) while connecting to upstream. Бэкенд не запущен или слушает другой порт, чем указан в proxy_pass.

    Проверьте sudo ss -ltnp и приведите адрес в proxy_pass к тому порту, который слушает приложение.

Deploykin

Как это делается в Deploykin

В Deploykin сайт создаётся из панели, и конфиг nginx под Laravel, WordPress или PHP панель пишет сама. Править конфиги можно в редакторе панели: перед сохранением конфиг проверяется на сервере, а прежняя версия уходит в резервную копию.

7 дней бесплатно на тарифе Про, без привязки карты.

Вопросы и ответы

Зачем нужны заголовки Upgrade и Connection при настройке WebSocket в nginx?

Они передают handshake от клиента к бэкенду. Без Upgrade: websocket и Connection: upgrade nginx обрабатывает запрос как обычный HTTP, и WebSocket-соединение не устанавливается.

Почему WebSocket-соединение в nginx обрывается через минуту?

Срабатывает proxy_read_timeout, по умолчанию 60 секунд. Увеличьте его в блоке location для WebSocket, например до 3600s, и перезагрузите nginx.

Можно ли проксировать WebSocket по HTTPS?

Да. Блок location с proxy_pass и заголовками Upgrade и Connection работает и внутри server с listen 443 ssl. Клиент должен подключаться по wss://.

Какой код ответа подтверждает, что WebSocket работает через nginx?

101 Switching Protocols. Его возвращает curl с заголовками Upgrade: websocket и Connection: Upgrade, и его же видно в браузере на вкладке Network.

Ещё по теме

Настройка nginx на сервере: от установки до рабочего конфига: все материалы темы

Мы используем cookies и сервис веб-аналитики «Яндекс Метрика» (включая Вебвизор) для улучшения работы сайта. Подробности — в политике конфиденциальности.