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 | |
要点:
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 | |
要点:
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 | |
要点:
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 收益最大。
四、三者对比
| 维度 | WebSocket | SSE | gRPC |
|---|---|---|---|
| 方向 | 双向 | 服务端 → 客户端 | 双向(RPC) |
| 协议 | HTTP 升级后为帧协议 | 普通 HTTP chunked | HTTP/2 |
| Nginx 关键 | Upgrade/Connection、长超时 | proxy_buffering off | grpc_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 |
参考链接
- Nginx 官方文档:WebSocket 代理 —— 升级握手与
map示例; - Nginx 官方文档:ngx_http_proxy_module(proxy_buffering / proxy_ignore_headers) —— SSE 关缓冲;
- Nginx 官方文档:ngx_http_grpc_module ——
grpc_pass/ 超时 /grpc_set_header/grpc_next_upstream; - Nginx 官方文档:ngx_http_v2_module —— gRPC 依赖的 HTTP/2;
- 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
