← 返回

如何使用 OpenResty XRay 排查 HTTP 504 超时错误

章亦春发布于 Dec 29, 2023 更新于 Jul 24, 2026

用时 5 分钟

阅读次数

HTTP 504 网关超时错误意味着作为反向代理的 OpenResty 或 Nginx 服务器在等待上游服务器响应时放弃了等待。根本原因几乎总是三者之一：上游服务器慢、两者之间的网络链路慢，或代理侧的超时设置太短。本教程展示如何使用 OpenResty XRay 在一台在线的 OpenResty 或 Nginx 服务器上精确定位到底是哪一个原因。

使用 OpenResty XRay 快速透视和解决您的软件问题

在 OpenResty 访问日志中确认 504 网关超时

每一次 504 排查都从访问日志开始。这里我们 tail OpenResty 的访问日志并过滤 504 状态码。

日志本身足以确认症状：/api/order/all 和 /api/sync/config 请求的状态都是 504，并且每隔几秒就重复出现一次。所以我们知道 504 错误正在发生，也知道受影响的是哪些接口。

但访问日志的答案也到此为止。上游服务器慢、网络链路慢、代理超时设置太短——这三种情况会产生完全相同的 504 日志行，仅凭状态码根本无法区分。要判断到底是哪一种，就必须深入到导致 504 的那条 TCP 连接内部，找出时间到底花在了哪里。这正是下一步要做的事情。

使用 OpenResty XRay 引导式分析定位根因

OpenResty XRay 可以在一台在线服务器上分析这些 504 错误，并还原连接内部到底发生了什么。打开 XRay 的 Web 控制台，确认监控的机器正确，然后进入 Guided Analysis 页面，选择要诊断的问题类型。

配置流程很短：选择 Errors & exceptions，选中上一步中的 OpenResty 应用，范围选 整个应用，语言层保持 Lua 和 C/C++，分析时间保持默认的 300 秒，然后开始。XRay 会自动执行多轮分析并生成报告。

读懂报告：一次分析同时抓到两类 504

生成的报告将所有问题归在 Errors & Exceptions 下，对于这台服务器，一次就浮现出两个截然不同的 HTTP 504 问题。

仔细读这两条一句话摘要——它们描述的是两种真正不同的失败模式：

第一个 504 耗时 3.19 秒，因为地址 133.91.43.213:80 的上游服务器在收到当前服务器的 ACK 后，延迟发送了一个 PSH+ACK 包。
第二个 504 发生的原因是上游根本没有回任何包——当前服务器等了一段时间后放弃并主动关闭了连接。

区分这两种情况的诀窍很简单，而这也是整个分析中最有价值的一个观念：看连接里最慢的那个包，问一句是当前服务器收到的还是发出的。 下面两个案例分别演示这两种结局。

案例一：延迟发生在上游发来的包上

展开第一个 504，XRay 会把这条问题 TCP 连接上的每一个包按顺序画出来，并标出每个包与前一个包之间的时间间隔。

这张图一眼就能读懂。横轴是包的序号（1、2、3……）；纵轴是每个包与前一个包之间的延迟；方块代表当前服务器发出的包（egress），圆圈代表当前服务器接收到的包（ingress）。几乎所有间隔都贴在 0 附近——只有一个圆圈，也就是 PSH+ACK 包，一下跳到 3 秒以上。悬浮上去可以看到具体数字和方向。

这个尖峰是个圆圈，也就是当前服务器正在等待从上游收到的包。换句话说，当前服务器按时完成了自己的工作，然后干等了 3 秒等上游回话。XRay 直接给出了结论和三个候选根因——上游服务器慢、两者之间的网络链路慢、或代理侧的超时设置太短——更重要的是，它把这三条落成了具体可执行的检查项。

案例二：延迟发生在当前服务器发出的包上

第二个 504 在报告里的表述类似，但包时序图恰好是镜像的。

这一次最慢的包是方块，带的是 FIN+ACK 标志。方块说明是当前服务器发出的，FIN+ACK 说明它关闭了连接。所以故事完全不同了：上游一个包也没发，当前服务器触发了自己的超时保护，放弃等待并主动把连接拆掉。

这就是整套诊断方法的一句话总结：对于同一个 504，最慢的包如果是收到的，说明还在等上游；最慢的包如果是发出的 FIN+ACK，则是本机的超时保护先触发、主动关闭了连接。 两者最终都指向同样的三个根因，但知道是哪一侧先卡住，能告诉你首先该往哪里看。

OpenResty XRay 只在应用层对导致 504 错误的 TCP 连接抓包，因此性能损耗极低。这非常适合对性能和延时有极高要求的生产环境。这就是我们强大的智能抓包技术。

全自动分析与报告

上面的引导式分析是发生故障时你要用的工具。在日常运行中，Insights 页面会自动执行同样的分析，并以日报和周报的形式发布结果。

同样的两个 504 问题在这里自动出现——你不需要主动发起分析就能看到。引导式分析适合正在发生的故障排查和逐案深入讲解；Insights 则确保这类反复出现的问题在日常运维中不会被遗漏。

通过 OpenResty XRay 产品提升您应用的性能

如果您喜欢这个教程，请订阅这个博客网站和我们的 YouTube 频道或 B 站频道。谢谢！

关于 OpenResty XRay

OpenResty XRay 是一个动态追踪产品，它可以自动分析运行中的应用程序，以解决性能问题、行为问题和安全漏洞，并提供可行的建议。在底层实现上，OpenResty XRay 由我们的 Y 语言驱动，可以在不同环境下支持多种不同的运行时，如 Stap+、eBPF+、GDB 和 ODB。

立即申请 OpenResty XRay 试用

关于作者

章亦春是开源 OpenResty^® 项目创始人兼 OpenResty Inc. 公司 CEO 和创始人。

章亦春（Github ID: agentzh），生于中国江苏，现定居美国湾区。他是中国早期开源技术和文化的倡导者和领军人物，曾供职于多家国际知名的高科技企业，如 Cloudflare、雅虎、阿里巴巴, 是 “边缘计算“、”动态追踪 “和 “机器编程 “的先驱，拥有超过 22 年的编程及 16 年的开源经验。作为拥有超过 4000 万全球域名用户的开源项目的领导者。他基于其 OpenResty^® 开源项目打造的高科技企业 OpenResty Inc. 位于美国硅谷中心。其主打的两个产品 OpenResty XRay（利用动态追踪技术的非侵入式的故障剖析和排除工具）和 OpenResty Edge（最适合微服务和分布式流量的全能型网关软件），广受全球众多上市及大型企业青睐。在 OpenResty 以外，章亦春为多个开源项目贡献了累计超过百万行代码，其中包括，Linux 内核、Nginx、LuaJIT、GDB、SystemTap、LLVM、Perl 等，并编写过 60 多个开源软件库。