Обычный GraphQL POST может работать, пока subscriptions полностью сломаны: длительное двунаправленное соединение использует другой транспорт и часто другой route. Первый контрольный признак — WebSocket handshake. Успешное переключение по HTTP/1.1 отвечает 101 Switching Protocols.

Сравните прямое подключение к backend в тестовой сети и публичный wss URL через proxy. Если прямое работает, правьте маршрут, headers или timeout proxy; если оба не работают, проверяйте сервер и согласованный subprotocol.

Status handshake сужает поиск

РезультатЧаще всего означаетЧто проверить
101, затем мгновенный closeSubprotocol/auth/init не принятSec-WebSocket-Protocol, close code, connection_ack
200 HTML/JSONЗапрос попал в обычный HTTP GraphQL routelocation и path rewrite
301/302Redirect во время handshakeСразу использовать конечный wss URL
400/426Нет/неверен UpgradeUpgrade и Connection headers
404Proxy изменил путьСлеши в location/proxy_pass
502/504Backend недоступен или timeoutUpstream address, logs, read timeout

В браузере откройте DevTools → Network → WS, а не только Fetch/XHR. Нужны request URL, status, request/response headers, frames и close code. Authorization payload и персональные данные из connection_init перед публикацией лога удаляют.

NGINX передаёт hop-by-hop headers явно

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    location /graphql-ws {
        proxy_pass http://graphql_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 75s;
    }
}

NGINX указывает, что Upgrade и Connection — hop-by-hop headers и не проходят к upstream автоматически. Для актуальной версии сверяйте необходимость явного proxy_http_version 1.1: документация NGINX помечает различие версий. Значение timeout в примере условное и должно быть больше интервала heartbeat с запасом.

Path проверяем без догадок о слешах

location /graphql-ws и proxy_pass с URI либо без него меняют upstream path по разным правилам. Запишите фактический path в access log proxy и route, который видит GraphQL server. Redirect с /graphql-ws на /graphql-ws/ лучше убрать из handshake и сразу настроить клиент на конечный URL.

  • Публичный клиент использует wss на HTTPS-сайте, а не смешанный ws.
  • DNS и TLS certificate соответствуют публичному host.
  • Origin проверяется по явному allowlist на backend.
  • Sticky sessions включаются только если состояние соединения действительно локально узлу.
  • Load balancer timeout согласован с ping/pong или protocol heartbeat.

Subprotocol должен совпасть на клиенте и сервере

Популярный протокол graphql-ws использует значение graphql-transport-ws в Sec-WebSocket-Protocol и описывает сообщения connection_init, connection_ack и subscribe. Он не совместим с устаревшим subscriptions-transport-ws. Proxy должен сохранить header выбора subprotocol, а обе стороны — говорить на одной версии протокола.

GraphQL Specification описывает семантику Subscription, но конкретный сетевой транспорт выбирает реализация. Поэтому наличие type Subscription в schema ещё не подтверждает правильную настройку WebSocket endpoint.

Обрыв через фиксированное время выдаёт timeout

NGINX по умолчанию закрывает proxied WebSocket, если upstream долго ничего не передаёт; официальная документация приводит интервал 60 секунд и предлагает изменить proxy_read_timeout либо отправлять ping frames. Не делайте timeout бесконечным: heartbeat обнаруживает мёртвые соединения и позволяет освободить ресурсы.

  1. Подключиться и дождаться connection_ack.
  2. Оставить подписку без событий дольше текущего idle timeout.
  3. Увидеть ping/pong или protocol keepalive в согласованном интервале.
  4. Остановить backend и получить ожидаемый close/reconnect.
  5. Перезапустить один upstream и проверить восстановление subscription.
  6. Убедиться, что reconnect не создаёт дубликаты активной подписки.

Приёмка проверяет данные после восстановления

Недостаточно получить 101. После connection_ack подпишитесь на тестовое событие, получите один payload, разорвите соединение и подтвердите reconnect по политике клиента. Если события имеют sequence ID, проверьте пропуск и дубль; WebSocket transport сам по себе не гарантирует replay бизнес-событий после disconnect.

Для разбора достаточно короткого сетевого следа

Приложите обезличенные handshake headers, status, close code/reason, публичный path, фрагмент NGINX location, версии client/server transport и временную шкалу disconnect. Токены из connection_init и полные subscription variables удалите. По этим данным обычно видно, где соединение перестало быть WebSocket.

Проверенные источники