設定檔指南
以程式碼實際行為為依據,說明 Saba-chan 的資料資料夾、config.json 設定檔、實例資料夾與權杖檔案。
設定檔指南
Saba-chan 的設定與狀態都存放在資料資料夾 %APPDATA%\saba-chan(= C:\Users\<你的名稱>\AppData\Roaming\saba-chan)下。本文件整理其中的檔案 在實際程式碼中如何被使用,並區分可以安心手動編輯的檔案與不應該碰的檔案。
所有工作都由常駐程式(saba-core)執行;GUI 與 CLI 只呼叫常駐程式的本機 HTTP API。因此從 GUI 或 CLI 變更設定最安全:常駐程式在儲存時會檢查格式。
1. 資料夾結構
- 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 中,並依命名空間(最上層鍵)分組。
| 命名空間 | 內容 | 變更位置 |
|---|---|---|
gui | GUI 行為、主題、語言、常駐程式連接埠 | GUI 設定 |
relay | Discord 整合(前綴、別名、各 Discord 伺服器設定) | GUI Discord 頁面 |
updates | 更新檢查間隔、自動下載、更新管道(channel) | GUI 設定 |
remote | 遠端常駐程式:遠端連接埠、已配對的電腦 | GUI 設定 → 連線 → 遠端常駐程式 |
boot | 上次選擇的啟動模式(GUI / CLI / 僅常駐程式) | 啟動選擇器 |
extensions | 已啟用的擴充功能清單 enabled、各擴充功能設定 settings | GUI 設定 → 擴充功能 |
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 讀取。
| 鍵 | 型別 | 預設值 | 說明 |
|---|---|---|---|
ipcPort | number | 57474 | 常駐程式 HTTP API 連接埠(一律只在 127.0.0.1 上開啟) |
autoRefresh | boolean | true | GUI 狀態自動重新整理 |
refreshInterval | number (ms) | 2000 | GUI 狀態輪詢間隔。設得太低會提高 CPU 使用率 |
consoleBufferSize | number | 2000 | GUI 主控台保留的行數 |
portConflictCheck | boolean | true | 啟動伺服器前檢查連接埠衝突 |
language | string | 由作業系統推斷 | 語言(ko、en、ja、de、es、fr、pt-BR、ru、zh-CN、zh-TW)。也用於模組與 Discord 回覆 |
theme | string | 無(GUI 使用 auto) | "dark" / "light" / "auto" |
osNotifications | boolean | true | 把當機、意外啟動或停止也作為系統通知傳送 |
daemonView | string | 無(switch) | 有遠端常駐程式時的伺服器列表樣式。"switch" 僅所選常駐程式,"unified" 合併顯示所有常駐程式 |
mainDaemon | string | 無(這台電腦) | 開啟應用程式時優先顯示的遠端常駐程式的 PC id(主常駐程式) |
此外還有顏色、字型縮放、視窗大小等外觀鍵;你在 GUI 設定中變更的內容會原樣儲存。
4. relay:Discord 整合
Discord 機器人只在雲端中繼上執行,因此你的電腦上沒有機器人程序或機器人權杖。此命名空間儲存你在 GUI 中編輯的前綴、稱呼與各 Discord 伺服器設定;配對後,常駐程式會將它們同步到中繼伺服器。
| 鍵 | 型別 | 預設值 | 說明 |
|---|---|---|---|
prefixes | string | [] | 未針對各 Discord 伺服器另行設定前綴時使用的聊天指令前綴列表(最多 10 個,每個 1–32 個字元且不含空格)。各 Discord 伺服器的前綴存放在 nodeSettings,在應用程式的 Discord 伺服器 → 機器人設定 分頁中變更。為空時使用 該 Discord 伺服器機器人語言(未設定時為 PC 應用程式語言)的預設值(韓語 사바쨩、日語 サバちゃん,其他 Saba-chan)。以字母結尾的前綴後必須接空格(或逗號、冒號),訊息才會被視為指令 |
serverWords | object | {} | 各伺服器(實例 ID)用來稱呼該伺服器與其指令的詞 {words, commands}。在伺服器畫面的 Discord 分頁中變更 |
newGuildInstances | string | "auto" | 以配對碼新連接的 Discord 伺服器,是立即開放這台電腦的所有伺服器(auto),還是之後再挑選(manual) |
nodeSettings | object | {} | 各 Discord 伺服器的設定(允許的實例、指令權限、語言、前綴、斜線指令樣式、會唱歌的 Saba-chan、會朗讀的 Saba-chan、再確認設定等) |
cloud | object | relayUrl、hostId。配對時填入 |
舊的全域別名(
moduleAliases、commandAliases、instanceAliases)會在常駐程式啟動時移到serverWords並清空。
nodeSettings中的權限與 Discord 設定只能透過其專用畫面(API)變更;儲存整份機器人設定不會覆寫它們。
指令語法
Saba-chan <server name or alias> <command> [arguments…]
Saba-chan minecraft startSaba-chan mc stop(別名)Saba-chan palworld statusSaba-chan list:伺服器清單,Saba-chan help:說明
每個伺服器都有預設指令 start、stop 與 status;其他指令由模組定義。音樂等額外功能由中繼伺服器端的機器人提供。
remote:遠端常駐程式
你的其他電腦連線本常駐程式所用的遠端連接埠,以及本機要連線的遠端常駐程式列表。在應用程式的設定 → 連線 → 遠端常駐程式或用 saba-chan-cli remote 修改,不包含在設定匯出中。用法見遠端常駐程式。它與 relay 分開,儲存在 config.json 的最上層鍵中。
| 鍵 | 型別 | 預設值 | 說明 |
|---|---|---|---|
enabled | boolean | true | 開啟遠端連接埠 |
port | number | 57480 | 遠端連接埠(TLS) |
address | string | 無 | 其他電腦能存取到的公網 IP 或主機名。留空則只能經由中繼連線 |
transport | string | "direct" | 連線方式。目前只有 "direct",請保持不變 |
clients | array | [] | 與本常駐程式配對的電腦(令牌只儲存雜湊) |
daemons | array | [] | 本機要連線的遠端常駐程式 |
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_token | UUID v4(單行) | 每次常駐程式啟動時重新產生 | GUI / CLI / 模組與擴充功能(本機 API 呼叫) |
.node_token | sbn_<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 } }。透過常駐程式 APIPUT /api/extensions/:id/config變更。sandbox.unisolated:同意在不隔離的情況下執行無法準備隔離環境的元件。它以元件檔案的指紋儲存,若任何檔案變更就會再次詢問。你可以在 GUI 的 設定 → 安全性 →「不隔離執行」中撤回,或使用saba-chan-cli sandbox revoke <component>。
8. 主要環境變數
| 變數 | 對象 | 說明 |
|---|---|---|
SABA_IPC_PORT | 常駐程式 / CLI | 覆寫 gui.ipcPort |
SABA_DAEMON | CLI | 接收指令的遠端常駐程式,與 --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\ 資料夾:你的伺服器清單以及安裝在預設位置的遊戲檔案都會一起消失。