在使用 RunCloud 管理 WordPress 或其他 PHP 應用的伺服器時，Nginx 502 Bad Gateway 及 504 Gateway Timeout 錯誤是最常見的故障之一，這兩種錯誤通常與 Nginx、PHP-FPM 服務異常或後端連線逾時有關。
本教學將以實際指令與步驟，詳細說明在 RunCloud 環境下如何系統性排查 RunCloud Nginx 502 錯誤 及 504 Gateway Timeout，確保伺服器穩定運行。
初步判斷 — 何謂 Nginx 502 與 504 Gateway Timeout 錯誤？
這類錯誤通常出現在使用者透過瀏覽器要求網站時：
- 502 Bad Gateway：Nginx 作為反向代理，未能正確取得 PHP-FPM 的處理結果，可能為 PHP-FPM 已當機或連線數暴增。
- 504 Gateway Timeout：Nginx 請求 PHP-FPM 或上游伺服器逾時未獲得回應，可能 PHP 腳本過慢、服務當機等。
Step-by-Step 排查流程
1. 檢查 Nginx 設定是否有誤（nginx-rc -t）
RunCloud 使用獨立的 nginx-rc 指令管理服務。執行以下指令可列出所有 Nginx 設定，並檢查語法是否錯誤。
sudo nginx-rc -t如果出現語法錯誤、未載入重要設定（如 fastcgi_pass 設定錯誤），請立即更正。有誤時會出現類似 invalid directive 或 unknown directive 等訊息。
2. 檢查 Nginx 與 PHP-FPM 服務狀態（systemctl status）
確保 Nginx 及 PHP-FPM 服務都已啟動且無異常：
sudo systemctl status nginx-rcsudo systemctl status phpXX-fpm（請依實際 PHP 版本調整 phpXX-fpm，例如：php81-fpm）
如果服務顯示為 inactive、failed，則說明服務當機，此時需嘗試重啟對應服務：
sudo systemctl restart php81-fpmsudo systemctl restart nginx-rc3. 查閱錯誤日誌把握關鍵（journalctl、tail）
- 篩選當機紀錄、異常錯誤訊息：
sudo journalctl -u nginx-rc --since "1 hour ago" --no-pagersudo journalctl -u php81-fpm --since "1 hour ago" --no-pager亦可直接檢查 Nginx、PHP 錯誤日誌：
sudo tail -n 50 /var/log/nginx-rc/error.logsudo tail -n 50 /var/log/php81-fpm.log根據錯誤訊息（如 upstream prematurely closed connection、connection refused 等）判斷是 PHP-FPM 當機、資源耗盡還是程式 bug。
4. 確認 PHP-FPM 是否卡住／崩潰（php-fpm 當機排查）
- 觀察 PHP-FPM 活躍進程數及占用情況：
ps aux | grep php-fpm- 查看 port 是否被正確監聽 (以
ss檢查)：
sudo ss -ltnp | grep php-fpm- 檢查大量進程是否因無法釋放、
pm.max_children達上限，這會造成伺服器吞吐降低，以及 502/504 問題（但本教學不深入 pm.max_children 調整，僅以日誌觀察為主）。
遇到進程暴增、持續僵死請立即嘗試重啟 PHP-FPM，並確認網站是否恢復。
5. 模擬前端請求檢查（curl）
使用 curl 指令直接從伺服器測試網站主頁，可確認是全站 502/504，還是部分網頁受影響：
curl -I http://localhost若仍回應 502/504，表示 Nginx 或 PHP-FPM 問題還未解決；若為 200 OK，則可能是 CDN 或外部網路問題。
排錯建議
- 若是 Nginx 或 PHP-FPM 未啟動，請根據 systemctl 錯誤訊息修正設定，再重新啟動。
- 若 nginx-rc -T 出現設定錯誤，請回溯最近更動的 Config。
- 若日誌顯示資源不足（如 Out of memory, Max children reached），可先重啟服務解除卡死，再分析背後原因（如流量暴增、程式導致 Memory Leak 等）。
- 因 504 Gateway Timeout 常見為 PHP 腳本異常或死迴圈，也建議檢查 /var/log/php81-fpm.log 搜尋 Timeout 關鍵字。
常見問題與排除 FAQ
- Q1. 重啟服務後仍然 502/504，怎麼辦？
- 請再次檢查 Nginx 與 PHP-FPM 設定是否相符，例如 fastcgi_pass 指向的 socket/port 是否正確，必要時可嘗試重新部署應用設定。
- Q2. 日誌出現 connection refused？
- 代表 PHP-FPM 服務沒啟動或 Listen 位置不符。請於 nginx-rc 與 PHP-FPM 設定比對。
- Q3. 經常性 504 Gateway Timeout？
- 請檢查 PHP 腳本執行效能、延伸模組、資料庫連線狀態，並考慮查閱 slowlog。
結語
502 Bad Gateway 與 504 Gateway Timeout 是 RunCloud 與 Nginx 伺服器最常見的前端錯誤，只要謹記以上排查步驟，結合 nginx-rc -T、systemctl、journalctl、tail、curl、ss 等強力指令，即可迅速定位問題來源，大幅提升服務穩定性。有相關主機管理經驗問題，歡迎在下方留言討論。
Photo by Scott Rodgerson on Unsplash