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 服务。

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 错误信息。

常见失败处理

如果出现调用失败,可以按照以下顺序定位:

  1. 检查 Nginx 是否启用了 http2。
  2. 确认使用的是 grpc_pass 而不是普通 HTTP 代理。
  3. 检查 TLS 证书和客户端信任链。
  4. 查看后端 gRPC 服务是否监听正确地址。
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

代理 gRPC 服务

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通