John Wick

除錯一個 Python 網路伺服器，它會默默停止回應 — 這是 threads=0 設定錯誤，以及如何透過適當驗證來捕捉此問題。

為什麼我的 Waitress 伺服器在 threads=0 時會掛起？

一個伺服器乾淨地啟動、沒有異常記錄，然後就再也不回應任何請求，這是最令人沮喪的 bug 之一 — 沒有 traceback 可供搜尋，也沒有例外狀況可供 Google。如果你遇到 Waitress 支援的 Flask 應用程式發生這種情況，一個特定的錯誤設定很常見：將 threads 設為 0。

目錄

  1. 症狀
  2. 為什麼 threads=0 會破壞一切
  3. 這個值通常從哪裡來
  4. 為什麼它不會自行引發錯誤
  5. StayPresent 如何事先驗證此問題
  6. 其他值得檢查的無效值
  7. 完整範例
  8. 常見問題
  9. 結論

症狀

你啟動伺服器，程序保持運作，記錄看起來完全正常，但每個傳入的請求都會掛起 — 沒有回應、沒有逾時訊息，什麼都沒有。託管平台上的健康檢查最終會將部署標記為不健康，但沒有明顯的錯誤指出原因。

為什麼 threads=0 會破壞一切

Waitress 使用可設定的 worker 執行緒數量來實際處理傳入的請求 — 這就是 threads 參數。當 threads=0 時，字面上來說，沒有任何 worker 可以接收任何傳入的連線。伺服器 socket 是開啟且正在監聽的，所以從外部看起來是存活的，但沒有任何東西可以實際處理請求。這會產生上述的症狀：伺服器看起來正常運作，但從不回應任何請求。

這個值通常從哪裡來

這很少是故意的。常見的實際原因：

  • 從環境變數讀取的設定值未設定或為空，靜默轉換為 0（int(os.getenv("THREADS", 0))，其中 THREADS 從未真正設定）。
  • 設定檔中的拼寫錯誤或複製貼上錯誤。
  • 動態計算（例如 threads = cpu_count() // 4）在 CPU 分配有限的小型容器中會四捨五入為零。

為什麼它不會自行引發錯誤

這是真正危險的部分：將 threads=0 傳遞給 Waitress 不會在啟動時引發例外。伺服器啟動、綁定埠，並且從程序監控的角度看起來完全健康 — 只有當你實際嘗試發送請求時，問題才會變得明顯，即使那時，失敗模式是掛起，而不是指向原因的明確錯誤訊息。

StayPresent 如何事先驗證此問題

StayPresent 會在呼叫 run() 時立即驗證 threads，拒絕任何小於 1 的值，並在伺服器啟動前拋出明確的 ValueError：

staypresent.run(
    "bot.py",
    threads=0,
)
# ValueError: threads must be at least 1

Enter fullscreen mode Exit fullscreen mode

這將靜默且難以診斷的掛起轉換為立即且明顯的啟動失敗 — 這是一個更好的除錯體驗，因為錯誤會直接指向實際的錯誤設定值，而不是讓你猜測為什麼請求會掛起。

staypresent.run(
    "bot.py",
    threads=8,   # valid
)

Enter fullscreen mode Exit fullscreen mode

其他值得檢查的無效值

threads=0 是這類 bug 最極端的版本，但如果部署以類似的靜默方式出現問題，有幾個其他參數值得仔細檢查：

  • port — 必須介於 0 和 65535 之間；超出範圍的值（例如拼寫錯誤如 80800）會立即驗證，而不是在 socket 綁定程式碼深處以混淆的錯誤失敗。
  • max_restarts、restart_delay、restart_reset_after — 必須為 >= 0；負值會被立即拒絕，而不是產生未定義的重啟迴圈行為。

所有這些都會在伺服器啟動前驗證，特別是為了讓拼寫錯誤的設定值以明確的錯誤訊息呈現，而不是靜默且令人困惑的執行期行為。

完整範例 

import os
import staypresent

staypresent.web.json({"status": "running"})

# threads read from env with a SAFE fallback, not one that can silently become 0
threads = int(os.getenv("SERVER_THREADS", "4")) or 4

staypresent.run(
    "bot.py",
    port=int(os.getenv("PORT", 8080)),
    threads=threads,
)

Enter fullscreen mode Exit fullscreen mode

這裡的 or 4 防護機制特別保護 SERVER_THREADS 被設定為字串 "0" 的情況，否則會直接通過成為 StayPresent 會在啟動時（正確地）拒絕的無效值 — 最好在你自己的設定邏輯中使用合理的後備值來捕捉它，而不是僅依賴啟動驗證。

常見問題

threads=1 是否有相同的問題？
沒有 — threads=1 是有效且可運作的，只是限制一次只能處理一個請求。只有 0（或負值）會導致上述的掛起。

這是 Waitress 特有的，還是 Flask 的開發伺服器也有相同的問題？
這個特定的失敗模式與 Waitress 的 worker 執行緒池有關；Flask 的開發伺服器有不同的（通常與生產環境較不相關）執行緒模型。

StayPresent 是否即使在 production=False 時也會驗證此問題？
是的 — threads 無論 Waitress 或 Flask 的開發伺服器最終是否實際執行都會被驗證，因為該值會在做出該決定之前進行檢查。如果它無法生效（開發伺服器後備），則會針對該不匹配另行記錄警告。

結論

threads=0 是一個安靜且容易引入的設定錯誤，會產生最令人困惑的症狀之一：伺服器看起來正常運作但從不回應。StayPresent 的預先參數驗證將此轉換為立即且明確的啟動錯誤，而不是你必須從外部向內除錯的靜默掛起。

pip install staypresent[prod]

Enter fullscreen mode Exit fullscreen mode