504本质是网关“等不及”上游响应：Nginx在规定时间内未收到完整响应头即主动断连返回错误，不等于后端崩溃；需逐层排查超时发生位置——Nginx日志与配置、应用线程阻塞点、数据库慢查询及下游依赖延迟。
504 不是后端挂了，而是网关“等不及”了
504 Gateway Timeout 的本质，是 Nginx 作为反向代理，在规定时间内没收到上游服务的完整响应（通常是响应头），于是主动断开连接并返回错误。它不等于后端崩溃、代码异常或数据库死锁——后端进程可能仍在运行，甚至几秒后才返回结果。真正的问题，是 Nginx 与后端之间的时间契约被打破。排查时必须跳出“后端是否在跑”的惯性思维，先确认：这个超时，到底发生在哪一跳？谁在等？等什么？等多久？
Nginx 层：看日志、查配置、验边界
这是第一道也是最关键的防线。别急着改 timeout，先读懂 Nginx 自己说的话：
- 打开 /var/log/nginx/error.log，搜索
upstream timed out，重点关注后面括号里的阶段描述：while reading response header（最常见）、while connecting to upstream或while sending request to upstream——这直接告诉你卡在哪个环节 - 用
grep -A2 -B2 "504" /var/log/nginx/access.log找出对应请求的完整路径、上游地址（upstream:"http://..."）和客户端 IP，确认问题是否集中在某个 API 或某台后端机器 - 检查生效的配置：执行
nginx -T | grep -A10 "location.*\/api"，确认你修改的proxy_read_timeout确实落在当前匹配的 location 块里；注意，server块或更外层的默认值可能被覆盖 - 警惕“超时倒挂”：CDN 超时（如 30s）＜ Nginx
proxy_read_timeout（如 60s）＜ 应用自身超时（如 90s），会导致 CDN 先返回 504，而 Nginx 日志里却看不到超时记录
应用层：查线程、看堆栈、测健康
如果 Nginx 明确报“读响应头超时”，说明请求已成功发到后端，但后端迟迟不给回应。此时重点不是 CPU 占用率，而是阻塞点：
- 立刻调用后端的健康检查接口：
curl -I http://backend-ip:port/actuator/health（Spring Boot）或自定义端点，确认服务存活且能快速响应 - 抓取线程快照：Java 用
jstack PID，Go 用curl http://localhost:6060/debug/pprof/goroutine?debug=2，分析是否有大量线程卡在WAITING或TIMED_WAITING状态，常见于数据库连接池耗尽、同步锁竞争、第三方 HTTP 调用未设超时 - 检查应用日志中是否出现
Connection refused、Timeout waiting for connection或频繁的SQLException，这些是数据库层问题的前置信号
数据库与下游依赖：慢查询、连接池、网络延迟
很多“低负载 504”最终都指向数据库。一个没走索引的查询，可能让单个请求卡住 15 秒，而 Nginx 默认只等 60 秒，高峰期并发一上来就全超时：
- 开启并检查 MySQL 慢查询日志：
SET GLOBAL long_query_time = 1;，然后查SHOW FULL PROCESSLIST;看是否有长时间运行的Query状态语句 - 验证连接池：应用日志里搜
waiting for connection；数据库侧执行SHOW STATUS LIKE 'Threads_connected';对比最大连接数，确认是否打满 - 测试直连延迟：从 Nginx 服务器执行
mysql -h db-host -u user -p -e "SELECT 1;"，观察是否卡顿；再用tcping db-host 3306测基础网络连通性与握手耗时 - 别忽略其他依赖：Redis 主从切换、Kafka 消费者堆积、内部 gRPC 服务未配
grpc_read_timeout，都可能成为超时链路上的隐性瓶颈
