[Nginx排查] 504 Gateway Time-out 错误频发？原因分析与超时参数调优指南

当你使用 Nginx 作为 Web 服务器或反向代理时，遇到各种 HTTP 错误状态码是在所难免的。其中，504 Gateway Time-out 错误是相对常见但也颇为棘手的一种。它通常意味着，Nginx 已经成功地将用户的请求转发给了后端的应用服务器（比如 PHP-FPM、Node.js 应用、Python/uWSGI 服务，或者另一个 Web 服务器），但是后端应用在 Nginx 设定的“耐心等待时间”内，没能及时给出完整的响应。Nginx 等啊等，等到花儿都谢了，后端还是“默不作声”或者“慢条斯理”，最后 Nginx 只能无奈地放弃等待，并告诉浏览器：“抱歉，我作为网关去上游服务器取东西，结果等太久了，它没给我回应！”

这就像你派了一个非常耐心的“采购员”（Nginx）去一家口碑不错的“工厂”（后端应用）取货。采购员到了工厂，下了订单，也成功联系上了工厂负责人。但是，工厂生产这批货（处理请求）的速度实在太慢了，采购员在门口等了半天（Nginx 的超时时间），货还没出来。最后采购员只能空手而归，并告诉你：“对不起，工厂超时了，货没拿到。”

理解了这个场景，我们就能明白，504 错误通常指向的是**后端应用的性能瓶颈或响应缓慢**，或者是**Nginx 与后端之间的网络通信问题（虽然较少见）**，以及 Nginx 自身对这种“慢响应”的**容忍度（超时设置）**。

Table of Contents

504 Gateway Time-out vs. 502 Bad Gateway：超时与坏网关，有何不同？

在开始排查之前，我们有必要区分一下 504 和它那个经常一起出现的“难兄难弟”——502 Bad Gateway。它们虽然都是服务器端错误，都和 Nginx 与后端的交互有关，但含义是不同的：

502 Bad Gateway (坏网关): 通常意味着 Nginx 尝试连接后端时，后端服务**直接不可达**（比如服务没启动、端口不通、Socket 文件不存在），或者后端服务虽然连接上了，但返回了一个**无效的、无法理解的响应**（比如连接被重置、返回了非 HTTP 格式的数据）。简单说，502 是“后厨关门了”或者“后厨做的菜没法吃”。
504 Gateway Time-out (网关超时): 通常意味着 Nginx **已经成功连接**到了后端服务，并且后端服务也收到了请求，正在处理中。但是，后端服务处理这个请求花费的时间**太长了**，超过了 Nginx 配置中设定的等待超时上限，Nginx 最终放弃了等待。简单说，504 是“后厨开着门，也在做菜，但做菜速度太慢，服务员等不及了”。

搞清楚这个区别，能帮助我们更有针对性地去排查。如果遇到 502，我们优先检查后端服务是否在运行、监听地址是否正确。如果遇到 504，我们则需要重点关注后端应用为什么会这么慢，以及 Nginx 的超时设置是否合理。

第一步：初步排查 – 是不是“偶感风寒”？

在深入挖掘之前，先做几个快速检查，排除一些简单或临时性的问题：

刷新页面大法： 按下 Ctrl+F5 (Windows) 或 Cmd+Shift+R (Mac) 进行强制刷新，清除浏览器缓存再试一次。有时候可能只是网络瞬间抖动或者后端服务临时的小卡顿，刷新一下就好了。
检查服务器整体负载： 登录到你的服务器，快速看一下当前的系统负载。 [提示：请将以下代码片段复制并粘贴到 WordPress 的“代码”区块中] uptime htop # 或者 top 如果服务器的 load average 持续很高，CPU 使用率爆满，或者可用内存所剩无几、Swap 被大量使用，那么很可能是整个服务器都处于高压状态，导致所有服务（包括你的后端应用）都响应缓慢。这种情况下，你需要先解决服务器的资源瓶颈问题
确认 Nginx 服务本身正常： 虽然 504 通常不是 Nginx 的直接问题，但还是检查一下它的状态： [提示：请将以下代码片段复制并粘贴到 WordPress 的“代码”区块中] sudo systemctl status nginx 确保它是 active (running)。如果 Nginx 都没跑起来，那用户连 504 都看不到，直接就是“无法连接”了。
近期是否有变更操作？ 回想一下，在 504 错误开始频繁出现之前，你或你的团队是否对服务器配置、后端应用程序代码、数据库结构、或者网络环境等进行过任何更改？有时候，一次不当的部署或配置调整，就可能引入性能问题，导致后端响应变慢。

