504-gateway-timeout

504 Gateway Timeout 的定位与修复

现象

网关返回 504 Gateway Timeout，表示它已经连上上游，但在超时时间内没有拿到完整响应。和 502 不同，504 通常是后端太慢，而不是完全不可达。

快速定位

curl -v -w '\n total=%{time_total}\n' http://<gateway>/<path>
tail -f /var/log/nginx/error.log
grep -i 'upstream timed out' /var/log/nginx/error.log
journalctl -u <backend> --since '10 min ago'
ss -lntp | grep ':<backend-port>'

常见根因

后端查询慢：数据库慢查询、锁等待、外部 API 超时。
网关 proxy_read_timeout/proxy_connect_timeout 太短。
后端连接池、线程池或 worker 耗尽，请求排队。
大请求体、流式响应或长轮询被网关提前切断。
网络延迟、丢包或中间代理超时。

修复

先看后端是否真的慢：用 curl 直连后端测耗时，再对比经过网关的耗时。
优化慢查询、加索引、减少同步外部调用，必要时异步化。
按业务合理调整网关超时，不要为了掩盖慢查询无限调大。
扩容后端、调整连接池和 worker 数，避免排队。
长任务改成异步接口或流式返回，配心跳。
加超时率、P99 延迟和上游错误告警。

相关命令

curl — 分段测耗时
nginx — 网关超时配置
journalctl — 后端日志
ss — 后端连接状态

读完自测

合上页面，先回答，再展开对照。

收到 504 通常说明后端不可达还是后端太慢？
如何判断是后端真的慢，还是网关超时设置太短？
是否应该为了消除 504 无限调大网关超时？

答案

504 表示网关已经连上上游，但在超时时间内没有拿到完整响应。通常是后端太慢，而不是完全不可达。
用 curl 直连后端测耗时，再对比经过网关的耗时。同时看 proxy_read_timeout/proxy_connect_timeout。
不应该。页面强调不要为了掩盖慢查询无限调大。应先优化慢查询、异步化并扩容后端。