504错误主因是proxy_read_timeout过短，它控制nginx等待后端首字节时间而非总响应时间；需结合error.log、tcpdump定位，分场景分级设置三类超时参数，并同步调整client端与健康检查配置。
代理超时设太短，最直接的表现就是请求还没处理完，Nginx 就主动断开连接，返回 504 Gateway Timeout。这不是后端真慢，而是 Nginx “等不及”了。解决的关键不是统一拉长所有 timeout，而是分阶段识别、精准调整、配合验证。
先确认是不是 proxy_read_timeout 在“背锅”
90% 的 504 错误其实卡在 proxy_read_timeout 这一关——它管的是 Nginx 等后端返回第一个字节的时间，不是整个响应。比如导出 Excel、生成 PDF、调第三方 API，后端可能前 10 秒都在准备数据，没发任何字节，这时哪怕总耗时 200 秒，只要首字节延迟超了 proxy_read_timeout（默认 60 秒），Nginx 就会断连。
- 查 error.log，搜
upstream timed out (110: Connection timed out) while reading upstream，基本就是它 - 用
tcpdump抓包：若三次握手已完成，但长时间无数据帧，说明是 read 阶段超时，不是 connect 或 send - 临时把该 location 的
proxy_read_timeout放宽到 300s，再测一次，看 504 是否消失
按场景分级设置 proxy 超时参数
三个 proxy timeout 各司其职，不能混着调：
- proxy_connect_timeout：只管 TCP 握手，内网设 3–5s，跨可用区 5–8s，公网后端最多 15s。设太长会让故障发现变慢
- proxy_send_timeout：管 Nginx 往后端发请求的间隔，普通接口 30s 够用；大文件上传可提到 60s
- proxy_read_timeout：最常触发 504，普通 API 60s，导出/长轮询/第三方调用等必须按实际业务时间设，比如 300s 或 600s
统一写在 http 块里作基础值，特殊路径再局部覆盖，例如：
location /export/ {
proxy_read_timeout 600s;
}
别漏掉 client 侧和健康检查
只调 proxy 参数，不控客户端行为，照样会中断：
- client_header_timeout 和 client_body_timeout 设太长（如默认 60s），会让恶意或异常客户端长期占着连接
- send_timeout 控制 Nginx 给客户端发响应的单次写超时，建议 20–60s，避免响应体大时被误杀
- 必须配健康检查：proxy_connect_timeout 设 5s，健康检查 interval 就设 10s；fails 设 2，passes 设 1，否则 Nginx 会持续把请求打到已宕机的节点上
实测验证比改配置更重要
改完不验证，等于没改：
- 停掉一台后端服务，用
curl -v http://your-domain/export/task观察响应延迟是否接近你设的 proxy_read_timeout 值 - 开启
error_log /var/log/nginx/error.log debug;，过滤connect()、readv()相关日志，确认超时触发环节 - 对比修改前后 access.log 中 504 状态码数量，下降明显才说明生效