如果这些初步检查都没发现明显问题，或者 504 错误是持续稳定地出现，那我们就需要进一步深入“后厨”看看了。

第二步：深入“后厨” – 后端应用为何“慢吞吞”？

既然 504 的核心原因是后端响应太慢，那么我们排查的重点自然就要放在那个“慢吞吞的后厨”——也就是你的后端应用程序（PHP-FPM, Node.js 应用, Python/Django/Flask 应用, Java/Spring Boot 应用等）身上。

再次确认 Nginx 的“后厨地址”： 打开你的 Nginx 网站配置文件，找到 proxy_pass 或 fastcgi_pass 指令，确认 Nginx 请求的是哪个后端地址、端口或 Socket 文件。确保这个信息是准确无误的。
排查后端应用性能瓶颈： 这是最关键也可能最复杂的一步。你需要分析为什么你的后端应用处理一个请求需要那么长时间。可能的原因包括：
- 代码中存在长时间运行的脚本或操作： 你的 PHP 脚本、Python 代码或 Node.js 函数里，是不是有一些非常耗时的计算、文件读写、或者循环操作？有没有可能陷入了死循环或者不合理的递归？ 如何排查： 查看后端应用的日志，寻找线索。使用应用性能监控 (APM) 工具（如 New Relic, Datadog, Sentry，或者语言特定的 Profiler 如 Xdebug for PHP, cProfile for Python）来剖析代码，找出执行时间最长的函数或代码段。
- 数据库查询缓慢： 对于动态网站，数据库操作往往是性能瓶颈的重灾区。是不是某个 SQL 查询语句没有命中索引导致了全表扫描？是不是有复杂的 JOIN 操作或者子查询效率低下？数据库本身是否负载过高？ 如何排查： 开启数据库的慢查询日志 (Slow Query Log)，分析那些执行时间超长的 SQL 语句。使用 EXPLAIN 命令分析查询的执行计划，看看是否用到了索引。优化 SQL 语句、为查询涉及的字段添加合适的索引、或者对数据库服务器进行参数调优。检查数据库服务器的 CPU、内存、I/O 是否饱和。
- 依赖的外部 API 服务响应缓慢： 你的后端应用是不是在处理请求的过程中，需要调用第三方的 API 接口（比如支付接口、天气接口、地图接口、或者其他微服务）？如果这些外部 API 响应非常慢或者超时了，你的应用就得一直等着，自然也就无法及时给 Nginx 返回响应。 如何排查： 在你的应用代码中，对所有外部 API 调用增加详细的日志记录（包括请求发出时间、收到响应时间、对方返回的状态码等）。检查这些外部调用的耗时是否过长。如果可能，为外部调用设置合理的超时时间，并做好容错处理（比如超时后返回默认值或错误提示，而不是无限等待）。
- 后端服务自身资源不足或配置不当：
  - PHP-FPM： pm.max_children（最大子进程数）设置是否过低，导致没有足够的 worker 进程来处理并发请求？PHP 脚本的 memory_limit 或 max_execution_time 是否设置不合理？
  - Node.js/Python 应用： 运行应用的进程数是否足够？是否有内存泄漏导致应用越来越慢？
  - Java 应用： JVM 堆内存 (-Xms, -Xmx) 是否分配不足？垃圾回收 (GC) 是否过于频繁或耗时过长？
  如何排查： 查看对应后端服务的配置文件和日志。使用特定语言或平台的监控工具来分析其内部状态。
找到并优化后端应用的性能瓶颈，是解决 504 问题的根本之道。

第三步：Nginx 日志里有什么线索？

虽然 504 通常是后端的问题，但 Nginx 的错误日志仍然能为我们提供一些有用的线索，至少能确认问题确实出在与后端的通信上。

