設定檔指南

以程式碼實際行為為依據,說明 Saba-chan 的資料資料夾、config.json 設定檔、實例資料夾與權杖檔案。

設定檔指南

Saba-chan 的設定與狀態都存放在資料資料夾 %APPDATA%\saba-chan(= C:\Users\<你的名稱>\AppData\Roaming\saba-chan)下。本文件整理其中的檔案 在實際程式碼中如何被使用,並區分可以安心手動編輯的檔案與不應該碰的檔案。

所有工作都由常駐程式(saba-core)執行;GUI 與 CLI 只呼叫常駐程式的本機 HTTP API。因此從 GUI 或 CLI 變更設定最安全:常駐程式在儲存時會檢查格式。


1. 資料夾結構

%APPDATA%\saba-chan\
  • config.json所有使用者設定(依命名空間)所有使用者設定(依命名空間)
  • config.json.bak最後一份正常的副本(用於自動復原)最後一份正常的副本(用於自動復原)
  • .ipc_token常駐程式 ↔ GUI/CLI 認證權杖(每次常駐程式啟動時重新產生)常駐程式 ↔ GUI/CLI 認證權杖(每次常駐程式啟動時重新產生)
  • .node_tokenDiscord(雲端中繼)連線權杖。配對時由常駐程式儲存Discord(雲端中繼)連線權杖。配對時由常駐程式儲存
  • instances\伺服器實例伺服器實例
  • order.json清單順序清單順序
  • <id>\
  • instance.json實例資訊實例資訊
  • settings.json各模組的遊戲設定值各模組的遊戲設定值
  • logs\伺服器主控台記錄伺服器主控台記錄
  • backups\備份備份
  • server\預設安裝位置(遊戲伺服器檔案)預設安裝位置(遊戲伺服器檔案)
  • modules\已安裝的遊戲模組已安裝的遊戲模組
  • extensions\已安裝的擴充功能已安裝的擴充功能
  • logs\GUI 記錄(saba-chan-<timestamp>.log)GUI 記錄(saba-chan-<timestamp>.log)
  • audit.log伺服器啟動/停止/指令的紀錄(機密已遮蔽)伺服器啟動/停止/指令的紀錄(機密已遮蔽)
  • updates\更新暫存區更新暫存區
  • installed-manifest.json已安裝的元件版本已安裝的元件版本
  • 可攜式 Python 執行環境(python-standalone\、python-env\)若安裝資料夾可寫入則建立在安裝資料夾中,否則建立在此資料資料夾中。
  • 另外還有常駐程式自行管理的檔案(daemon.lock、scan-verdicts.json、sandbox-temp\ 等)。請勿碰觸。
  • 你可以用 SABA_DATA_DIR 環境變數覆寫資料根目錄本身,但一般不建議這麼做。

2. config.json:存放所有設定的檔案

使用者設定都放在 一個檔案 config.json 中,並依命名空間(最上層鍵)分組。

命名空間內容變更位置
guiGUI 行為、主題、語言、常駐程式連接埠GUI 設定
relayDiscord 整合(前綴、別名、各 Discord 伺服器設定)GUI Discord 頁面
updates更新檢查間隔、自動下載、更新管道(channel)GUI 設定
remote遠端常駐程式:遠端連接埠、已配對的電腦GUI 設定 → 連線 → 遠端常駐程式
boot上次選擇的啟動模式(GUI / CLI / 僅常駐程式)啟動選擇器
extensions已啟用的擴充功能清單 enabled、各擴充功能設定 settingsGUI 設定 → 擴充功能
chatbot會說話的 Saba-chan(AI 對話)設定GUI Discord 頁面
sandbox同意在不隔離的情況下執行未驗證的元件執行被封鎖時的提示、設定 → 進階
cli 等各用戶端自己的設定該用戶端

儲存與自動復原

  • 儲存是原子性的(先寫入暫存檔再替換),替換前最後一份正常的副本會保留為 config.json.bak。
  • 若 config.json 損毀而無法讀取,常駐程式會將它移到一旁成為 config.json.corrupt-<timestamp>,並從 .bak 復原。
  • 放入 gui 或 relay 的未知鍵會在儲存時被捨棄。

3. gui:GUI / 常駐程式共用設定

常駐程式啟動時,若未設定 SABA_IPC_PORT 環境變數,會讀取 gui.ipcPort;若也沒有,就使用預設值 57474。其他鍵大多由 GUI 讀取。

