Web 服务器与网关 / 系统课时
代理 gRPC 服务
代理 gRPC 服务
本课解决 Nginx 作为网关代理 gRPC 服务时的配置问题。通过 grpc_pass、HTTP/2 和 TLS 相关设置,可以让客户端稳定访问后端 gRPC 服务,并正确理解 gRPC 状态与 HTTP 状态之间的区别。
学习目标
- 掌握 Nginx 代理 gRPC 服务的基本配置方式。
- 理解 gRPC、HTTP/2 和 TLS 的关系。
- 学会定位 gRPC 调用失败的常见原因。
gRPC 代理工作方式
gRPC 基于 HTTP/2 传输,普通 proxy_pass 主要面向 HTTP/1.x 请求,因此不能直接代理 gRPC 流量。Nginx 需要使用专用的 grpc_pass 指令,将 HTTP/2 请求帧转发给后端 gRPC 服务。
如果客户端通过 HTTPS 访问 gRPC 网关,还需要配置 TLS 证书。Nginx 负责完成客户端连接加密,再将请求转发到后端明文或加密 gRPC 服务。

配置 Nginx 代理 gRPC
下面示例展示 TLS 终止在 Nginx 的常见部署方式。后端 gRPC 服务监听 <PORT> 端口。
nginx
server {
listen 443 ssl http2;
server_name grpc.example.com;
ssl_certificate /etc/nginx/cert.pem;
ssl_certificate_key /etc/nginx/key.pem;
location / {
grpc_pass grpc://127.0.0.1:<PORT>;
# 透传客户端身份信息,便于后端记录来源
grpc_set_header Host $host;
# 控制长时间 RPC 的等待时间
grpc_read_timeout 300s;
grpc_send_timeout 300s;
}
}预期结果
text
Nginx starts with HTTP/2 enabled.
gRPC client connects successfully.
RPC method returns OK status.配置完成后,需要执行配置检查和重新加载,使新的 gRPC 路由生效。
验证一元调用和流式调用
gRPC 调用是否成功不能只看 HTTP 状态码。一次 RPC 请求通常会返回 HTTP/2 层状态和 gRPC 层状态,其中 gRPC 状态码更能反映服务执行结果。
bash
grpcurl -plaintext \
-d '{"name":"nginx"}' \
localhost:<PORT> example.Service/Hello预期结果
text
{
"message": "Hello nginx"
}对于流式调用,需要保持连接持续读取消息。如果客户端能够持续收到服务端消息,说明 HTTP/2 长连接和流控制均正常。
理解 gRPC 状态与 HTTP 状态差异
gRPC 通常使用 HTTP 200 表示传输层成功建立,但业务失败可能通过 gRPC status 返回。例如权限不足、参数错误或服务内部异常,都可能表现为 HTTP 成功而 gRPC 失败。排查时应同时查看:
- Nginx access.log 中的 HTTP 状态。
- 应用日志中的 gRPC status code。
- 客户端显示的 RPC 错误信息。
常见失败处理
如果出现调用失败,可以按照以下顺序定位:
- 检查 Nginx 是否启用了
http2。 - 确认使用的是
grpc_pass而不是普通 HTTP 代理。 - 检查 TLS 证书和客户端信任链。
- 查看后端 gRPC 服务是否监听正确地址。
按自己的节奏,确认真正理解。