疑難排解

執行 Saba-chan 時會遇到的常見問題,以及以程式碼實際行為為依據的解決步驟。

疑難排解

本文件依使用者實際遇到的症狀整理,說明 常駐程式程式碼的行為方式 以及修正步驟。指令範例與路徑以 Windows 為準。在 Linux 上,資料資料夾是 ~/.config/saba-chan。


1. 常駐程式無法啟動 / GUI 無法連線

1.1 連接埠衝突 / 常駐程式已在執行

常駐程式(saba-core)預設監聽連接埠 57474,且只監聽 127.0.0.1。

  • 每台電腦只會執行一個常駐程式。若已有常駐程式在執行,新啟動的常駐程式會立即結束,GUI 與 CLI 則會連線到正在執行的那個。
  • 若有其他程式佔用該連接埠,常駐程式會以 2 秒間隔重試 10 次,然後結束。
# Windows:查看是誰在使用
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
  • 你可以在 http://127.0.0.1:57474/health 不帶權杖確認常駐程式是否存活。saba-chan-cli daemon status 也會顯示相同資訊。
  • 若有無回應的常駐程式殘留,請用 saba-chan-cli daemon stop 停止它。若仍無法結束,請執行 Stop-Process -Name saba-core -Force。
  • 若需要變更連接埠,請編輯 config.json 中的 gui.ipcPort 並重新啟動。或設定 SABA_IPC_PORT=57480 之類的環境變數。

1.2 IPC 權杖不符

常駐程式每次啟動都會建立新的 .ipc_token。認證失敗(401)時,GUI 與 CLI 會重新讀取權杖檔案並重試一次,因此通常會自行修復。

若「認證失敗」持續重複:

  • 確認 GUI 與常駐程式看的是同一個資料資料夾。若只為其中一方設定了 SABA_DATA_DIR 或 SABA_TOKEN_PATH,權杖檔案的位置就會不同。
  • 完全結束 GUI 後再重新啟動。

2. 伺服器啟動/停止行為異常

2.1 按下停止後很久都沒有反應

這可能是正常的。常駐程式依下列順序處理:

  1. 對於有主控台的伺服器,會將模組的 stop_command 送到主控台(stdin)。對於 Palworld 等沒有主控台的遊戲,模組會透過 REST 要求伺服器存檔並關閉。
  2. 等待伺服器自行結束。預設為 30 秒;模組可以用 module.toml 的 [config] stop_timeout 變更,使用者也可以在伺服器畫面 Saba-chan 分頁的 停止等待時間 中依各伺服器變更。若世界很大、儲存要花很久,請調高。
  3. 若仍存活,就會被強制終止。
  4. 停止後的 30 秒 內會暫停當機偵測。

若每次最後都被強制終止,表示伺服器沒有收到停止指令。請確認停止指令是否出現在伺服器主控台中。範例:Minecraft stop、Zomboid quit。

2.2 伺服器一直重新啟動

伺服器結束時,常駐程式會將原因分類為 手動停止 / 遊戲內停止 / 當機 / 原因不明。預設 只有當機時 才會自動重新啟動;等待時間從 5 秒開始,每次加倍,10 分鐘內重新啟動超過 3 次就會停止重新啟動。

解決方法:

  • 在伺服器畫面的「最近的結束紀錄」中確認分類。
  • 若要停止重新啟動,請在伺服器畫面 Saba-chan 分頁的「自動重新啟動」中關閉「當機後重新啟動」。若你開啟了「原因不明時也重新啟動」,也請一併確認。
  • 檢查伺服器主控台記錄(instances\<id>\logs\)找出當機原因。若是 Java OOM(OutOfMemoryError),請增加記憶體設定。

2.3 啟動時出現「連接埠衝突」錯誤

啟動前檢查發現伺服器的連接埠正被其他執行中的實例或其他程式使用。通常是先前的程序仍殘留,或另一個遊戲伺服器使用了相同的連接埠。

  • 找出使用該連接埠的程序並停止它。
  • 若無法這麼做,請在實例設定中變更連接埠後再啟動。
  • 你可以用 GUI 設定中的「連接埠衝突偵測」(gui.portConflictCheck)關閉檢查本身,但不建議。

2.4 「需要同意條款」(Minecraft EULA 等)

對於模組宣告了條款的遊戲(例如 Minecraft EULA),你必須閱讀並同意條款後伺服器才能啟動。在同意之前,啟動會以 agreement_required 被封鎖。

  • 在 GUI 中啟動伺服器時,請在出現的對話框中閱讀條款、勾選核取方塊,然後啟動。
  • 無法從 Discord 同意條款。在你電腦上的 Saba-chan 同意後,就也能從 Discord 啟動伺服器。