鍵型別預設值說明
ipcPortnumber57474常駐程式 HTTP API 連接埠(一律只在 127.0.0.1 上開啟)
autoRefreshbooleantrueGUI 狀態自動重新整理
refreshIntervalnumber (ms)2000GUI 狀態輪詢間隔。設得太低會提高 CPU 使用率
consoleBufferSizenumber2000GUI 主控台保留的行數
portConflictCheckbooleantrue啟動伺服器前檢查連接埠衝突
languagestring由作業系統推斷語言(ko、en、ja、de、es、fr、pt-BR、ru、zh-CN、zh-TW)。也用於模組與 Discord 回覆
themestring無(GUI 使用 auto)"dark" / "light" / "auto"
osNotificationsbooleantrue把當機、意外啟動或停止也作為系統通知傳送
daemonViewstring無(switch)有遠端常駐程式時的伺服器列表樣式。"switch" 僅所選常駐程式,"unified" 合併顯示所有常駐程式
mainDaemonstring無(這台電腦)開啟應用程式時優先顯示的遠端常駐程式的 PC id(主常駐程式)

此外還有顏色、字型縮放、視窗大小等外觀鍵;你在 GUI 設定中變更的內容會原樣儲存。


4. relay:Discord 整合

Discord 機器人只在雲端中繼上執行,因此你的電腦上沒有機器人程序或機器人權杖。此命名空間儲存你在 GUI 中編輯的前綴、稱呼與各 Discord 伺服器設定;配對後,常駐程式會將它們同步到中繼伺服器。

鍵型別預設值說明
prefixesstring[]未針對各 Discord 伺服器另行設定前綴時使用的聊天指令前綴列表(最多 10 個,每個 1–32 個字元且不含空格)。各 Discord 伺服器的前綴存放在 nodeSettings,在應用程式的 Discord 伺服器 → 機器人設定 分頁中變更。為空時使用 該 Discord 伺服器機器人語言(未設定時為 PC 應用程式語言)的預設值(韓語 사바쨩、日語 サバちゃん,其他 Saba-chan)。以字母結尾的前綴後必須接空格(或逗號、冒號),訊息才會被視為指令
serverWordsobject{}各伺服器(實例 ID)用來稱呼該伺服器與其指令的詞 {words, commands}。在伺服器畫面的 Discord 分頁中變更
newGuildInstancesstring"auto"以配對碼新連接的 Discord 伺服器,是立即開放這台電腦的所有伺服器(auto),還是之後再挑選(manual)
nodeSettingsobject{}各 Discord 伺服器的設定(允許的實例、指令權限、語言、前綴、斜線指令樣式、會唱歌的 Saba-chan、會朗讀的 Saba-chan、再確認設定等)
cloudobjectrelayUrl、hostId。配對時填入

舊的全域別名(moduleAliases、commandAliases、instanceAliases)會在常駐程式啟動時移到 serverWords 並清空。

nodeSettings 中的權限與 Discord 設定只能透過其專用畫面(API)變更;儲存整份機器人設定不會覆寫它們。

指令語法

Saba-chan <server name or alias> <command> [arguments…]
  • Saba-chan minecraft start
  • Saba-chan mc stop(別名)
  • Saba-chan palworld status
  • Saba-chan list:伺服器清單,Saba-chan help:說明

每個伺服器都有預設指令 start、stop 與 status;其他指令由模組定義。音樂等額外功能由中繼伺服器端的機器人提供。

remote:遠端常駐程式

你的其他電腦連線本常駐程式所用的遠端連接埠,以及本機要連線的遠端常駐程式列表。在應用程式的設定 → 連線 → 遠端常駐程式或用 saba-chan-cli remote 修改,不包含在設定匯出中。用法見遠端常駐程式。它與 relay 分開,儲存在 config.json 的最上層鍵中。

鍵型別預設值說明
enabledbooleantrue開啟遠端連接埠
portnumber57480遠端連接埠(TLS)
addressstring無其他電腦能存取到的公網 IP 或主機名。留空則只能經由中繼連線
transportstring"direct"連線方式。目前只有 "direct",請保持不變
clientsarray[]與本常駐程式配對的電腦(令牌只儲存雜湊)
daemonsarray[]本機要連線的遠端常駐程式

5. instances\:伺服器實例

你在 GUI 中建立的每個伺服器都儲存為各自的 instances\<id>\ 資料夾。<id> 是 UUID。

  • instance.json:名稱、模組、執行檔/工作資料夾、連接埠、REST 連線資訊、排程工作、擴充功能資料(extension_data)等。
  • settings.json:模組宣告的遊戲設定值(例如最大玩家數、難度)。
  • order.json:GUI 清單的順序。
