Nginx 工程实践 -- 13. WebSocket、SSE 与 gRPC 代理

HTTP 请求-响应模型之外,还有三类"长连/流式"流量:WebSocket 是全双工长连接,SSE 是服务端单向推送,gRPC 是基于 HTTP/2 的多路复用 RPC。它们对 Nginx 的要求各不相同,但共同点是都不能套用到普通代理的默认缓冲/超时设置。

一、WebSocket

WebSocket 借 HTTP 握手升级:客户端带 Upgrade: websocket,服务端回 101 Switching Protocols,之后连接转为双向帧通道。

sequenceDiagram
    participant C as 客户端
    participant N as Nginx
    participant U as 后端
    C->>N: "GET /ws Upgrade: websocket"
    N->>U: "转发 Connection: upgrade"
    U-->>N: "101 Switching Protocols"
    N-->>C: "101 Switching Protocols"
    C->>N: 数据帧
    N->>U: 数据帧
    U-->>N: 数据帧
    N-->>C: 数据帧

配置:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}

server {
location /ws/ {
proxy_pass http://127.0.0.1:3000;

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;

# 长连接不能按普通请求设短超时
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
}

要点:

  • Connection 必须按需设置:写死 upgrade 会污染普通请求,用 map 按 Upgrade 头决定;
  • proxy_http_version 1.1; 是升级握手的前提;
  • 长连接要放大 proxy_read_timeout(两次读之间,默认 60s 对静默连接太短);
  • 帧数据是透传的,Nginx 不解析内容,日志里按连接计。

二、SSE(Server-Sent Events)

SSE 是"HTTP 响应体持续写入"的推送模型:服务端不断 data: ...\n\n,客户端持续读。关键在别让 Nginx 缓冲住。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
location /events/ {
proxy_pass http://127.0.0.1:3000;

proxy_http_version 1.1;
proxy_set_header Connection "";

# 关闭缓冲,让每个事件即时下发
proxy_buffering off;
proxy_cache off;

# 用 chunked 持续发送
chunked_transfer_encoding on;
proxy_read_timeout 3600s;
}

要点:

  • proxy_buffering off 是核心:否则 Nginx 会攒够缓冲再发,SSE 就"卡住不出流";
  • 后端可返回 X-Accel-Buffering: no,Nginx 也会据此关闭该响应的缓冲(可用 proxy_ignore_headers X-Accel-Buffering; 禁用这一行为);
  • 客户端断开(499)时,后端可能仍在写,需自行处理断连;
  • 经过 CDN 时要确认 CDN 不缓冲 SSE 路径。

三、gRPC

gRPC 基于 HTTP/2(多路复用、头部压缩),Nginx 用专门的 ngx_http_grpc_module 转发,要求已启用 ngx_http_v2_module。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
server {
listen 9000;
http2 on;

location / {
grpc_pass grpc://127.0.0.1:9000;
# 对上游也是 TLS 时:grpc_pass grpcs://127.0.0.1:9443;

grpc_connect_timeout 5s;
grpc_read_timeout 60s;
grpc_send_timeout 60s;

grpc_set_header Host $host;
grpc_next_upstream error timeout http_502 http_503 http_504;
}
}

要点:

  • grpc_pass 可指向地址、grpc:///grpcs:// 或 upstream 组;
  • grpc_set_header 语义与 proxy_set_header 类似;默认不转发 Date、Server、X-Accel-*,需要时用 grpc_pass_header;
  • grpc_read_timeout / grpc_send_timeout 是两次操作之间的超时,流式调用要按消息间隔评估;
  • 错误处理:grpc_intercept_errors on 可把 ≥300 的响应交给 error_page;
  • 客户端到 Nginx 这一段通常也是 HTTP/2(listen ... http2 on + TLS),保持全链路 HTTP/2 收益最大。

四、三者对比

维度WebSocketSSEgRPC
方向双向服务端 → 客户端双向(RPC)
协议HTTP 升级后为帧协议普通 HTTP chunkedHTTP/2
Nginx 关键Upgrade/Connection、长超时proxy_buffering offgrpc_pass、http2 on
缓冲不需要缓冲必须关缓冲由 HTTP/2 帧处理
典型超时read/send 放大read 放大按消息间隔

五、排错

现象原因 / 处理
WebSocket 握手 400缺 proxy_http_version 1.1 或 Upgrade 头没传
握手后立刻断开Connection 写死或 $connection_upgrade 取错;后端未回 101
静默一会儿就断proxy_read_timeout 太小;放大
SSE 只收到第一批proxy_buffering 未关,或中间 CDN 缓冲
gRPC 连接被拒ngx_http_v2_module 未启用;http2 on 没配
gRPC 偶发 UNAVAILABLE上游连接复用/超时问题;检查 grpc_read_timeout 与 keepalive

参考链接

  1. Nginx 官方文档:WebSocket 代理 —— 升级握手与 map 示例;
  2. Nginx 官方文档:ngx_http_proxy_module(proxy_buffering / proxy_ignore_headers) —— SSE 关缓冲;
  3. Nginx 官方文档:ngx_http_grpc_module —— grpc_pass / 超时 / grpc_set_header / grpc_next_upstream;
  4. Nginx 官方文档:ngx_http_v2_module —— gRPC 依赖的 HTTP/2;
  5. MDN:Server-sent events、Using SSE。

小结

  • WebSocket:proxy_http_version 1.1 + map 决定 Connection,放大 read/send 超时;
  • SSE:proxy_buffering off + proxy_cache off,确认 CDN 不缓冲;
  • gRPC:grpc_pass + http2 on,按需 grpc_pass_header/grpc_intercept_errors;
  • 三者都不要沿用普通代理的短超时与默认缓冲;
  • 握手/断连类问题先看请求头与 101,流式问题先看缓冲与超时。

系列导航


Nginx 工程实践 -- 13. WebSocket、SSE 与 gRPC 代理
https://bubao.github.io/posts/d3e4f5a6.html
作者
一念
发布于
2026年11月21日
许可协议