開始使用

Saba-chan 的安裝、設定與運作指南,涵蓋執行架構與運作行為。

開始使用

本文件說明 Saba-chan 的基本安裝、設定與建立伺服器的步驟。遠端整合與問題排除請參考 Discord 機器人 與 疑難排解 文件。


1. 下載與安裝

系統需求:Windows 10 或 11(64 位元)、Microsoft Edge WebView2 Runtime(Windows 11 與較新的 Windows 10 已內建),以及網際網路連線。也可以在沒有螢幕的 Linux(x86_64)上安裝常駐程式和 CLI(見下方 1.1)。macOS(Apple 晶片)請在首頁下載 .dmg,並把應用程式拖到「應用程式」資料夾。本應用程式未經 Apple 公證,首次開啟被阻擋時,請到「系統設定」>「隱私權與安全性」允許開啟。

  1. 從網站上的下載按鈕或 GitHub Releases 下載安裝程式 saba-chan-installer.exe。
  2. 執行安裝程式,選擇安裝位置、要先安裝的遊戲模組以及捷徑選項,然後按下 安裝。
    • 預設安裝位置為 C:\Program Files\Saba-chan。若選擇的資料夾中已有其他檔案,安裝程式會在其中建立 Saba-chan 資料夾。
    • 遊戲模組也可以之後在應用程式中新增。
  3. 安裝程式會設定下列元件。視網路連線狀況,可能需要幾分鐘。
    • 確認最新的已簽章發行版,然後下載並部署常駐程式、GUI、CLI、語系等元件(每個檔案都會進行雜湊檢查)。安裝程式也會一併放在安裝資料夾中,供之後套用更新與解除安裝 Saba-chan 時使用
    • 安裝所選的遊戲模組及其所需的擴充功能(例如 SteamCMD)
    • 下載可攜式 Python 並建立 venv 環境(安裝在 Saba-chan 資料夾中,不會變更系統 PATH)
    • 將已安裝的元件版本記錄在 installed-manifest.json
  4. 安裝完成後,按下 啟動 Saba-chan 開啟 GUI。也可以從桌面或「開始」功能表的捷徑啟動。

設定、遊戲伺服器檔案、世界與備份都儲存在 %APPDATA%\saba-chan。刪除程式資料夾並不會移除你的伺服器資料。

重新安裝:若安裝中途失敗或檔案損毀,請再次執行安裝程式。它會重新下載程式檔案,並刪除損毀的 Python 執行環境後重新下載。你的設定與伺服器資料會保留。比目前發行版更舊的安裝程式會被封鎖,因此請務必下載最新的安裝程式。

1.1 Linux 伺服器

在沒有螢幕的 Linux(x86_64)上,不裝應用程式介面,只安裝常駐程式和 CLI。需要 curl、unzip、sha256sum、python3。

curl -fsSL https://raw.githubusercontent.com/WareAoba/saba-chan/main/install.sh | sh
  • 安裝程式會獲取最新的正式版本,用發行雜湊和已簽名的清單校驗檔案後安裝,建立 ~/.local/bin/saba-chan-cli,並以 systemd 使用者服務(saba-chan.service)啟動常駐程式。用 sh -s -- --dir <資料夾> --modules <模組…> 選擇安裝資料夾和模組。
  • 想在不登入的情況下開機啟動,執行一次 sudo loginctl enable-linger $USER。
  • 資料資料夾是 ~/.config/saba-chan。
  • Linux 伺服器通過 Windows 電腦上的應用程式以遠端常駐程式的方式管理。連線 Discord 和開啟遠端連線的方法見遠端常駐程式一章。

2. 認識 Saba-chan 的架構

下圖說明 Saba-chan 各元件的關係和通訊方式:

你的電腦
GUI 應用程式桌面應用程式 · 可選
CLI指令和互動式 Shell · 可選
Saba-chan 常駐程式 (saba-core)獨自負責伺服器、設定和 Discord 連線
遊戲伺服器由常駐程式啟動並看顧
模組每款遊戲的說明書 · Python
擴充功能額外功能 · Python
雲端
Discord 中繼Saba-chan 機器人 · 連接 Discord 和你的電腦
Discord用聊天下指令
遊戲伺服器在你的電腦上執行。與中繼往來的只有 Discord 指令和結果,以及伺服器清單、狀態等摘要,不會為遠端控制開放任何連接埠。
  • 常駐程式(saba-core.exe):執行 Saba-chan 所有功能的核心。它執行並管理伺服器程序、收集記錄,且只在本機位址 127.0.0.1:57474 提供 HTTP API。
  • GUI:呼叫常駐程式 API 的桌面應用程式。
  • CLI:呼叫常駐程式 API 的命令列工具。不帶參數執行時會開啟互動式 shell。
  • 執行器(saba-runner):附加在每個伺服器上的小型監看程序。即使常駐程式重新啟動,伺服器主控台與記錄也能保持連續。
  • 中繼伺服器:Discord 機器人運作所在的雲端服務。配對後,常駐程式會向外連線(長輪詢)以接收 Discord 管理指令,所有請求都透過 HTTPS 以配對時取得的節點權杖進行驗證。中繼伺服器只傳遞 Discord 指令、執行結果與伺服器摘要,不承載遊戲流量,因此加入遊戲的玩家所需的網路連線必須另外設定。

遊戲伺服器在你自己的電腦上執行。GUI 與 CLI 只向常駐程式發送請求,絕不會自行編輯檔案或啟動程序。