定位 Nginx 错误日志： 通常在 /var/log/nginx/error.log，或者你为特定网站配置的错误日志路径。
寻找与超时相关的错误信息： 在 504 错误发生的时间点附近，查找包含以下关键词的日志条目：
- upstream timed out (110: Connection timed out) while reading response header from upstream: 这是最典型的 504 错误日志。它表示 Nginx 在等待从后端服务器读取响应头时超时了。
- upstream timed out (110: Connection timed out) while reading upstream: 类似上面，可能是在读取响应体时超时。
这些日志明确地告诉我们，Nginx 因为等不到后端的及时响应而主动关闭了连接。
(可选) 检查访问日志中的上游响应时间： 如果你的 Nginx 访问日志格式 (log_format) 中配置了记录 $upstream_response_time 变量，你可以通过查看访问日志，找到那些返回 504 状态码的请求，看看它们的上游响应时间是不是非常长，或者直接就是一个 Nginx 超时设置的值。这也能印证是后端处理慢导致的超时。

第四步：Nginx 超时参数“调教”指南 (理解与调整)

既然是“超时”错误，那么调整 Nginx 的超时参数设置，是不是就能解决问题呢？理论上是的，但这里面有“学问”。简单粗暴地无限延长超时时间，并不能解决根本问题，反而可能拖垮你的 Nginx 服务器。

你需要了解 Nginx 中与后端通信相关的几个主要超时参数：

proxy_connect_timeout (用于 proxy_pass): Nginx 与后端 HTTP 服务器建立连接的超时时间。默认通常是 60s。如果后端服务器本身响应新连接就很慢，可能会触发这个超时，但它通常不直接导致 504（更可能导致 502 或 503）。
proxy_send_timeout (用于 proxy_pass): Nginx 向后端服务器发送请求的超时时间。默认 60s。如果请求体很大且网络慢，可能触发。
proxy_read_timeout (用于 proxy_pass): 这是导致 504 错误的最常见 Nginx 参数！ 它定义了 Nginx 从后端服务器读取响应的超时时间。也就是说，从 Nginx 成功连接到后端并发送完请求后，如果在该时间内没有收到后端完整的响应，Nginx 就会关闭连接并返回 504。默认通常是 60s。
fastcgi_connect_timeout, fastcgi_send_timeout, fastcgi_read_timeout (用于 fastcgi_pass，如 PHP-FPM): 作用分别与上面的 proxy_ 系列超时类似，只不过是专门针对 FastCGI 后端的。其中，fastcgi_read_timeout 是导致 PHP 应用出现 504 的关键参数。默认通常也是 60s。
send_timeout: Nginx 向客户端发送响应的超时时间。这个超时通常与 504 关系不大，因为 504 是 Nginx 等不到后端响应。

如何调整这些参数？

分析后端正常的最大响应时间： 首先，你应该通过监控、日志分析或性能剖析，大致了解你的后端应用在正常情况下处理一个复杂请求所需的最长时间是多少。
谨慎增加读取超时时间： 如果你的后端应用确实有一些合法的、需要较长时间（比如超过默认 60 秒）才能完成的操（比如生成复杂报表、进行大数据量处理），那么你可以考虑**适度**增加 proxy_read_timeout 或 fastcgi_read_timeout 的值。例如，在你的 Nginx 配置文件中对应的 http, server 或 location 块里（通常在 location 块里针对特定路径设置更精确）： [提示：请将以下代码片段复制并粘贴到 WordPress 的“代码”区块中] # 对于反向代理到其他 HTTP 服务的 location location /some_slow_api/ { proxy_pass http://backend_api_server; proxy_read_timeout 120s; # 增加到 120 秒 proxy_connect_timeout 10s; # 连接超时可以短一些 # 其他 proxy_... 指令 } # 对于处理 PHP 的 location location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/var/run/php/php8.1-fpm.sock; # 替换为你的FPM socket fastcgi_read_timeout 180s; # 增加到 180 秒 # 其他 fastcgi_... 指令 }
重要警告：超时不是万能药！
- 简单地大幅增加 Nginx 的超时时间，并**不能解决后端应用本身性能低下的根本问题**。它只是让 Nginx 这个“服务员”更有耐心去等那个“慢厨师”而已。
- 设置过长的超时时间（比如几分钟甚至十几分钟），会导致 Nginx 的工作进程 (worker) 长时间地被这些慢请求占用，无法去处理其他新的、快速的请求。在高并发情况下，这反而可能**耗尽 Nginx 的连接资源，导致整个网站对所有用户都变得非常缓慢甚至不可用！**
所以，调整 Nginx 超时参数通常是作为一种**临时缓解**或**为合法长耗时任务提供必要窗口**的手段。**优化后端应用的性能，才是解决 504 问题的王道！**
修改配置后，别忘了： [提示：请将以下代码片段复制并粘贴到 WordPress 的“代码”区块中] sudo nginx -t sudo systemctl reload nginx

