Nginx代理出现504 Gateway Timeout

知识分享

2026-08-27 05:00

59 阅读

Nginx 代理出现 504 Gateway Timeout，意思是 Nginx 作为反向代理在限定时间内没有等到后端服务器（如 PHP-FPM、Java 应用、另一台内网机器）返回响应。
常见原因并不是 Nginx 本身出错，而是后端处理太慢、连接不通或 Nginx 默认超时时间设置太短。
本文会把 Nginx 代理涉及的超时参数全部说明白，并给出可直接复制使用的配置片段，帮你一步步定位和修复问题。

504 产生前，先确认后端是否真的健康

修改任何参数之前，先确认后端服务本身是否正常。
直接在服务器上执行下面命令，检查端口是否能连通：

curl -I http://127.0.0.1:8080 -m 5

如果后端是 PHP 环境，也可以检查对应端口进程：

ss -lntp | grep 8080

若 curl 迟迟不返回或报错，说明后端卡死或端口监听异常，此时调大 Nginx 超时只能暂时掩盖问题，优先修复后端。
若 curl 能快速返回，则大概率是 Nginx 的超时阈值过小。

Nginx 代理超时参数有哪些，分别作用在哪里

Nginx 的 http、server、location 块里都可以配置超时参数。
代理场景下最常用的是这几个：

proxy_connect_timeout：Nginx 与后端建立 TCP 连接的超时时间，默认 60 秒，通常不需要调太大，5-10 秒足够。
proxy_send_timeout：Nginx 向后端发送请求数据的超时时间，默认 60 秒。
proxy_read_timeout：Nginx 等待后端响应数据的超时时间，默认 60 秒。这是 504 最常命中的参数，后端处理超过这个时间就会被判定超时。
fastcgi_connect_timeout、fastcgi_send_timeout、fastcgi_read_timeout：如果 Nginx 通过 FastCGI 代理到 PHP-FPM，需要修改这一组参数，而不是上面的 proxy 系列。
proxy_buffer_size 和 proxy_buffers：不是传统意义上的“超时”，但响应头或响应体过大时也会触发异常中断，容易被误认为超时。

修改时首先要判断你用的是普通反向代理（proxy_pass）还是 FastCGI（fastcgi_pass）。
宝塔面板、LNMP 一键包常见的是 fastcgi，使用 Laravel、ThinkPHP 等框架时尤其要看 fastcgi_read_timeout。

按场景调整超时配置

下面给出两种最常见场景的配置示例。
修改前建议先备份原配置：

cp /www/server/nginx/conf/nginx.conf /www/server/nginx/conf/nginx.conf.bak

场景一：普通 HTTP 代理到 Java/Node/Python 服务

在对应的 server 或 location 块中添加：

location /api/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_connect_timeout 10s;
    proxy_send_timeout 60s;
    proxy_read_timeout 300s;
}

场景二：Nginx + PHP-FPM 出现 504

打开站点的 .conf 文件，找到 location ~ \.php 或 location ~ [^/]\.php 部分，在内部添加：

location ~ \.php$ {
    fastcgi_pass unix:/tmp/php-cgi-74.sock; # 按实际路径修改
    fastcgi_connect_timeout 10s;
    fastcgi_send_timeout 120s;
    fastcgi_read_timeout 300s;
}

如果同站点还有后台导入、导出等功能，建议把超时时间调高到 600 秒，或者把耗时任务改成异步队列，避免长时间占用 PHP 进程。

改完配置如何验证与常见避坑

配置修改后必须重载 Nginx 才生效：

nginx -t && nginx -s reload

如果有宝塔面板，也可以直接点击“重载配置”。
验证方式分两步：

再次触发之前产生 504 的请求，观察是否恢复；
查看 Nginx 错误日志：

tail -f /www/wwwlogs/nginx_error.log

若日志中出现 upstream timed out，说明是 proxy_read_timeout 或 fastcgi_read_timeout 不够；
若出现 connect upstream timed out，则是 proxy_connect_timeout 过短或后端防火墙拦截。

避坑提醒：不要盲目把所有超时都调到几千秒。
过长的 proxy_read_timeout 会占用大量连接资源，导致 Nginx 并发能力下降。
更合理的做法是先定位慢请求来自哪个接口，然后只对那个 location 单独调大超时。
同时注意 PHP 的 max_execution_time 也要相应调整，否则 Nginx 等到了，PHP 进程自己却已终止。

最后说一句实操结论

遇到 Nginx 代理 504 时，先确认后端端口是否正常，再根据代理类型（proxy_pass 还是 fastcgi_pass）修改对应超时参数，最后用 nginx -t 校验配置并重载。
大多数情况下，把 proxy_read_timeout 或 fastcgi_read_timeout 从 60 秒调整到 300 秒即可解决。
若调大后仍超时，问题不在 Nginx，而在后端应用本身，需要检查数据库慢查询、外部接口调用或服务器负载。
建议你在本地测试环境中先模拟慢请求，确认参数调整确实生效，再放到生产环境。

Redis连接数打满，客户端泄漏

中转服务容器化Docker‑Compose一键部署生产模板