Центр Диагностики & База Системных Ошибок

Решения для Windows Server, Active Directory, 1С, СУБД, Linux, Cisco, MikroTik и IP-телефонии.

⚠️ Важная информация Все материалы, инструкции, команды и скрипты предоставлены исключительно в ознакомительных целях. Их применение может повлиять на работу операционной системы, баз данных и сетевого оборудования. Перед выполнением действий обязательно создайте резервную копию. При отсутствии необходимой квалификации обратитесь к ИТ-специалистам.
Nginx Error: gRPC upstream: handshake failed or stream reset by server Linux / DevOps

Nginx: gRPC upstream handshake failed or stream reset — Решение

Обновлено: 18.08.2026  ·  Официальная база знаний

Клиентские gRPC-вызовы завершаются со статусом UNAVAILABLE (14) или INTERNAL (13). В журнале ошибок Nginx регистрируется сбой мультиплексирования HTTP/2 фреймов: gRPC upstream: handshake failed or stream reset by server / upstream rejected gRPC stream with code 2 (INTERNAL_ERROR).

Схема gRPCДиректива NginxПричина сбоя согласования
gRPC без TLS (h2c)grpc_pass grpc://...Бэкенд ожидает зашифрованный TLS, а Nginx шлет plaintext
gRPC с TLS (mTLS)grpc_pass grpcs://...Ошибка валидации сертификата или отсутствие HTTP/2 ALPN
Статус Code 2INTERNAL_ERRORРазрыв TCP-сессии сервером gRPC из-за несовместимости протокола
  • RPC-вызовы методов (gRPC Unary / Streaming) сбрасываются мгновенно при обращении через Nginx.
  • Прямой вызов бэкенда через grpcurl без участия Nginx работает корректно.
  1. Убедитесь, что для входящего клиентского порта в Nginx включен протокол HTTP/2:
    # Для Nginx 1.25.1+:
    server {
        listen 443 ssl;
        http2 on;
        server_name grpc.example.com;
        ...
    }
  2. Если целевой микросервис gRPC работает без шифрования (h2c plaintext), используйте схему grpc://:
    location /my.package.ServiceName/ {
        grpc_pass grpc://127.0.0.1:50051;
        
        # Обязательные gRPC таймауты и буферы:
        grpc_read_timeout 120s;
        grpc_send_timeout 120s;
        grpc_set_header Host $host;
        grpc_set_header X-Real-IP $remote_addr;
    }
  3. Если бэкенд требует зашифрованный TLS (grpcs), используйте схему grpcs:// и включите передачу SNI:
    location / {
        grpc_pass grpcs://backend_grpc_tls;
        grpc_ssl_server_name on;
        grpc_ssl_name backend.internal;
        # При необходимости самоподписанных сертификатов:
        # grpc_ssl_verify off;
    }
  4. Проверьте файл конфигурации: sudo nginx -t.
  5. Примените параметры: sudo systemctl reload nginx.
Внимание к HTTP-методу: Спецификация gRPC жестко требует, чтобы все вызовы выполнялись строго методом POST с заголовком Content-Type: application/grpc. Если промежуточный WAF трансформирует или блокирует эти заголовки, gRPC-сервер сбросит стрим с кодом ошибки.
Практический опыт инженера: Для микросервисов gRPC с долгими соединениями обязательно задавайте `grpc_read_timeout 3600s;` и настраивайте Keep-Alive пинги в коде клиента, иначе Nginx закроет стрим по дефолтному 60-секундному таймауту.

Частые вопросы (FAQ)

Чем grpc_pass отличается от стандартного proxy_pass?

Директива grpc_pass использует специализированный модуль ngx_http_grpc_module, который полноценно поддерживает бинарный транспорт HTTP/2 фреймов, двунаправленный стриминг (Bi-directional streaming) и передачу gRPC Trailers (заголовков завершения статуса RPC).

Поддерживает ли Nginx gRPC Streaming?

Да, Nginx полностью поддерживает клиентский, серверный и двунаправленный (bidirectional) стриминг при условии достаточных таймаутов в директиве grpc_read_timeout.

Как протестировать gRPC эндпоинт за Nginx из консоли?

Используйте CLI утилиту grpcurl: grpcurl -insecure -v grpc.example.com:443 list.

Что означает gRPC статус UNAVAILABLE (14)?

Код 14 означает, что сервис физически недоступен, TCP-соединение не смогло установиться, либо Nginx вернул 502/503 статус при невозможности связаться с бэкендом.