504责任归属需依据日志与实测：先查nginx error.log中“upstream timed out”后的阶段描述——“while reading response header”指向后端阻塞，“while connecting”指向连接失败，“while sending”指向发送卡顿；再比对access.log的$upstream_response_time字段，结合直连curl测试与超时链梯度验证，精准定位打破时间契约的一方。
504 Gateway Timeout 不是 Nginx 自己挂了，而是它在等后端响应时超时断连。排查重点不是“Nginx 有没有问题”，而是“它等谁？等什么？等了多久？谁先卡住？”——沿着请求链路一层层确认瓶颈位置。
看清楚是哪个 location 触发的 504
同一个 Nginx 实例可能有多个 server 块、多个 location，每个都可以独立配置超时参数。默认值（如 proxy_read_timeout 60s）只在没显式设置时生效。必须定位到具体出错的域名和路径：
- 查访问日志，确认触发 504 的请求命中了哪个 server_name 和 location；
- 进对应配置块，检查是否设置了 proxy_read_timeout、proxy_connect_timeout 等；
- 注意 fastcgi_* 参数仅对 PHP-FPM 生效，与 proxy_pass 到 Java/Node 的场景无关；
- 若用了 CDN 或前置 LB，需通过响应头中的 Via、X-Cache 或自定义 trace-id 反查实际返回 504 的那一层。
验证上游服务是否可达且响应及时
Nginx 能连上，不代表上游能正常处理请求。先绕过 Nginx 直连测试：
- 用 curl 模拟相同请求，直连 upstream 地址（如 curl -v http://127.0.0.1:8080/api/report）；
- 观察响应时间、状态码、body 是否完整；
- 若直连也慢或超时，说明问题在应用层：查应用日志是否有卡顿、慢 SQL、外部依赖阻塞；
- 若直连快但 Nginx 下必现 504，说明 Nginx 与上游之间存在网络延迟、连接复用异常或缓冲区限制。
检查 Nginx 关键超时参数是否匹配业务场景
proxy_read_timeout 是最常需调整的参数，它控制 Nginx 等待上游返回第一个字节的最长时间。默认 60 秒对普通接口足够，但对报表导出、大文件上传、长轮询等场景明显不足：
- 在对应 location 块中显式设置 proxy_read_timeout，例如 300（5 分钟）；
- 同步检查 proxy_connect_timeout（建连）、proxy_send_timeout（发请求），确保它们不比 proxy_read_timeout 更短；
- 若用 PHP-FPM，还需配 fastcgi_read_timeout，并确保它 ≥ proxy_read_timeout；
- 所有 timeout 值建议比后端实际最长耗时多留 5–10 秒缓冲，避免刚踩线就失败。
查 Nginx 错误日志和系统资源水位
错误日志里往往藏着关键线索：
- 打开 error_log（建议设为 warn 或 debug 级别），搜索 “upstream timed out”、“no live upstreams”、“connect() failed”；
- 出现 “upstream timed out (110: Connection timed out)” 说明是 proxy_connect_timeout 触发；
- 出现 “upstream timed out (110: Operation timed out)” 多与 proxy_read_timeout 相关；
- 同时用 top、free -h、netstat -s 查 CPU、内存、连接数、TIME_WAIT 是否异常；
- 特别留意 worker_connections 是否被打满，或 ulimit -n 设置过低导致无法新建连接。