2.5 伺服器設定儲存被拒絕

  • unknown_setting:該鍵既不是通用實例欄位,也不是模組宣告的設定。可能是打錯字或其他遊戲的設定。
  • validation_failed / invalid_format:值的範圍或格式與模組的宣告不符。請修正錯誤中顯示的欄位。
  • 「設定已儲存,但無法更新遊戲的設定檔」:設定已儲存,但模組無法編輯遊戲的設定檔。請確認遊戲檔案沒有被其他程式鎖定,然後再儲存一次。

2.6 未驗證的元件無法執行

不是從官方目錄安裝的模組與擴充功能,或安裝後檔案有變更的,會被標示為「未驗證」。Saba-chan 不會以防毒軟體掃描它們。在 Windows 上以 AppContainer、在 Linux 上以 bubblewrap 隔離執行;在無法隔離的環境(沒有 bubblewrap 或無法使用它的 Linux,以及 macOS),只有在你對其目前檔案表示同意後才會執行。若執行被封鎖,會顯示下列代碼之一。

代碼意義修正方式
launch_outside_instance模組嘗試執行伺服器資料夾外的程式確認該模組的來源
sandbox_unavailable無法在這台電腦上準備隔離環境見下方說明

遇到 sandbox_unavailable 時,GUI 會詢問「不隔離直接執行?」。只對你信任的元件 允許。若允許,該元件就能以你帳號的權限存取所有檔案與網路。只能在這台電腦上同意,且若元件的檔案變更就會再次詢問。你可以在 設定 → 安全性 →「不隔離執行」中撤回同意。

最確實的修正方式是從官方目錄重新安裝該模組或擴充功能。已驗證的元件會略過這些檢查。


3. 安裝 / 更新問題

3.1 安裝中途失敗

  • 安裝程式停止時,錯誤畫面會顯示原因代碼(fetch_failed、download_failed、extract_failed、elevation_failed、installer_outdated)與記錄路徑。記錄會寫入 %TEMP%\saba-chan-installer.log。
  • installer_outdated 表示安裝程式比最新發行版舊。請下載並執行最新的安裝程式。
  • 若是網路問題,請檢查連線,然後按下 重試 或再次執行安裝程式。
  • 準備 Python 執行環境時失敗不會中止安裝。常駐程式會在第一次啟動時再次準備,重新執行安裝程式也會刪除損毀的執行環境並重新下載。

3.2 伺服器安裝進度不顯示或卡住(給模組開發者)

伺服器安裝進度可在 GET /api/provision-progress/:name 取得。

  • 確認模組/擴充功能以 PROGRESS:{json} 格式將進度輸出到 stderr。
  • 確認 JSON 有效(message 中的雙引號與換行要跳脫)。
  • 成功的進度會在完成 5 秒後被移除,因此太晚輪詢會發現已經是空的。失敗的進度會保留到使用者關閉為止,若是新建立的伺服器,關閉時會刪除該實例。

3.3 更新沒有套用

更新會以 Saba-chan 中繼提供的已簽章發行版資訊進行確認,套用前會驗證每個檔案的雜湊。若簽章或雜湊不符,就不會套用任何內容。

  • 若更新後看到部分項目無法更新的通知,點擊它即可查看哪些項目失敗。
  • 在 GUI 設定中再次檢查更新並套用。
  • 替換常駐程式、GUI 或安裝程式本身的更新,會在常駐程式結束後由安裝程式(saba-chan-installer)套用。套用期間請不要重新啟動 Saba-chan。
  • 若仍無效,請結束 Saba-chan,清空 updates\ 資料夾後再試一次。

4. Discord 機器人 / 雲端配對

4.1 機器人沒有回應

  • 依序輸入前綴(預設 Saba-chan)、空格,再接伺服器名稱與指令。範例:Saba-chan minecraft status。
  • 必須在 GUI 中完成配對,使 .node_token 被儲存。
  • Saba-chan(常駐程式)必須正在執行。機器人在雲端執行,但指令是由這台電腦上的常駐程式執行。
  • 若常駐程式無法連線到中繼伺服器,請在 GUI 的 設定 → 疑難排解 →「診斷資訊」中查看最近的警告。若看到「older than relay minimum」,請更新 Saba-chan。
  • 確認官方機器人已被邀請到你的 Discord 伺服器且沒有在睡眠。若在睡眠,請用 /saba wake 喚醒它。

4.2 配對代碼「已過期」

配對代碼只在 5 分鐘內有效。請從 GUI 發行新的代碼。

4.3 中繼連線被以 401 拒絕