第五步：检查后端应用（如 PHP-FPM）自身的超时设置

光给 Nginx 这个“服务员”延长等待时间还不够，你还得确保“后厨”本身不会因为“内部规定”而提前“下班”或“放弃做菜”！很多后端应用或服务（比如 PHP-FPM, Python Gunicorn/uWSGI, Java Tomcat 等）自身也有执行超时或请求处理超时的设置。

以 **PHP-FPM** 为例，你需要关注：

max_execution_time (在 php.ini 文件中): 这个参数定义了一个 PHP 脚本允许执行的最长时间（默认通常是 30 秒）。如果你的 PHP 脚本因为某些原因（比如复杂计算、外部 API 调用缓慢、死循环等）执行时间超过了这个值，PHP 解释器会主动终止脚本的执行。这时，即使 Nginx 的 fastcgi_read_timeout 设置得再长，PHP-FPM 也已经“罢工”了，Nginx 最终还是会收到一个无效响应或连接断开，可能导致 502 或 504。
request_terminate_timeout (在 PHP-FPM 的 `pool` 配置文件中，如 www.conf): 这个参数为 FPM 工作池中的单个请求设置了一个“硬性”的终止超时。如果一个 PHP 脚本的执行时间达到了这个值，FPM 主进程会向对应的子进程发送一个终止信号。这个值应该设置得比 max_execution_time 稍长一些（如果设置了的话），或者作为独立的超时控制。

如何调整？

你需要确保 PHP-FPM 的这些超时设置，能够容纳你应用中那些合法的、耗时较长的脚本的正常执行时间，并且最好与 Nginx 的读取超时（fastcgi_read_timeout）相协调。通常，PHP 的超时应该比 Nginx 的超时略短或接近，以便让 PHP 先有机会正常结束或报错，而不是让 Nginx 干等。

例如，如果你把 Nginx 的 fastcgi_read_timeout 设为 180 秒，那么你可能需要将 PHP 的 max_execution_time 和 PHP-FPM 的 request_terminate_timeout 也调整到一个合适的值（比如 170 秒或 180 秒）。

修改 PHP 相关配置后，记得重启 PHP-FPM 服务：

[提示：请将以下代码片段复制并粘贴到 WordPress 的“代码”区块中]


sudo systemctl restart php8.1-fpm # 替换为你的 PHP-FPM 服务名

对于 Node.js, Python, Java 等其他后端应用，也需要检查它们各自的 HTTP 服务器模块或应用服务器是否有类似的请求处理超时设置。

第六步：网络问题再排查（Nginx 与上游之间）

虽然比较少见，但如果 Nginx 和你的后端应用部署在**不同的服务器**上，它们之间的网络连接质量也可能导致 504。

中间网络设备/防火墙： 检查这两台服务器之间的所有网络路径（路由器、交换机、防火墙、云平台的网络 ACL 等），确保没有设备会因为连接时间过长或流量特征而主动断开或重置 TCP 连接。
网络延迟或丢包： 使用 ping 或 mtr 从 Nginx 服务器测试到后端应用服务器的网络质量，看是否存在高延迟或丢包，这可能导致通信效率低下，间接触发超时。

对于通过公网连接的后端服务（比如 Nginx 作为公网 API 的代理），这种网络问题导致 504 的可能性会更高。

结论：让“耐心”的 Nginx 等到“靠谱”的回复

Nginx 的 504 Gateway Time-out 错误，就像是“服务员”对“慢吞吞的后厨”失去了耐心。绝大多数情况下，这意味着你的**后端应用程序响应太慢或者完全没有在 Nginx 设定的时间内给出响应**。

