REST API 參考
Saba-chan 常駐程式對外提供的 HTTP API。涵蓋認證方式與主要端點目錄。
REST API 參考
Saba-chan 常駐程式(saba-core)在 127.0.0.1:57474 提供 HTTP REST API。GUI 與 CLI 只呼叫此 API,而透過雲端中繼傳來的 Discord 指令也由常駐程式內部的相同功能處理。你可以依照相同的約定打造自訂用戶端。
本參考從常駐程式的路由定義(src/ipc/)中,整理使用者或整合者可能需要的路由。部分內部路由已省略,且欄位結構可能會變更,最新內容請參考程式碼。
1. 基本資訊
- 基礎 URL:
http://127.0.0.1:57474(預設)。可透過SABA_IPC_PORT環境變數或config.json中的gui.ipcPort變更(常駐程式重新啟動後生效)。 - 繫結位址:固定為
127.0.0.1,因此無法從外部存取。Host標頭不是 loopback(127.0.0.1、localhost、::1)的請求會收到 403。 - 認證:除了
/health以外的所有請求都需要X-Saba-Token標頭。常駐程式每次啟動都會產生新的權杖,並寫入資料資料夾中的.ipc_token檔案(Windows:%APPDATA%\saba-chan\.ipc_token)。權杖遺失或錯誤時會收到沒有內容的 401。 - Content-Type:請求內容為
application/json。大多數回應也是 JSON(擴充功能 GUI 套件、圖示等例外)。 - 錯誤格式:因路由而異。常見的形式有
{"error": "...", "error_code": "..."}、{"success": false, "error": ..., "error_code": ...}與{"ok": false, "error": ...}。部分路由在失敗時會回傳 HTTP 200 搭配ok:false,因此也請檢查內容。
2. 健康檢查與常駐程式
GET /health # 不需要權杖
GET /api/version
GET /api/diagnostics
GET /api/events # 事件串流(SSE)
POST /api/daemon/shutdown
/health:{"ok": true, "version": "x.y.z", "pid": 1234, "token": "valid" | "invalid" | "missing"}。token只告訴你所傳送的X-Saba-Token是否正確,絕不會透露其值。/api/version:{version, components: {...}}(核心、模組與擴充功能的版本)。/api/events:Server-Sent Events。主要種類有instance.exit(伺服器結束 / 當機判定)、backup.done、update.available、schedule.warn、provision.progress與action.run。重新連線時,可以用Last-Event-ID標頭或?since=<n>補上錯過的事件。/api/daemon/shutdown:關閉常駐程式。
3. 伺服器(實例)
Saba-chan 將每個伺服器作為 實例 管理,以 UUID(id)識別。
3.1 列出、建立、更新、刪除
GET /api/servers # 伺服器清單 + 執行狀態
GET /api/instances # 實例清單
POST /api/instances # 建立
PUT /api/instances/reorder # body: { "order": [id, ...] }
GET /api/instance/:id # 詳細資訊(+ agreements 中的條款同意狀態)
PATCH /api/instance/:id # 變更設定(鍵值物件)
DELETE /api/instance/:id # 刪除
POST /api/instance/:id/rename # body: { "name": "..." }
POST /api/instances的主要欄位:{ "name", "module_name", "port"?, "preset"?, "module_settings"?, "accept_agreements"?: [id] }。成功時回傳 201{success, id, ...},若模組定義了安裝步驟,會在背景開始安裝伺服器檔案(§3.5)。- 除了連接埠與模組設定之外,
PATCH /api/instance/:id也接受下列常駐程式設定:auto_restart、restart_on_unknown_exit:當機後 / 原因不明結束後是否自動重新啟動extra_args:額外的啟動參數(字串或字串陣列;null清除)memory_limit_mb:記憶體上限(MiB,至少 256;接受"4G"/"4096M"形式;null/0表示不限制)。僅適用於 Windows。
- 重新命名需要伺服器處於停止狀態;已被使用的名稱會回傳 409
name_taken。
3.2 啟動 / 停止 / 重新啟動
POST /api/instance/:id/start
POST /api/instance/:id/stop # 選用 body: { "force": true }
POST /api/instance/:id/restart # 選用 body: { "force": true }
GET /api/instance/:id/events # 最近的結束紀錄
GET /api/server/:name/status # 依名稱查詢狀態
- 啟動前,常駐程式會檢查條款同意狀態並執行模組的檢查。未同意的條款會回傳 409
agreement_required(附agreements);嚴重的檢查失敗會回傳 409preflight_failed。 - 停止時會傳送遊戲的正常停止指令,等待模組的逾時時間(預設 30 秒),若程序仍存活則強制終止。
force: true時會立即終止。 events回傳{events: [...]},內含結束判定(user_stop、in_game_stop、crash、unknown_exit)、其證據、任何已排程的自動重新啟動等。
3.3 主控台與指令
GET /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin # body: { "command": "say hello" }
POST /api/instance/:id/command # body: { "command": "<name>", "args"?: {...} }
GET /api/instance/:id/commands # 此伺服器可用的指令
POST /api/instance/:id/rest # 僅 REST 的遊戲(例如 Palworld)
POST /api/instance/:id/rcon # 相容性名稱;依下方指令路徑(stdin → REST → RCON)傳送
- 主控台輪詢:回應為
{success, lines: [{id, timestamp, source, content, level}], running, ...}。使用since時,會回傳id大於或等於該值的行,因此下次請傳送收到的最後一個id+ 1。不帶since時,會取得最近的count行(預設 100)。常駐程式會在記憶體中為每個伺服器保留最近 10,000 行。 - 指令路徑順序為 stdin → REST → RCON。 指令先送到伺服器主控台(stdin),而 Palworld 等只支援 REST 的遊戲則透過 REST。只有模組宣告
supported = ["rcon"]的遊戲(沒有主控台也沒有 REST API)才會使用 RCON,此時常駐程式會為每個執行個體指派連接埠與隨機密碼,且只透過迴路位址(127.0.0.1)連線。其他情況下,/rcon只是為了舊用戶端而保留名稱的路徑,會送到 stdin。沒有指令路徑的伺服器會回傳 409no_command_path。 - 若模組不支援 stdin,
/stdin會回傳 409stdin_not_supported。 /command執行模組定義的指令;若伺服器已停止則回傳 409server_not_running。
3.4 設定、條款、檢查
POST /api/instance/:id/launch-preview # body: { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements # body: { "accept": ["eula"] }
GET /api/instance/:id/properties # 讀取遊戲的設定檔
PUT /api/instance/:id/properties # body: { "settings": {...} }
POST /api/instance/:id/validate # 伺服器檢查
POST /api/instance/:id/diagnose # 記錄診斷
launch-preview會在不啟動伺服器的情況下計算啟動命令列。回應範例:{success: true, has_launch_args, command_line, program, args, extra_args, errors: [...]}。密碼值會被遮蔽為***。若模組未宣告啟動參數,會回傳has_launch_args: false。agreements記錄對模組宣告之條款(例如 Minecrafteula)的同意。它 只在本機 有效;來自遠端來源(Discord 等)的請求會收到 403agreement_local_only。未宣告的 id 會收到 400invalid_format。
3.5 安裝進度與遊戲伺服器更新
GET /api/provision-progress/:name # :name = 實例名稱
DELETE /api/provision-progress/:name # 關閉失敗的進度狀態
GET /api/instance/:id/check-update
POST /api/instance/:id/apply-update
provision-progress 回應範例:
{
"active": true,
"step": 2,
"total": 5,
"label": "...",
"message": "...",
"percent": 40,
"done": false,
"error": null
}
沒有進行中的作業時會回傳 {"active": false}。成功的進度狀態會在 5 秒後自動清除;失敗的進度狀態會保留到你以 DELETE 關閉為止(若伺服器是新建立中,此時會被復原)。進度也可以在 /api/events 上以 provision.progress 取得。
若伺服器正在執行,apply-update 會回傳 409 server_running。更新前會先進行備份(適用於支援備份的模組)。
3.6 備份與排程工作
GET /api/instance/:id/backups # { success, backups: [{ name, kind, created, size }] }
POST /api/instance/:id/backups # 立即備份
DELETE /api/instance/:id/backups/:name
POST /api/instance/:id/backups/:name/restore # 伺服器必須已停止
GET /api/instance/:id/schedule
PUT /api/instance/:id/schedule # body: { "schedule": [...], "backup_keep"?: 10 }
- 備份
kind:manual、scheduled、pre-update、pre-restore。若模組不支援備份,會收到 400backup_unsupported;若還沒有可備份的內容,會收到 400nothing_to_back_up。 - 若伺服器正在執行,還原會回傳 409
server_running,且還原前會將目前狀態備份為pre-restore。 - 一個排程工作的形式:
{ "action": "restart", "at": "05:00", "warn_minutes": [10, 5, 1], "enabled": true }
action 為 backup | restart | announce | update,且 every_minutes(每 N 分鐘)與 at(每天 HH:MM)只能使用其中一個。announce 需要 message,warn_minutes 只適用於 restart 與 update。無效的工作會回傳 400 validation_failed(附 details)。
4. 模組
GET /api/modules # 已安裝的模組
POST /api/modules/refresh # 重新讀取模組資料夾
GET /api/module/:name # 模組中繼資料
GET /api/module/:name/versions # 可安裝的遊戲伺服器版本
GET /api/module/:name/locales
GET /api/modules/manifest # 可安裝模組的目錄
POST /api/modules/manifest/:id/install # 從目錄安裝模組
DELETE /api/modules/:id # 移除模組
模組目錄來自已簽章的發行版清單,下載的檔案會在雜湊驗證通過後才安裝。
5. 擴充功能
GET /api/extensions # 含安裝/啟用狀態的清單
POST /api/extensions/rescan
GET /api/extensions/manifest # 可安裝擴充功能的目錄
GET /api/extensions/updates
POST /api/extensions/:id/install
DELETE /api/extensions/:id
POST /api/extensions/:id/enable # 非同步執行 daemon.startup 掛鉤
POST /api/extensions/:id/disable
GET /api/extensions/:id/config
PUT /api/extensions/:id/config
GET /api/extensions/:id/gui # GUI 套件(UMD JavaScript)
GET /api/extensions/:id/gui/styles # CSS
GET /api/extensions/:id/i18n/:locale # ko / en / ja / ...
擴充功能路由的錯誤使用 {success: false, error, error_code, ...} 形式。
6. 設定
GET /api/config/gui
PUT /api/config/gui # 部分 JSON(淺層合併)
GET /api/config/bot
PUT /api/config/bot # 前綴、別名等機器人設定(部分 JSON)
GET /api/system/metrics # CPU、記憶體、磁碟、各伺服器使用量
所有使用者設定都依命名空間儲存在資料資料夾中的單一 config.json 檔案。常駐程式會將機器人設定同步到中繼伺服器。Discord 機器人本身在雲端中繼上執行,因此常駐程式沒有啟動或停止機器人程序的 API。
7. 更新
GET /api/updates/status # 目前狀態與各元件版本
POST /api/updates/check # 立即檢查更新
POST /api/updates/download # 選用 body: { "components": [...] }
GET /api/updates/download/progress
POST /api/updates/apply # 選用 body: { "components": [...] }
POST /api/updates/launch-updater # 透過安裝程式套用(常駐程式會停止)
GET /api/updates/config
PUT /api/updates/config
更新資訊來自已簽章的發行版清單。必須替換執行中檔案的元件,會在 apply 回應中標示為需要另行套用;呼叫 launch-updater 後,安裝程式(saba-chan-installer --apply)會停止並替換常駐程式,只重新啟動有變更的部分。這些路由以 {ok: ...} 形式回應。
8. 雲端中繼配對
用於 GUI ↔ 中繼伺服器的配對流程。詳細流程請參考 Discord 機器人 頁面。
POST /api/relay/pair/initiate # 發行配對代碼(轉送到中繼伺服器)
GET /api/relay/pair/:code/status # 輪詢配對是否已完成
GET /api/relay/agent # 中繼代理程式狀態
POST /api/relay/agent/start
POST /api/relay/agent/stop
DELETE /api/config/node-token # 刪除這台電腦的節點權杖(停止代理程式)
配對完成後(status: "claimed"),常駐程式會自動儲存節點權杖,並以新權杖重新連接中繼代理程式。對中繼伺服器的驗證由常駐程式處理,因此用戶端不需要處理。
9. 認證範例(curl)
TOKEN=$(cat "$APPDATA/saba-chan/.ipc_token")
curl -H "X-Saba-Token: $TOKEN" \
http://127.0.0.1:57474/api/servers
curl -X POST \
-H "X-Saba-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"command":"list"}' \
http://127.0.0.1:57474/api/instance/<instance-id>/stdin
<instance-id> 是 GET /api/servers 或 GET /api/instances 回應中的 id。
10. 版本相容性
- 此 API 被歸類為 私有 IPC。它不是公開的約定,因此即使是次要版本,路徑與結構也可能變更。
- 若你散布自訂用戶端,請檢查常駐程式版本(
GET /health中的version)並保守地處理。
若遇到問題,請前往 疑難排解。