← 返回

如何使用 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 多個開源軟體庫。