网关 504/502：先查 proxy_read_timeout

前端偶发 504 Gateway Timeout 或 502 Bad Gateway，而后端日志显示请求其实还在处理——先别急着加机器。很多时候是 Nginx 作为反向代理时，读上游响应等太久就断开了。本文帮你判断是不是 proxy_read_timeout，怎么改，以及怎样确认修好。

你遇到的问题（现象）

现象	更可能是
固定在某个秒数附近失败（如 60s）	代理读超时（常见默认 60s）
上游进程还在、Nginx 已返回 504	`proxy_read_timeout` 偏小
立刻 502，上游连不上 / 进程崩溃	不是超时，先查上游存活与 `proxy_pass`
只有慢接口（导出、报表、大模型）失败	应对慢接口单独加大超时，或改异步

2 分钟诊断

看失败是否卡在固定时长（对齐 Nginx 默认或你的配置）。
对照时间线：Nginx error log 是否有 upstream timed out；上游是否仍在跑。
用 curl 直打上游（绕过 Nginx）：若直打能完成、经网关失败 → 优先查代理超时。

# 看当前 server/location 是否显式配置
grep -R "proxy_read_timeout" -n /etc/nginx/

# 复现时盯 error log
tail -f /var/log/nginx/error.log

解法

proxy_read_timeout：Nginx 向代理服务器读取响应时的最长等待。超时常见表现为 504；上游异常断开则可能是 502。

在对应 location（或 http/server）设置，例如慢接口 120s：

location /api/ {
  proxy_pass http://upstream_app;
  proxy_read_timeout 120s;
  # 按需一并核对：
  # proxy_connect_timeout 10s;
  # proxy_send_timeout 60s;
}

原则：

只给慢接口加大，不要全局改成 10 分钟掩盖后端问题
导出/长任务优先改异步 + 轮询/回调，超时只是兜底
改完 nginx -t && nginx -s reload

如何验证已修好

原先必现的慢请求经网关可完整返回（或明确走到异步任务）
error log 不再出现对应 upstream timed out
直打上游与经网关的耗时量级一致
正常快接口未被误伤（无需无意义加长全局超时）

常见坑

只改 proxy_connect_timeout：连得上但仍读超时 → 必须看 proxy_read_timeout
前端 axios/浏览器也有超时：三层（浏览器 / 网关 / 上游）要对齐
用超大超时掩盖死锁/慢 SQL：超时消失了，体验仍差 → 回去治根因

下一步

标出失败接口的 P95 耗时，把超时设为「略高于 P95」而不是拍脑袋。
若经常 > 60s，评估异步化，而不是无限加超时。
需要系统看 Nginx 网关排障时，再翻站点里的 Nginx 问题索引文。