Web 服务器与网关 / 系统课时

504 Gateway Timeout 怎么排查

504 Gateway Timeout 怎么排查

504 常见于代理等待上游超过允许时间,但不同超时参数约束的阶段并不相同。本篇在响应首部前制造两秒等待,用一秒读取超时复现失败,再对照正常路径与延长等待上限,解释为什么参数变化不能替代原因修复。

学习目标

  • 从错误日志定位连接、发送或读取阶段的超时。
  • 复现首部前等待导致的 504 并对照正常响应。
  • 按实际服务预算评估超时,保留后端故障证据。

超时先按阶段解释

proxy_connect_timeout 约束建立上游连接;proxy_send_timeout 约束向上游连续发送操作间的等待;proxy_read_timeout 约束连续读取操作间的等待。后两项不是整个请求从头到尾的统一时限。

若首部尚未返回,上游读取等待超时可能产生 504。若正文已经发送给客户端,再发生超时,可能表现为正文截断,不能保证还能改成完整 504 响应。

用可控后端制造等待

实验需要 Linux、Python 3、curl、Nginx 1.28,以及空闲回环 8080、9001。以下完整程序保存为 timeout_app.py,在独立终端执行 python3 timeout_app.py:

python
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

class App(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/slow":
            time.sleep(2)  # 等待期间不发送响应首部。
        try:
            self.send_response(200)
            self.send_header("Content-Length", "3")
            self.end_headers()
            self.wfile.write(b"ok\n")
        except (BrokenPipeError, ConnectionResetError):
            pass  # 实验客户端或代理可能已经离开。

if __name__ == "__main__":
    ThreadingHTTPServer(("127.0.0.1", 9001), App).serve_forever()

预期结果:/fast 立即响应,/slow 在首部前等待约两秒。Ctrl+C 结束实验后端;等待结束才尝试写响应,不等于真实业务能够自动取消工作。

一秒读取等待触发 504

创建新的 /tmp/nginx-504-lab 日志目录,保证 Master 可打开它。以下片段示例位于 http,依赖上述后端:

nginx
server {
    listen 127.0.0.1:8080;
    server_name timeout.test;
    error_log /tmp/nginx-504-lab/error.log error;
    location / {
        proxy_connect_timeout 1s;
        proxy_send_timeout 1s;
        proxy_read_timeout 1s;
        proxy_next_upstream off;
        proxy_pass http://127.0.0.1:9001;
    }
}

检查并重载后执行:

bash
for path in /slow /fast; do
  curl --noproxy '*' --resolve timeout.test:8080:127.0.0.1 -sS -o /dev/null -w 'status=%{http_code}\n' "http://timeout.test:8080$path"
done
tail -n 10 /tmp/nginx-504-lab/error.log

预期输出先为 status=504,再为 status=200。错误日志应指出等待上游响应首部时超时,说明请求已进入读取阶段;它不是端口拒绝连接的证据。

延长上限只能改变等待结果

仅在隔离实验把 proxy_read_timeout 改成 3s,检查并重载,再请求 /slow,应得到 200 且仍等待约两秒。说明失败阈值变了,后端耗时没有因此缩短。参数语义见 Nginx proxy_read_timeout。

现场信号 继续调查
建立连接超时 网络路由、防火墙、上游监听压力及连接指标
等待响应首部超时 应用排队、依赖等待与首部前处理
响应体读取超时 流式输出间隔、上游停顿及网络背压

同时记录整体时间、上游尝试地址与应用请求标识。前方 CDN 或客户端可能有更短时限,不能只调整 Nginx 一处就认为链路预算一致。

给正常等待和异常等待分别设预算

同步接口按真实业务时限设计,长任务可考虑异步状态查询。提高上限前评估并发占用、排队增长、取消传播和重试放大,避免大量请求更久地占住资源。

客户端已经收到超时,不保证后端事务已经回滚;涉及写操作时还需幂等与结果查询。修复后对照正常请求、预期耗时请求和真实失败路径,确认没有通过隐藏错误状态掩盖服务退化。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

504 Gateway Timeout 怎么排查

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通