502根本原因是nginx超时主动断连而非后端宕机；proxy_connect_timeout控制响应头等待，proxy_read_timeout控制响应体读取，二者均需调大，并同步调整后端超时及client_max_body_size等参数。

nginx 反向代理超时后返回 502 的根本原因

502 不是后端挂了，而是 nginx 等不及上游响应就主动断开了连接。常见于大文件导入、长事务处理等场景——proxy_read_timeout 默认只有 60 秒，而一次 excel 导入可能卡在解析或数据库写入上，耗时远超这个值。

关键点在于：nginx 在等待 upstream（比如 Flask/Gunicorn/Node.js）返回响应头时，受 proxy_connect_timeout 控制；真正等响应体传输完成，则由 proxy_read_timeout 决定。两者都得调大，否则还没读完数据就 502 了。

常见错误现象：
- 导入界面卡住 60 秒后突然报错 502 Bad Gateway
- nginx error log 里出现 upstream timed out (110: Connection timed out) while reading response header from upstream 或 while reading upstream

必须调整的三个 nginx 缓冲区与超时参数

只改 proxy_read_timeout 是不够的。大文件导入会触发响应体缓存、临时文件写入、客户端流式接收等问题，缓冲区不匹配会导致连接提前中断或内存暴涨。

• proxy_read_timeout 300：设为导入最长预期耗时（单位秒），别用 0（某些版本不支持，且隐藏风险）
• proxy_buffering off：关闭缓冲，让响应直接透传给客户端。开启时 nginx 会攒满 proxy_buffers 才发，对长响应极不友好
• proxy_buffer_size 128k：即使关了 proxy_buffering，首块响应头仍需此缓冲，太小会报 upstream sent too big header

示例片段（放在 location 块内）：

proxy_read_timeout 300;
proxy_connect_timeout 60;
proxy_send_timeout 300;
proxy_buffering off;
proxy_buffer_size 128k;

后端服务也要同步放宽限制

nginx 放宽了，但后端若自己设了超时或请求体限制，照样会提前 kill 掉请求。不能只盯着反向代理。

常见组合问题：

• Gunicorn：--timeout 300 和 --keep-alive 5 必须同步调大，否则 worker 进程自己先超时退出
• Flask：app.config['MAX_CONTENT_LENGTH'] = 500 * 1024 * 1024（如需上传 500MB 文件）
• Nginx 自身请求体限制：client_max_body_size 500M，漏配会导致 413，不是 502，但用户感知一样是“导不进去”

注意：client_max_body_size 要放在 http/server/location 任一有效作用域，且单位必须带 M 或 G，写 500000000 不生效。

如何验证配置是否真正生效

改完 reload nginx 后，别急着测导入——先确认 nginx 是否真的用了新参数，以及后端有没有被其他中间件拦截。

• 查 nginx 实际加载配置：nginx -T | grep -A 5 "location.*upload"，确认参数出现在对应 location 块
• 看 error log 是否还有 timeout 相关报错：tail -f /var/log/nginx/error.log | grep timeout
• 用 curl 模拟长延迟响应测试：curl -v http://localhost:8000/slow-upload，后端该接口 sleep(200)，观察是否真等到 200 秒才返回，还是 60 秒就断

最容易被忽略的是：多个 server 块或 include 文件里存在同名 location，实际生效的可能是别的配置。务必用 nginx -T 输出全量配置来定位真实生效位置。