12. 疑難排解

本章彙整 admin 在排查問題、或協助使用者排查問題時會用到的事實。內容大多回指前章（§11）已說明的設定；遇到語音品質的細節，請參照 §2.2。

12.1 語音連線排查（TURN / 防火牆 / NAT）

嚴格 NAT（VPN、企業網路）後的使用者連不上語音時，啟用內建 TURN 伺服器可以幫他們中繼。依據 TURN 分頁的說明：「運行 TURN 中繼伺服器，幫助在嚴格 NAT（VPN、企業網路）後的用戶連接語音頻道。」啟用方式見 §11.1。

防火牆與連接埠轉發是常見的卡點。請確保 UDP 與 TCP 的連接埠（預設 3478）都已在防火牆中開放；伺服器在路由器後方時，還要把這兩個埠轉發到伺服器。其中 TCP 是給 UDP 被封鎖之網路環境的備援。

排查時有一個關鍵要留意：「執行診斷」只是伺服器內部的自我檢測，診斷成功並不等於使用者一定連得上。依據按鈕下方的說明：「此為伺服器內部自我檢測，無法驗證外部連線是否暢通。請使用 VPN 或從外部網路實際測試語音連線，以確認 TURN 對真實用戶有效。」所以診斷通過後，請務必再用 VPN 或從外部網路實際測一次語音連線，才能確認 TURN 對真實使用者有效。

另外，如果這座伺服器是以環境變數 TURN_URL 指向外部 TURN，內建 TURN 會停用，TURN 分頁最上方也會出現對應提示；要改用內建功能，需要先移除 TURN_URL。

語音品質本身（例如音質與頻寬的取捨）屬於各頻道的語音設定，詳見 §2.2，本章不重複展開。

12.2 伺服器更新失敗排查

更新的自動驗證（SHA256）沒過，不一定代表檔案壞了。可能只是網路暫時的問題，或雜湊清單還沒上傳。這時可以前往 GitHub Release 頁面手動比對雜湊，若與該頁的雜湊相符，就選擇略過驗證並套用。對應的操作路徑見 §11.5。

跑在容器（Docker）中的伺服器，以拉取新版、重建容器的方式更新，原有資料會保留不會遺失。對應指令是：

docker compose pull && docker compose up -d

更新失敗時，admin 可能會看到下列其中一條提示，依字面就能判斷該往哪查：

• 「磁碟空間不足（需要 …，可用 …）。」——清出磁碟空間後再試，孤兒檔案掃描（§11.4）也可釋放一些空間。
• 「下載停滯——已 60 秒無資料傳輸，請重試。」——多半是網路中斷，重試即可。
• 「下載超過 30 分鐘逾時上限。」——同樣偏向網路問題，待網路穩定後重試。
• 「檢查更新失敗。」與「下載更新失敗。」——先確認伺服器對外網路是否暢通，再重試。伺服器的對外連線受防火牆限制時，也確認下方的網域都已放行。

檢查與下載更新時，伺服器會連到 HakoSpace 的軟體發佈來源，那裡無法使用時改連 GitHub（§11.5）。如果伺服器所在的網路只允許連往特定網域，請放行伺服器以 HTTPS（443 埠）連往下列網域：

• dl.hakospace.com
• api.github.com、github.com
• *.githubusercontent.com（從 GitHub 下載檔案時會轉到這個網域底下）

套用更新前，確認畫面會提醒「將中斷所有使用者連線並重啟伺服器，是否繼續？」請挑使用者較少的低峰時段操作。

以 systemd 服務執行的伺服器，如果套用更新之後一直沒有回來，請確認服務設定用的是 Restart=always（見《速架設指南》§4.5）：套用更新時，伺服器換好新的執行檔後會自行結束，要由 systemd 把新版本啟動起來，Restart=on-failure 在這種情況不會重新啟動。改好服務設定後，重新載入設定並啟動服務（例如 sudo systemctl daemon-reload、sudo systemctl start hakospace），就會跑起已經換好的新版本。

12.3 使用者回報連線中斷

使用者連線中斷時，他們的畫面會出現「連線中斷，重新連線中…」，並附一句「連線恢復後會自動重新連接，無須手動操作，請稍候。」連線恢復後則顯示「已重新連線」。

這裡有一個重要的 admin 認知：這段文案是刻意寫得中性的，因為連不上的原因很多，也可能是使用者自己那端的網路。所以使用者看到「連線中斷，重新連線中…」時，未必是伺服器故障；可以先請使用者排查自身的網路，多數情況稍候就會自動重新連上。

「無法連線至 HakoSpace 伺服器」（或「無法連線至 HakoSpace 伺服器,請稍後再試。」）則是另一回事：這兩句只會出現在設定面板「總覽」分頁的「HakoSpace 改善計畫」區塊，說的是這座伺服器能不能連到 HakoSpace，跟成員能不能連上這座伺服器無關，見 §1.1。