不能用 proxy_pass 实现 gRPC 反向代理，必须使用 grpc_pass 指令并启用 HTTPS+HTTP/2，配置 grpc_buffering off、延长超时、复用连接及错误页返回标准 gRPC 状态头。
不能用 proxy_pass 实现 gRPC 协议的反向代理转发。
gRPC 基于 HTTP/2 二进制帧传输，要求端到端支持流式、长连接、头部压缩和多路复用。而 proxy_pass 是为 HTTP/1.x 设计的指令，即使在 Nginx 1.13.10+ 中显式设置 proxy_http_version 2.0，它仍无法正确透传 gRPC 的二进制 payload、HTTP/2 伪头（如 :method, :path）、状态码（如 grpc-status）及流控制帧。实际使用中会直接触发以下典型错误：
-
rpc error: code=Unavailable desc="error reading server preface: http2: frame too large" -
426 Upgrade Required（客户端要求 HTTP/2，Nginx 未启用或降级） -
502 Bad Gateway（协议不匹配导致连接提前关闭） -
"Stream removed"（缓冲或超时截断流）
真正可行且官方支持的方式是 必须使用 grpc_pass —— 这是 Nginx 专为 gRPC 流量设计的指令，自动启用 HTTP/2 协议栈、透传二进制帧、兼容 gRPC 状态头，并与 upstream 的 grpc:// 或 grpcs:// 地址语义对齐。
必须启用 HTTPS + HTTP/2
gRPC 客户端（Go/Python/Java SDK）默认只通过 TLS 启动 HTTP/2 连接；明文 h2c 在生产环境几乎不可用，且 Nginx 仅允许在 ssl 监听下启用 http2。
server {
listen 443 ssl http2; # 关键：ssl 和 http2 必须同时存在
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
}注意：Nginx 1.25+ 要求
http2 on;单独写在server块内，不可再塞进listen指令。
正确配置 grpc_pass 指令
grpc_pass 不是 proxy_pass 的别名，而是独立协议适配器。后端地址必须用 grpc://（明文）或 grpcs://（TLS），不能混用。
-
后端是本地明文 gRPC 服务（如 Go
grpc.NewServer()默认）：location / { grpc_pass grpc://127.0.0.1:50051; } -
后端也启用了 TLS（如双向认证场景）：
location / { grpc_pass grpcs://127.0.0.1:50051; grpc_ssl_verify off; # 测试可关；生产需配 grpc_ssl_certificate 等 } -
需负载均衡时，定义
upstream并引用：upstream grpc_backend { server 10.0.1.10:50051; server 10.0.1.11:50051; keepalive 32; # 复用连接，减少握手开销 } location / { grpc_pass grpc://grpc_backend; }
关键性能与稳定性调优
gRPC 是长连接流式协议，Nginx 默认的缓冲和超时策略会破坏流完整性。
-
禁用缓冲（防止粘包、延迟响应）：
grpc_buffering off;
-
延长读写超时（适应空闲流、大文件流、双向流）：
grpc_read_timeout 3600; # 1小时 grpc_send_timeout 3600;
-
强制复用连接（避免频繁建连）：
grpc_set_header Host $host; grpc_set_header X-Real-IP $remote_addr; # keepalive 已在 upstream 中配置，此处无需 proxy_set_header Connection
错误处理与可观测性增强
gRPC 错误需返回标准 grpc-status 和 grpc-message 头，而非 HTML 页面。
error_page 502 = @grpc_unavailable;
location @grpc_unavailable {
internal;
default_type application/grpc;
add_header grpc-status 14;
add_header grpc-message "unavailable";
return 204;
}
# 添加调试头便于排障
add_header X-Grpc-Upstream $upstream_addr;
add_header X-Grpc-Time $upstream_response_time;不复杂但容易忽略。