以「僅關閉介面」關閉視窗時,常駐程式與遊戲伺服器會繼續在背景運作。重新開啟 GUI 時,會重新連線到常駐程式,並接續既有的伺服器狀態與主控台記錄。若常駐程式重新啟動,它會重新連結仍在執行中的既有伺服器程序並繼續監控(因斷電或系統重新開機而終止的程序不會被還原)。若要停止個別遊戲伺服器,請在介面中按下 停止。


3. 建立第一個伺服器(使用 GUI)

第一次啟動 Saba-chan 時,伺服器清單是空的,「下一步」卡片會引導你安裝遊戲模組並建立第一個伺服器。若尚未安裝任何遊戲模組,請先在應用程式中的 Saba 儲存 安裝。接著依下列步驟建立伺服器:

  1. 新增伺服器:按下 新增伺服器 並選擇 作為新伺服器新增。若要連結你已在使用的伺服器資料夾,請改選 遷移現有伺服器。
  2. 選擇遊戲:從已安裝的遊戲模組中選擇一個(官方模組:Minecraft、Palworld、Project Zomboid 與 Terraria)。
  3. 設定伺服器:輸入伺服器名稱,並填寫模組要求的選項(例如 Minecraft 伺服器類型)與建議設定。連接埠(遊戲用來接受玩家連線的編號)會自動指派,不會與其他伺服器衝突。
  4. 同意條款:對於 Minecraft 等需要同意條款(EULA)的遊戲,你必須親自閱讀條款並勾選核取方塊,才能建立伺服器。Saba-chan 絕不會自動同意條款。
  5. 開始安裝:按下 新增伺服器 後,常駐程式會依下列順序執行設定作業:
    • 確認模組所需的擴充功能(例如 Palworld 與 Project Zomboid 需要 SteamCMD)。若所需的擴充功能已關閉,會提示你到「設定 → 擴充功能」中啟用。
    • 將實例資料儲存到 %APPDATA%\saba-chan\instances\<實例 ID>\ 資料夾
    • 執行 server.post_create 掛鉤
    • 將最新版本的遊戲伺服器檔案下載到實例資料夾的 server\ 目錄(Minecraft、Terraria 使用官方伺服器下載,Palworld 與 Project Zomboid 使用 SteamCMD)。進度會顯示在進度條上。
  6. 啟動:按下 啟動 後,常駐程式會檢查條款同意狀態並執行啟動前檢查,接著執行 server.pre_start 掛鉤,然後以模組的啟動命令(get_launch_command)啟動程序。伺服器主控台輸出會即時顯示在 GUI 主控台中。

所有遊戲指令都經由常駐程式,依 stdin(伺服器主控台)→ REST → RCON 的順序傳送。有主控台或 REST API(如 Palworld)的遊戲會在 RCON 關閉的狀態下執行。只有僅支援 RCON 的遊戲才會使用 RCON,連接埠與隨機密碼由常駐程式為每個執行個體指派,且只透過迴路位址(127.0.0.1)連線。


4. 運作中需要知道的行為

4.1 停止逾時

對於常駐程式直接管理的程序,當使用者按下 停止 時,常駐程式會依下列順序嘗試關閉。設定值定義於 src/supervisor/mod.rs。

  1. 正常停止:將模組的 stop_command(例如 Minecraft stop、Zomboid quit)送到伺服器主控台(stdin)。對於沒有主控台輸入的遊戲(Palworld),模組會透過 REST API 要求伺服器存檔並關閉。接著常駐程式會等待停止等待時間(伺服器 Saba-chan 分頁中設定的值;沒有時為 module.toml 的 [config].stop_timeout;再沒有時為 30 秒)。若超過逾時時間,常駐程式會強制終止程序,並再額外等待 2 秒。
  2. 強制終止:強制終止時,會立即終止整個程序樹,隨後最多等待 5 秒。
  3. 停止冷卻:停止後的 30 秒 內會暫停自動當機偵測。這樣可避免把正常關閉記錄為當機。

4.2 當機處理

伺服器結束時,常駐程式會將原因分類為 手動停止、遊戲內停止、當機 或 原因不明,並記錄在該伺服器的「最近的結束紀錄」清單中。只有在有證據(例如異常的結束代碼或模組宣告的當機檔案)時,才會將結束分類為當機;沒有證據則不視為當機。

  • 自動重新啟動:在伺服器畫面 Saba-chan 分頁的「自動重新啟動」中開啟或關閉。當機後重新啟動 預設開啟,原因不明時也重新啟動 預設關閉。你自己停止或在遊戲內停止的伺服器絕不會被重新啟動。
  • 重新啟動間隔:第一次重新啟動在 5 秒後進行,之後每次重新啟動的等待時間加倍。若 10 分鐘內重新啟動超過 3 次,Saba-chan 會停止重新啟動。請檢查記錄並手動啟動伺服器。

4.3 記錄位置

  • GUI 記錄:%APPDATA%\saba-chan\logs\(由 GUI 啟動的常駐程式的輸出也會記錄在這裡)。也可以使用 saba-chan-cli daemon logs 查看常駐程式記錄。
  • 伺服器主控台記錄:%APPDATA%\saba-chan\instances\<實例 ID>\logs\。透過執行器執行的伺服器每次執行都會在 sessions\ 下建立一個檔案,預設保留 20 個。
  • 主控台檢視:常駐程式會在記憶體中為每個實例保留最近 10,000 行。GUI 以游標輪詢端點 GET /api/instance/:id/console?since=…,最多到其顯示上限 consoleBufferSize(預設 2000 行)。

5. 下一步