Настройка WebSocket в nginx на Ubuntu 24.04
WebSocket в nginx проксируется через proxy_pass с заголовками Upgrade и Connection. Без них handshake не проходит и клиент получает 400 или обрыв. Настройка занимает один блок location и проверку через curl.
01Проверьте, что nginx установлен
На сервере уже должен работать nginx 1.24 из репозитория Ubuntu 24.04. Проверьте версию и статус службы. Если пакета нет, установите его командой sudo apt install nginx и вернитесь к проверке.
nginx -v
sudo systemctl status nginx
02Узнайте адрес и порт WebSocket-бэкенда
Приложение, которое принимает WebSocket, слушает свой порт или unix-сокет. Для примера возьмём 127.0.0.1:3000. Убедитесь, что процесс запущен и слушает именно этот адрес.
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 секунд.
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 продолжит работать со старым конфигом.
sudo nginx -t
sudo systemctl reload nginx
05Проверьте handshake через curl
Запрос с заголовками Upgrade: websocket и Connection: Upgrade должен вернуть 101 Switching Protocols. Код 101 означает, что nginx передал соединение бэкенду. Код 400 или 502 говорит о проблеме в конфиге или на бэкенде.
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.
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 Docker nginx: установка и настройка обратного прокси Пошагово: установка nginx в Docker на Ubuntu 24.04, конфиг обратного прокси, проверка через curl и разбор частых ошибок с логами.
- Руководство · Nginx Установка nginx на Ubuntu 24.04 и настройка сайта с PHP Пошаговая установка nginx на Ubuntu 24.04: apt, настройка PHP 8.3 через php-fpm, конфиг сайта, логи и проверка через nginx -t и systemctl status.
- Руководство · Nginx found nginx: почему nginx отдаёт 404 и как это исправить Пошаговая инструкция: как найти причину 404 Not Found в nginx на Ubuntu 24.04, проверить конфиг, пути и права, перезагрузить nginx и убедиться, что страница…
- Руководство · Nginx Nginx версии: установка и настройка на Ubuntu 24.04 Пошаговая настройка nginx на Ubuntu 24.04: установка версии 1.24, конфиг сайта, PHP 8.3, проверка nginx -t и reload, разбор ошибок 403, 502, 504.
- Руководство · Nginx Настройка nginx location на Ubuntu 24.04 Пошаговая настройка nginx на Ubuntu 24.04: установка, директива location, конфиг сайта, проверка синтаксиса и перезагрузка. Разбор частых ошибок.
- Руководство · Nginx Настройка сайта в nginx на Ubuntu 24.04 Пошаговая настройка сайта в nginx на Ubuntu 24.04: конфиг в sites-available, симлинк, проверка nginx -t, reload, права и PHP-FPM. Команды и проверка.
Настройка nginx на сервере: от установки до рабочего конфига: все материалы темы