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规定范围之外的安装值会返回 400not_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);严重的检查失败返回 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记录对模块所声明条款(例如 Minecraft 的eula)的同意。它仅限本地;来自远程(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 文件里。守护进程会将机器人设置同步到 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)并保守地处理。
如果遇到问题,请前往 故障排查。