REST API 参考

Saba-chan 守护进程对外提供的 HTTP API。鉴权方式与主要端点目录。

REST API 参考

Saba-chan 守护进程(saba-core)在 127.0.0.1:57474 上提供 HTTP REST API。GUI 和 CLI 只调用此 API,经由 Server-chan 到达的 Discord 命令也由守护进程内部的相同功能处理。你可以按照同样的约定编写自定义客户端。

本参考根据守护进程的路由定义(src/ipc/)整理了用户或集成者可能需要的路由。部分内部路由已省略,字段结构也可能变化,最新信息请以代码为准。


1. 基础

  • 基础 URL:http://127.0.0.1:57474(默认)。可以通过 SABA_IPC_PORT 环境变量或 config.json 中的 gui.ipcPort 修改(守护进程重启后生效)。
  • 绑定地址:固定为 127.0.0.1,因此无法从外部访问。Host 请求头不是回环地址(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                      # 创建
POST   /api/instances/check                # 创建前检查(名称・文件夹・端口是否冲突,不会创建任何东西)
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"?, "version"?, "working_dir"?, "managed_start"?, "accept_agreements"?: [id] }。version 留空则为最新版本,working_dir 是用来安装新服务器的空文件夹(绝对路径),managed_start: false 表示自行管理运行。模块用 install_options 规定范围之外的安装值会返回 400 not_installable。成功时返回 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/instance/:id/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 文件里。守护进程会将机器人设置同步到 Server-chan。Discord 机器人本身运行在 Server-chan 上,因此守护进程没有启动或停止机器人进程的 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. Server-chan 配对

用于 GUI ↔ Server-chan 的配对流程。详细流程请参阅 Discord 机器人 页面。

POST   /api/relay/pair/initiate            # 签发配对代码 (转发到 Server-chan)
GET    /api/relay/pair/:code/status        # 轮询配对是否完成
GET    /api/relay/agent                    # Server-chan 代理状态
POST   /api/relay/agent/start
POST   /api/relay/agent/stop
DELETE /api/config/node-token              # 删除这台电脑的节点令牌 (停止代理)

配对完成后(status: "claimed"),守护进程会自动保存节点令牌,并用新令牌重新连接 Server-chan 代理。向 Server-chan 的认证由守护进程处理,客户端无需关心。


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)并保守地处理。

如果遇到问题,请前往 故障排查。