Nginx 反向代理常见坑：缓冲、超时、WebSocket

上传被截断

默认 client_max_body_size 是 1m。接口接收图片或日志包时，Nginx 会直接 413，请求到不了后端。站点如果有上传，我至少写成 20m，并在应用里再限一次，避免只改一层。

另一个隐蔽点是 proxy_request_buffering。大文件上传时，Nginx 会先收完再转给上游。磁盘慢或临时目录满，表现为上传到 99% 失败。对上传路径可以关掉缓冲：

location /api/upload {
    client_max_body_size 32m;
    proxy_request_buffering off;
    proxy_pass http://app;
}

偶发 504

报表、导出、模型推理这类接口，上游要跑十几秒。Nginx 默认 proxy_read_timeout 是 60s，够用。一旦上游超过这个值，访问日志里是 504，应用可能仍在算。

我不会把全局超时拉到 10 分钟。只给慢接口单独加 location，例如 180s，并让前端显示“仍在处理”，避免用户连点。

还要看 proxy_connect_timeout。上游挂了或 listen 队列满，错误会变成 502。这时该看 upstream 健康检查，而不是把超时再加大。

WebSocket 连上又断

升级协议必须把 Hop-by-hop 头传下去，并把读超时拉长。我常用这一段：

location /ws/ {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
    proxy_pass http://app;
}

如果 60 秒就断，几乎一定是默认 read timeout。应用自己有心跳的话，超时可以短一点，但必须长于心跳间隔的两倍。

缓冲对 WebSocket 也添乱。长连接路径上关掉 proxy_buffering，消息才不会被攒成一块再发。

手册：ngx_http_proxy_module。