錯誤原因修正方式
TOKEN_REPLACED在其他地方配對時用 重新連接 選了這台電腦,取代了這台電腦的權杖若要繼續使用這台電腦,請再次配對
INVALID_TOKEN / NODE_NOT_FOUND.node_token 錯誤或已在伺服器端被移除再次配對(會使既有權杖失效)
MISSING_TOKEN / INVALID_TOKEN_FORMAT權杖檔案遺失或格式錯誤再次配對

4.4 音樂指令無法運作

  • 在 GUI 的 Discord 頁面中,確認該 Discord 伺服器的設定已啟用音樂。
  • 下指令的人必須已在 Discord 語音頻道中。若機器人無法加入語音頻道,請檢查機器人的頻道權限。
  • 播放由官方音樂伺服器處理,因此你的電腦上不需要 ffmpeg 或 yt-dlp。

4.5 連不上遠端常駐程式

顯示內容處理方法
那台電腦未開放遠端連線在伺服器電腦的設定 → 連線 → 遠端常駐程式中開啟允許遠端連線目前是關閉的。開啟並儲存
無法連到遠端常駐程式確認伺服器電腦和它的 Saba-chan 已開啟並聯網。無法直接存取時會經由 Saba-chan 雲連線,所以連接埠轉發不是必需的
本機沒有連接 Discord用同一個 Discord 帳號為兩台電腦配對
遠端常駐程式不再接受本機伺服器電腦斷開了連線。請在你的電腦上重新點 連線
連接埠已被使用其他程式在使用同一連接埠。請更換連接埠
這只能在那台電腦上直接操作更新、自動啟動等操作無法遠端進行

4.6 Saba-chan 網頁連結打不開

  • 連結只能開啟一次,且須在 5 分鐘內。用 /saba web 獲取新連結。
  • 出現 無法連線到你的電腦 時,確認電腦上的 Saba-chan 正在執行且是最新版本。
  • 在沒有電腦的情況下開啟的連結中,伺服器、模組、電腦選單是鎖定的。請安裝應用程式並執行 /saba connect 後,再取得新連結。
  • 關閉分頁或重新整理會結束工作階段。這是正常行為。

5. 資料 / 設定復原

5.1 config.json 損毀

  • 常駐程式會將損毀的 config.json 移到一旁成為 config.json.corrupt-<timestamp>,並自動從 config.json.bak(最後一份正常的副本)復原。
  • 若 .bak 也遺失或損毀,就會以預設值啟動。包括 Discord 整合設定在內的所有設定都會被重設,請參考被移走的 .corrupt- 檔案,在 GUI 中重新輸入你需要的值。
  • 伺服器清單(instances\)與 .node_token 與 config.json 是分開的,因此會被保留。

5.2 完全重設

1. 結束 Saba-chan GUI、CLI 與常駐程式
2. 備份並刪除整個 %APPDATA%\saba-chan 資料夾
3. 啟動 Saba-chan → 以預設值重建

注意:若你將伺服器安裝在預設位置,遊戲伺服器檔案與備份都位於 %APPDATA%\saba-chan\instances\ 中,會被一起刪除。只有在你選擇此資料夾以外的伺服器資料夾時,遊戲檔案才會保留下來。


6. 記錄在哪裡?

位置內容
%APPDATA%\saba-chan\logs\saba-chan-*.logGUI 記錄。也包含由 GUI 啟動之常駐程式的輸出
GUI 常駐程式主控台視窗常駐程式記錄(記憶體緩衝區,最近 10,000 行)
GUI 設定 → 疑難排解 → 診斷資訊常駐程式狀態與最近的警告/錯誤。不包含密碼或權杖
%APPDATA%\saba-chan\instances\<id>\logs\伺服器主控台記錄(console.log、sessions\)
GUI 主控台分頁各實例的遊戲伺服器輸出
%APPDATA%\saba-chan\audit.log伺服器啟動/停止/指令的紀錄(含來源,機密已遮蔽)
%TEMP%\saba-chan-installer.log安裝程式記錄

直接執行常駐程式時,可以用 RUST_LOG 環境變數變更常駐程式的記錄等級(預設 info)。


7. 問題回報檢查清單

開新的 issue 前,請確認並附上以下內容。

  1. Saba-chan 版本(saba-chan-cli version,或 GUI 診斷資訊)。
  2. 重現步驟。
  3. 相關記錄(依時間戳記擷取的片段)。GUI 診斷資訊中「複製」的輸出也有幫助。
  4. 作業系統 / 組建(例如 Windows 10 x64 21H2)。
  5. 絕對不要附上權杖檔案(.ipc_token、.node_token)或其內容。

儲存庫: