Nginx返回504 Gateway Timeout，通常表示它作为网关或代理没有在规定时间内拿到上游所需响应。但“规定时间”可能来自Nginx、CDN、负载均衡、API网关或客户端中的任一层。第一步不是调大proxy_read_timeout，而是确认504究竟由谁生成。
请求时间线先拆开
| 阶段 | 可能耗时 | 重点检查 |
|---|---|---|
| 解析上游 | DNS查询与缓存 | Resolver、内部DNS和地址变化 |
| 连接上游 | TCP握手与排队 | proxy_connect_timeout、端口和连接池 |
| TLS握手 | 证书与加密协商 | SNI、CA、协议和CPU |
| 上游处理 | 应用、数据库和下游API | Trace、慢查询、线程池和超时 |
| 读取响应 | 首字节与分段读取 | proxy_read_timeout、流式响应 |
| 发送客户端 | 缓冲、带宽与慢客户端 | Buffer、临时文件和send timeout |
如何确认504由哪一层返回
比较响应头、错误页样式、请求ID和各层日志时间。CDN可能在Nginx仍等待上游时先返回504；Nginx也可能在应用最终完成前断开。将边缘、Nginx和应用日志用统一请求ID关联，才能重建时间线。
proxy_connect_timeout解决什么
它主要限制Nginx建立到上游连接所等待的时间。连接阶段慢通常与上游端口不可达、SYN重传、连接队列、DNS地址错误或资源耗尽有关。将连接超时改得很长，会让大量失败请求占用工作连接。
proxy_read_timeout并非整个请求总时长
它通常约束从上游两次读取操作之间的等待，而不是简单的“业务总执行时间”。持续有数据的流式响应与长时间没有任何数据的任务表现不同。应按当前Nginx版本和模块语义核对，不能把它当作统一截止时间。
上游慢到底慢在哪里
应用日志要记录排队、业务计算、数据库、缓存和外部API耗时。若Nginx连接很快、首字节很慢，重点在应用或依赖；若应用根本没有收到请求，则查连接、DNS和上游选择。仅看平均值容易忽略少量高分位慢请求。
缓冲有什么影响
启用代理缓冲时，Nginx会读取并缓存上游响应，再按客户端速度发送，可能使用内存和临时文件。大响应、磁盘慢或空间不足会造成额外压力。对SSE等流式响应通常需要不同策略，但关闭缓冲也会让慢客户端更长时间占用上游连接。
Keepalive连接会带来什么误判
上游Keepalive提高复用效率，旧连接被防火墙或上游提前关闭时，也可能出现重置。检查连接池、空闲超时和上游部署变更是否协调。不要把所有重置都归因于“网络不稳定”。
多层代理的超时应怎样排列
一般应让内层业务拥有明确截止时间，外层超时略大于内层并预留返回空间。若CDN 30秒、Nginx 60秒、应用90秒，客户端会先得到失败，而应用继续消耗资源。具体值需按业务SLO和资源容量设计。
写请求超时后为什么不能直接重试
客户端收到504时，上游可能已经完成下单、扣款或写入，只是响应未返回。自动重试必须使用幂等键、请求ID和状态查询。相关原则见代理超时、重试与幂等恢复。
日志至少增加哪些字段
- 请求ID与上游地址；
- 请求总时间和上游连接时间；
- 上游首字节/响应时间与状态；
- 重试过的上游节点；
- 请求体和响应体大小；
- Nginx实例、配置版本与Trace ID。
排查顺序
- 确认504生成层和准确时间；
- 从Nginx日志判断连接还是读取阶段；
- 关联应用Trace、慢查询与外部依赖；
- 检查连接池、DNS和资源饱和；
- 用受控慢请求复现；
- 按SLO协调各层超时；
- 验证写请求幂等与状态查询。
结论
Nginx 504不是一个“超时调大”问题，而是一条时间线。找到等待发生在DNS、连接、应用还是响应流，再协调缓冲和多层截止时间，才能避免故障从快速失败变成长时间资源占用。