解决这个问题的核心思路是：

优先优化后端！优先优化后端！优先优化后端！ （重要的事情说三遍）找出并解决导致你应用响应缓慢的根本原因（代码效率、数据库查询、外部 API 调用等）。
如果后端确实存在一些合法的、无法在短时间内完成的长耗时任务，那么再**谨慎地、适度地**增加 Nginx 的相关读取超时参数（如 proxy_read_timeout 或 fastcgi_read_timeout），并确保后端应用自身的执行超时设置与之协调。
持续监控你的应用性能和服务器资源，才能在问题发生时快速定位。

希望这篇指南能帮助你不再对 504 错误感到束手无策，而是能够有条不紊地分析原因，调整参数，最终让你的 Nginx 这个“耐心服务员”总能等到来自“高效后厨”的美味佳肴！

还有疑问？常见问题解答 (FAQs)

问: 如果我的服务器负载很高 (CPU/内存占用高)，是不是一定会导致 504？ 答: 很大概率会导致。 当服务器整体资源（CPU、内存、磁盘 I/O）非常紧张时，所有运行在上面的进程（包括你的后端应用程序）都会受到影响，处理速度会变慢。如果后端应用因为抢不到足够的资源而无法在 Nginx 的超时时间内完成请求处理，就会导致 Nginx 返回 504。所以，解决服务器高负载是处理 504 的一个重要前提。
问: Nginx 的 keepalive_timeout 参数和 504 有关系吗？ 答: keepalive_timeout 主要控制的是 **Nginx 与客户端（浏览器）之间**的 HTTP Keep-Alive 连接的空闲超时时间，它与 Nginx **与后端（上游）服务器之间**的连接超时（如 proxy_read_timeout）是两个不同的概念。所以，keepalive_timeout 通常不直接导致 504 错误。但如果设置不当（比如过长导致大量空闲连接占满 Nginx 资源），可能会间接影响 Nginx 处理新请求或与后端通信的能力，但这不是 504 的直接原因。
问: 为什么我的网站有时候访问很快，有时候又会突然出现 504 错误？ 答: 这种情况通常表明你的后端应用性能存在不稳定性，或者服务器资源在某些时候会达到瓶颈。可能的原因包括：1) **突发流量高峰**导致后端处理不过来。2) 后端应用中某些**特定操作或特定请求路径**特别耗时（比如某个复杂的数据库查询只在特定条件下触发）。3) **定时任务或后台进程**在某个时间点运行，占用了大量服务器资源，影响了前端应用的响应。4) **外部依赖服务**（如第三方 API）在某些时候响应缓慢。你需要结合 504 发生的时间点，去分析当时的服务器负载、后端应用日志和可能的外部因素。
问: 504 错误会影响我的网站 SEO 吗？ 答: 会的，特别是如果频繁或持续出现。 504 错误意味着用户无法正常访问你的页面内容，这直接损害了用户体验。搜索引擎爬虫在抓取时如果也遇到 504，会认为你的网站不稳定或不可靠。如果这种情况持续存在，搜索引擎可能会降低你网站的抓取频率，甚至将返回 504 的页面从索引中暂时移除或降低排名。因此，及时解决 504 错误对于维护良好的 SEO 和用户体验非常重要。
问: 如果我使用了负载均衡器（比如 Nginx 作为负载均衡器，后面带多个应用服务器），504 错误该怎么排查？ 答: 基本思路是一样的，但排查范围扩大了。你需要：1) 检查**负载均衡器（Nginx）本身的日志**，看是哪个（或哪些）后端应用服务器返回了超时。2) **逐个排查**那些超时的后端应用服务器，按照本文中针对单个后端应用的排查步骤进行分析（检查其自身应用日志、资源使用、配置等）。3) 检查**负载均衡器与后端服务器之间的网络连接**是否稳定。4) 检查负载均衡器的**健康检查 (Health Check)** 配置是否正确，它是否能及时发现并剔除有问题的后端实例？5) 负载均衡器自身的**超时参数**（比如它等待后端响应的超时时间）是否设置合理？

{{userData.name}}已认证