開始使用
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 公證,首次開啟被阻擋時,請到「系統設定」>「隱私權與安全性」允許開啟。
- 從網站上的下載按鈕或 GitHub Releases 下載安裝程式
saba-chan-installer.exe。 - 執行安裝程式,選擇安裝位置、要先安裝的遊戲模組以及捷徑選項,然後按下
安裝。- 預設安裝位置為
C:\Program Files\Saba-chan。若選擇的資料夾中已有其他檔案,安裝程式會在其中建立Saba-chan資料夾。 - 遊戲模組也可以之後在應用程式中新增。
- 預設安裝位置為
- 安裝程式會設定下列元件。視網路連線狀況,可能需要幾分鐘。
- 確認最新的已簽章發行版,然後下載並部署常駐程式、GUI、CLI、語系等元件(每個檔案都會進行雜湊檢查)。安裝程式也會一併放在安裝資料夾中,供之後套用更新與解除安裝 Saba-chan 時使用
- 安裝所選的遊戲模組及其所需的擴充功能(例如 SteamCMD)
- 下載可攜式 Python 並建立
venv環境(安裝在 Saba-chan 資料夾中,不會變更系統PATH) - 將已安裝的元件版本記錄在
installed-manifest.json
- 安裝完成後,按下
啟動 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 各元件的關係和通訊方式:
- 常駐程式(
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 儲存 安裝。接著依下列步驟建立伺服器:
- 新增伺服器:按下
新增伺服器並選擇作為新伺服器新增。若要連結你已在使用的伺服器資料夾,請改選遷移現有伺服器。 - 選擇遊戲:從已安裝的遊戲模組中選擇一個(官方模組:Minecraft、Palworld、Project Zomboid 與 Terraria)。
- 設定伺服器:輸入伺服器名稱,並填寫模組要求的選項(例如 Minecraft 伺服器類型)與建議設定。連接埠(遊戲用來接受玩家連線的編號)會自動指派,不會與其他伺服器衝突。
- 同意條款:對於 Minecraft 等需要同意條款(EULA)的遊戲,你必須親自閱讀條款並勾選核取方塊,才能建立伺服器。Saba-chan 絕不會自動同意條款。
- 開始安裝:按下
新增伺服器後,常駐程式會依下列順序執行設定作業:- 確認模組所需的擴充功能(例如 Palworld 與 Project Zomboid 需要 SteamCMD)。若所需的擴充功能已關閉,會提示你到「設定 → 擴充功能」中啟用。
- 將實例資料儲存到
%APPDATA%\saba-chan\instances\<實例 ID>\資料夾 - 執行
server.post_create掛鉤 - 將最新版本的遊戲伺服器檔案下載到實例資料夾的
server\目錄(Minecraft、Terraria 使用官方伺服器下載,Palworld 與 Project Zomboid 使用 SteamCMD)。進度會顯示在進度條上。
- 啟動:按下
啟動後,常駐程式會檢查條款同意狀態並執行啟動前檢查,接著執行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。
- 正常停止:將模組的
stop_command(例如 Minecraftstop、Zomboidquit)送到伺服器主控台(stdin)。對於沒有主控台輸入的遊戲(Palworld),模組會透過 REST API 要求伺服器存檔並關閉。接著常駐程式會等待停止等待時間(伺服器 Saba-chan 分頁中設定的值;沒有時為module.toml的[config].stop_timeout;再沒有時為 30 秒)。若超過逾時時間,常駐程式會強制終止程序,並再額外等待 2 秒。 - 強制終止:強制終止時,會立即終止整個程序樹,隨後最多等待 5 秒。
- 停止冷卻:停止後的 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. 下一步
- 啟動與停止伺服器、備份、排程工作等日常運作:管理伺服器
- 透過 Discord 指令遠端管理伺服器:Discord 機器人 & 雲端中繼
- 設定設定檔(
config.json):設定檔指南 - 排除常見錯誤:疑難排解
- 開發自訂遊戲模組:模組開發指南