HTTPTools

HTTP 504 Gateway Timeout

中间人等得不耐烦了:上游服务器没有在代理的时限内做出响应。

HTTP 504 是什么意思

HTTP 504 Gateway Timeout 由代理、负载均衡器或 CDN 发出,表示它向上游服务器发出的请求在超时时间内没有收到任何响应。与 502(上游给出了错误响应)不同,504 表示上游根本没有及时给出任何响应。

根本原因几乎总是幕后某个环节速度缓慢:一个昂贵的数据库查询、一个响应迟缓的外部 API,或被负载压垮而资源耗尽的应用线程池。

504 错误的常见原因

  • 一个缓慢的数据库查询或缺失的索引,使某个端点耗时超过了代理允许的上限。
  • 应用程序在等待一个本身缓慢或已宕机的外部 API。
  • 后端已饱和:所有 worker 都在忙碌,请求在超时之前就已排队等待。
  • 代理与上游之间的网络问题(路由、丢包、DNS)。
  • 超时设置不匹配:应用程序确实需要 60 秒,而代理在 30 秒时就已切断。

作为访客该如何处理

  • 稍等片刻后重试——单次 504 通常只是一次慢请求,而不是一次真正的故障。
  • 对于你提交的操作(支付、订单),在重试之前先检查它是否实际已经完成。

作为开发者该如何修复

  • 在访问日志/APM 中找到慢速端点:优化查询、添加索引、缓存结果。
  • 把耗时的工作转移到后台任务,并快速返回一个客户端可以轮询的状态。
  • 端到端地统一超时预算(应用 < 代理 < CDN),以便明确知道哪个环节最慢且这是有意为之的。
  • 在不稳定的外部 API 周围添加熔断器,而不是让它们拖垮你的 worker。

示例响应

HTTP/1.1 504 Gateway Timeout
Server: nginx
Content-Type: text/html

<html><body><h1>504 Gateway Timeout</h1></body></html>

常见问题

504 和 502 有什么区别?

504 表示上游在超时时间内始终没有响应;502 表示上游给出了某种无效响应。

504 是用户连接的问题吗?

不是——问题出在网站的代理和其后端之间。用户的网络本身是正常的。

如果收到 504,我提交的请求是否已被处理?

有可能是的——超时命中的是响应环节,不一定是处理过程本身。在盲目重试非幂等操作之前,应先检查其实际状态。