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);嚴重的檢查失敗會回傳 409 preflight_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。沒有指令路徑的伺服器會回傳 409 no_command_path。
  • 若模組不支援 stdin,/stdin 會回傳 409 stdin_not_supported。
  • /command 執行模組定義的指令;若伺服器已停止則回傳 409 server_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 記錄對模組宣告之條款(例如 Minecraft eula)的同意。它 只在本機 有效;來自遠端來源(Discord 等)的請求會收到 403 agreement_local_only。未宣告的 id 會收到 400 invalid_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。若模組不支援備份,會收到 400 backup_unsupported;若還沒有可備份的內容,會收到 400 nothing_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)並保守地處理。

若遇到問題,請前往 疑難排解。