// instances\<id>\instance.json(節錄)
{
  "id": "3f6c…",
  "name": "My Minecraft Server",
  "module_name": "minecraft",
  "working_dir": null,
  "port": 25565,
  "extension_data": {}
}
  • 只有模組宣告 supported = ["rcon"] 的遊戲(沒有主控台也沒有 REST API)才會使用 RCON,此時常駐程式會為每個執行個體指派連接埠與隨機密碼,且只透過迴路位址(127.0.0.1)連線。其他遊戲指令會送到伺服器主控台(stdin),Palworld 則使用其 REST API。舊檔案中殘留的 RCON 鍵會在載入時被移除。
  • extension_data 是保留給擴充功能的儲存空間。例如透過 SteamCMD 安裝的模組,其安裝方式與應用程式資訊會放在這裡。
  • 儲存伺服器設定時(GUI 伺服器設定、PATCH /api/instance/:id),既不是通用實例欄位、也不是模組宣告之設定的鍵,會以 unknown_setting 錯誤被拒絕。
  • 刪除實例會刪除整個 instances\<id>\ 資料夾,包括預設安裝位置(server\)中的遊戲伺服器檔案與 backups\。

請只在 常駐程式未執行時 手動編輯這些檔案。在執行中編輯會與常駐程式記憶體中的狀態不一致,且下一次儲存會覆寫你的編輯。


6. 權杖檔案(.ipc_token / .node_token)

檔案格式建立時機使用者
.ipc_tokenUUID v4(單行)每次常駐程式啟動時重新產生GUI / CLI / 模組與擴充功能(本機 API 呼叫)
.node_tokensbn_<hostId>.<secret>Discord 配對完成時由常駐程式儲存常駐程式的中繼連線

IPC 權杖

常駐程式 API 只監聽 127.0.0.1,除了 /health 以外的所有請求都需要 X-Saba-Token 標頭。

GET /api/servers HTTP/1.1
Host: 127.0.0.1:57474
X-Saba-Token: <contents of the .ipc_token file>
  • 每當常駐程式重新啟動,權杖就會改變。GUI 與 CLI 在認證失敗時會重新讀取權杖檔案,因此你不需要做任何事。
  • 權杖檔案的位置可以用 SABA_TOKEN_PATH 變更。

節點權杖

.node_token 是將這台電腦連接到 Discord 機器人(雲端中繼)的密鑰。常駐程式會透過 HTTPS 將它傳送到中繼伺服器進行認證。絕對不要給任何人看;若懷疑外洩,請從 GUI 重新配對。重新配對會使舊權杖失效。


7. 擴充功能與隔離設定(extensions / sandbox)

  • extensions.enabled:已啟用的擴充功能 ID 清單。
  • extensions.settings:各擴充功能的設定值 { "<id>": { "<key>": value } }。透過常駐程式 API PUT /api/extensions/:id/config 變更。
  • sandbox.unisolated:同意在不隔離的情況下執行無法準備隔離環境的元件。它以元件檔案的指紋儲存,若任何檔案變更就會再次詢問。你可以在 GUI 的 設定 → 安全性 →「不隔離執行」中撤回,或使用 saba-chan-cli sandbox revoke <component>。

8. 主要環境變數

變數對象說明
SABA_IPC_PORT常駐程式 / CLI覆寫 gui.ipcPort
SABA_DAEMONCLI接收指令的遠端常駐程式,與 --daemon <名稱> 相同
SABA_DATA_DIR常駐程式重新指定資料根目錄本身(進階)
SABA_TOKEN_PATH常駐程式IPC 權杖檔案路徑
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATH常駐程式重新指定模組、擴充功能與實例資料夾
RUST_LOG常駐程式記錄篩選器(預設 info)
SABA_IPC_URL模組/擴充功能子程序常駐程式 API 位址。由常駐程式注入子程序
SABA_LANG模組/擴充功能子程序目前語言(gui.language)
PYTHONPATH模組/擴充功能子程序合併模組與擴充功能路徑後注入
SABA_ENABLED_EXTENSIONS模組/擴充功能子程序已啟用的擴充功能 ID 清單(以 , 分隔)
PYTHONIOENCODING模組/擴充功能子程序一律為 utf-8
PYTHONUNBUFFERED模組/擴充功能子程序1:立即清空 stdout

若懷疑自己弄壞了什麼,請 先停止常駐程式,然後刪除有問題的檔案再重新啟動;大多數檔案都會以預設值重新產生。刪除 config.json 會重設所有設定,包括你的 Discord 整合設定,因此請先嘗試還原 config.json.bak。請不要刪除 instances\ 資料夾:你的伺服器清單以及安裝在預設位置的遊戲檔案都會一起消失。