Проксирование WebSocket в Nginx: настройка заголовков Upgrade, Connection и устранение ошибки 1006 на VDS

1. Анатомия рукопожатия WebSocket и почему Nginx сбрасывает соединение

Протокол WebSocket (RFC 6455) обеспечивает полнодуплексный двунаправленный обмен сообщениями между клиентом и сервером поверх единого постоянного TCP-соединения. Он лежит в основе современных веб-чатов, дашбордов с живыми котировками и графиками, систем мгновенных push-уведомлений, совместных редакторов и ботов.

Установление WebSocket-сессии всегда начинается с обычного HTTP-запроса, называемого рукопожатием (WebSocket Handshake). Клиент отправляет стандартный запрос методом GET со специальными заголовками согласования:

GET /ws/ HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

Если бэкенд готов перейти на протокол веб-сокетов, он возвращает ответ со статусом HTTP 101 Switching Protocols:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

С этой секунды TCP-сокет перестает быть HTTP-каналом: клиент и сервер начинают обмениваться легковесными бинарными или текстовыми фреймами с минимальным оверхедом (всего 2–10 байт на сообщение вместо сотен байт HTTP-заголовков).

Чтобы проверить, какие заголовки фактически возвращает ваш сервер при попытке подключения, воспользуйтесь онлайн-инструментом Анализ HTTP-заголовков онлайн.

2. Директива map $http_upgrade: безопасное переключение протоколов

Самая распространенная ошибка начинающих администраторов — жестко прописать в конфигурации проксирующего блока:

# Ошибочный подход: жесткая фиксация заголовка Connection
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Такая запись приводит к скрытым багам: если к тому же эндпоинту или виртуальному хосту обратится обычный REST API или браузер со стандартным HTTP-запросом (где заголовок Upgrade отсутствует), Nginx все равно принудительно отправит бэкенду заголовок Connection: upgrade. Многие бэкенд-фреймворки (FastAPI, Node.js, Go) расценивают такой запрос как некорректный и аварийно завершают обработку с ошибкой 400.

Официальный стандарт Nginx требует использования динамической карты map в контексте http:

# Файл /etc/nginx/nginx.conf (внутри блока http { ... })
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

3. Конфигурация виртуального хоста Nginx для проксирования сокетов

Объединим директиву map и параметры обратного проксирования в боевой конфигурации виртуального хоста Nginx.

Откройте файл конфигурации сайта (например, /etc/nginx/sites-available/app.conf):

# 1. Задаем пул upstream-серверов или локальный порт приложения
upstream websocket_backend {
    # Приложение на Node.js, Python, Go или Laravel Reverb
    server 127.0.0.1:3000;
    keepalive 32;
}

server {
    listen 80;
    server_name app.example.com;

    # Основной эндпоинт приложения или выделенный путь сокетов /ws/
    location /ws/ {
        proxy_pass http://websocket_backend;

        # Обязательный перевод проксирования на HTTP/1.1
        proxy_http_version 1.1;

        # Проброс динамически согласованных заголовков рукопожатия
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # Проброс контекста клиента для авторизации и логирования
        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_buffering off;

        # Увеличение таймаутов для предотвращения разрыва молчащих сессий
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }

    # Регулярные веб-страницы и статика
    location / {
        proxy_pass http://websocket_backend;
        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:

# Тест синтаксиса конфигурации Nginx
sudo nginx -t

# Применение новых правил без сброса активных сессий
sudo systemctl reload nginx

Готовые проверенные шаблоны конфигураций для популярных стеков доступны в наших pSEO-инструментах: Конфигурация Nginx для Laravel с WebSocket (Reverb / Echo) и Nginx Reverse Proxy для Node.js и Next.js с WebSocket.

4. Устранение ошибки 1006 (Abnormal Closure) и настройка таймаутов

Классическая ситуация: рукопожатие успешно завершилось, сокет открылся, данные начали передаваться. Но если пользователь отвлекся и перестал отправлять сообщения, ровно через 60 секунд соединение самопроизвольно обрывается.

В консоли браузера при этом регистрируется событие WebSocket.onclose со следующим кодом:

// Вывод в консоли разработчика браузера (F12)
WebSocket connection to 'wss://app.example.com/ws/' failed: 
WebSocket is closed before the connection is established.
// CloseEvent: code = 1006 (Abnormal Closure), reason = ""

Код 1006 (Abnormal Closure) — это псевдокод браузера, зарезервированный спецификацией RFC 6455. Он указывает, что соединение было физически прервано на транспортном TCP-уровне (получен пакет TCP RST или TCP FIN) без предварительного обмена контрольным фреймом закрытия (Close Frame).

Для устранения этой проблемы применяются два взаимодополняющих решения:

1. Увеличение таймаута на стороне Nginx:
   Установите proxy_read_timeout 86400s; (24 часа) или 3600s (1 час) внутри блока location. Это предотвратит закрытие сокета самим веб-сервером.
2. Внедрение Heartbeat (Ping/Pong фреймов) на стороне бэкенда:
   Даже если в Nginx таймаут равен суткам, сокет могут разорвать промежуточные узлы: NAT-роутеры домашних провайдеров, мобильные вышки операторов связи или облачные балансировщики. Протокол WebSocket имеет встроенные фреймы опроса: Ping (0x9) и Pong (0xA).

Пример реализации автоматического пинга в Node.js (библиотека ws):

// heartbeat.js на стороне Node.js сервера
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 3000 });

function heartbeat() {
  this.isAlive = true;
}

wss.on('connection', (ws) => {
  ws.isAlive = true;
  ws.on('pong', heartbeat);
});

// Отправляем Ping клиентам каждые 30 секунд
const interval = setInterval(() => {
  wss.clients.forEach((ws) => {
    if (ws.isAlive === false) return ws.terminate();
    ws.isAlive = false;
    ws.ping(); // Отправляет легковесный Ping-фрейм
  });
}, 30000);

wss.on('close', () => clearInterval(interval));

SecurityError: Failed to construct 'WebSocket': An insecure WebSocket connection may not be initiated from a page loaded over HTTPS.

# Установка Certbot и плагина Nginx через snap
sudo snap install core && sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

# Автоматический выпуск сертификата с настройкой редиректа на HTTPS
sudo certbot --nginx -d ws.example.com --redirect