rpc错误：代码 = Unavailable 描述 = 在收到服务器前言前连接已关闭
rpc error: code = Unavailable desc = connection closed before server preface received
ID: communication/grpc-connection-reset-by-peer-tls
版本兼容性
| 版本 | 状态 | 引入 | 弃用 | 备注 |
|---|---|---|---|---|
| gRPC Go v1.62.0 | active | — | — | — |
| gRPC Python v1.60.0 | active | — | — | — |
| gRPC Java v1.61.0 | active | — | — | — |
| Envoy proxy v1.29.0 | active | — | — | — |
| NGINX 1.25.3 | active | — | — | — |
根因分析
gRPC客户端因TLS握手失败、代理超时或服务器不支持协商协议上的HTTP/2而无法收到HTTP/2服务器前言（初始SETTINGS帧）。
English
gRPC client fails to receive the HTTP/2 server preface (the initial SETTINGS frame) due to TLS handshake failure, proxy timeout, or server not supporting HTTP/2 over the negotiated protocol.
官方文档
https://grpc.io/docs/guides/error/解决方案
-
Verify TLS configuration on the server: ensure the server supports HTTP/2 (requires ALPN with h2). For NGINX, add 'http2 on;' and 'ssl_protocols TLSv1.2 TLSv1.3;' to the server block.
-
Check if a proxy (e.g., Envoy, NGINX) is stripping the ALPN header or not forwarding HTTP/2; configure the proxy to pass through HTTP/2: for Envoy, set 'typed_config: "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"' with 'codec_type: AUTO'.
无效尝试
常见但无效的做法:
-
Disable TLS entirely and use plaintext gRPC
80% 失败
Disabling TLS exposes data to eavesdropping and violates security policies; the error may persist if the root cause is proxy timeout, not TLS.
-
Increase the gRPC client timeout to a very high value (e.g., 5 minutes)
85% 失败
A high timeout does not fix the underlying issue—if the server never sends the preface, the connection will still be closed after a long delay.
-
Use HTTP/1.1 instead of HTTP/2 in the proxy configuration
95% 失败
gRPC requires HTTP/2; downgrading to HTTP/1.1 breaks gRPC streaming and causes different errors like 'Unimplemented'.