如何配置 proxy_pass 实现对 gRPC 协议的高性能反向代理转发实战-Nginx-PHP中文网

不能用 proxy_pass 实现 gRPC 反向代理，必须使用 grpc_pass 指令并启用 HTTPS+HTTP/2，配置 grpc_buffering off、延长超时、复用连接及错误页返回标准 gRPC 状态头。

如何配置 proxy_pass 实现对 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（如双向认证场景）：

Bailian Usage Proxy
阿里百炼大模型平台多人共享账号用量统计代理服务。解决公司共用账号时无法区分个人用量的问题。适用场景：1)部署用量统计代理；2)统计多人Token用量和调用次数；3)管理大模型API调用配额。

下载
```
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;

不复杂但容易忽略。