排查 Nginx 502 Bad Gateway 的系統方法

在 Linux 伺服器管理中，502 Bad Gateway 是 Nginx 最常見的錯誤之一。當使用者看到這個錯誤時，代表 Nginx 作為反向代理伺服器，成功接收了客戶端的請求，但在嘗試將請求轉發給後端應用程式伺服器（如 PHP-FPM、Node.js 或 Gunicorn）時，卻收到了無效的回應。

對於中階 Linux 使用者而言，盲目重啟服務往往無法解決根本問題。本文將引導你透過系統層面的邏輯排查，快速定位並修復此問題。

第一步：確認後端服務狀態

502 錯誤的核心在於「後端掛了」或「後端無回應」。首先，我們必須確認你的應用程序是否正在運行。假設你使用的是 PHP-FPM，請檢查其服務狀態：

systemctl status php8.1-fpm

如果服務顯示 inactive (dead) 或 failed，請嘗試啟動它：

sudo systemctl start php8.1-fpm
sudo systemctl enable php8.1-fpm

若服務正在運行但狀態異常，請檢查其日誌以獲取更多細節：

journalctl -u php8.1-fpm -n 50 --no-pager

第二步：檢查 Nginx 錯誤日誌

Nginx 的錯誤日誌（通常位於 /var/log/nginx/error.log）是排查 502 錯誤的第一手資料。當 502 發生時，日誌中通常會包含具體的失敗原因，例如「Connection refused」或「No live upstreams」。

使用 tail 命令即時監控日誌變化，然後刷新你的網頁觸發錯誤：

sudo tail -f /var/log/nginx/error.log

常見的关键訊息包括：

connect() failed (111: Connection refused)：後端服務未監聽在指定端口，或服務未啟動。
upstream prematurely closed connection：後端服務崩潰或處理超時。

第三步：驗證 Socket 或端口連接

Nginx 與後端通訊通常透過 Unix Socket 或 TCP 端口。以 PHP-FPM 為例，預設使用 Socket 檔案。請確認 Nginx 配置中的 fastcgi_pass 路徑與 PHP-FPM 產生的 Socket 路徑一致。

檢查 PHP-FPM 是否生成了 Socket 檔案：

ls -l /run/php/php8.1-fpm.sock

如果檔案不存在，可能是權限問題或 PHP-FPM 配置錯誤。若使用 TCP 端口（如 127.0.0.1:9000），則需確認該端口是否被監聽：

ss -tlnp | grep 9000

若無輸出，表示後端未監聽該端口。

第四步：檢查權限與 SELinux/AppArmor

即使服務運行正常，權限問題也會導致 Nginx 無法讀取後端 Socket 或訪問資源。確保 Nginx 使用者（通常是 www-data）對相關目錄和檔案擁有讀取權限。

對於 Ubuntu/Debian 系統，SELinux 預設關閉，但 AppArmor 可能限制 Nginx 的權限。檢查 AppArmor 日誌：

sudo dmesg | grep -i apparmor

若發現拒絕記錄，可能需要調整 AppArmor 配置或使用 aa-complain 模式進行測試。

常見問題

1. 後端服務記憶體不足而崩潰

當後端應用程式（如 Node.js 或 Python 應用）記憶體泄漏時，Linux OOM Killer 可能會終止該進程，導致 Nginx 收到 502。檢查系統日誌：

sudo dmesg | grep -i "out of memory"

若發現 OOM 事件，需優化應用程式記憶體使用或增加伺服器 RAM。

2. 配置錯誤導致無效上游

在 Nginx 配置中，若 upstream 區塊定義錯誤，或 server 指令指向不存在的後端，也會引發 502。檢查 Nginx 配置語法：

sudo nginx -t

若出現 invalid host in upstream 或 no live upstreams，請修正 nginx.conf 或對應的 site 配置文件。

小結

排查 Nginx 502 Bad Gateway 錯誤，關鍵在於理解其本質是「代理伺服器與後端通訊失敗」。透過檢查後端服務狀態、分析 Nginx 錯誤日誌、驗證連接方式以及確認系統權限，大多數 502 問題都能被快速解決。記住，系統日誌永遠是可靠的線索，善用 journalctl 和 dmesg 將助你成為更高效的 Linux 管理員。