Minecraft UniBot 文档

简体中文

English

简体中文

English

外观

REST API 参考

复制页面

约 1527 字大约 5 分钟

UniBot 的 WebUI 后端提供一组 REST API，供前端管理面板调用。整个 API 路由挂载在 /webui 前缀下，各模块再加 /api/<模块> 作为路由前缀，因此实际请求路径为 /webui/api/<模块>/...。下文为行文简洁，各端点统一以 /api/... 表示，实际访问时需带上 /webui 挂载前缀。

认证方式

采用 JWT + HttpOnly Cookie 认证：

  • 登录成功后，后端通过 Set-Cookie 下发 access_token（2 小时）和 refresh_token（7 天）。
  • 前端请求需要携带 Cookie（credentials: 'include'）。
  • 也可以用 Authorization: Bearer <token> 头来传递。

令牌存放在 HttpOnly Cookie 中，前端 JS 无法读取，可有效降低 XSS 风险。

API 概览

模块路由前缀说明
认证/api/auth登录、刷新、登出
配置/api/config读取/修改配置
扩展/api/extensions扩展列表、启停、配置、渲染设置
玩家/api/players白名单绑定管理
服务器/api/servers服务器状态与指令
插件/api/plugins插件列表与状态
日志/api/logs日志查看
状态/api/status运行状态监控
统计/api/statistics消息统计与活跃群聊
用户/api/users用户管理
任务/api/tasks后台任务中心（列表、详情、取消、重试、依赖同步）
WebSocket/api/ws实时推送

API 概览

认证接口

登录

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your_password"
}

响应会设置 JWT Cookie，前端据此保持登录态。

刷新令牌

POST /api/auth/refresh

登出

POST /api/auth/logout

配置接口

读取配置

GET /api/config

返回当前配置（按分组展示）。

修改配置

PUT /api/config
Content-Type: application/json

{
  "section": "webui",
  "key": "enabled",
  "value": true
}

修改后需重启机器人才生效（由 Watchdog 处理）。

状态接口

GET /api/status

返回机器人运行状态，包括内存占用、在线服务器数、绑定玩家数等。

服务器接口

GET /api/servers                    # 所有服务器状态
GET /api/servers/{name}             # 指定服务器详情
POST /api/servers/{name}/command    # 远程执行指令

统计接口

由「数据统计」插件在后台自动收集，数据持久化于 Data/Statistics.json。

获取统计数据

GET /api/statistics?days=30         # days 为趋势天数（1-90，默认 30）

返回总览摘要、按天趋势、活跃群聊排行、平台分布以及当前已连接的机器人列表。

清空统计数据

POST /api/statistics/reset

清空全部统计数据并立即落盘，需要 管理员权限。

玩家接口

GET /api/players                    # 玩家列表
PUT /api/players/{id}               # 修改绑定
DELETE /api/players/{id}            # 删除绑定

扩展接口

扩展管理接口挂载于 /api/extensions。

注意

修改配置、启停、卸载、安装以及切换渲染引擎 / 模板 均要求 管理员权限；列表与详情接口至少要求已认证用户。

扩展列表

GET /api/extensions

返回已安装扩展列表（类型、版本、依赖、启停状态）。

扩展详情

GET /api/extensions/items/{id}

返回指定扩展的详情与配置 Schema。

启用 / 禁用

POST /api/extensions/{id}/enable
POST /api/extensions/{id}/disable

持久化启停意图，重启后生效。启用接口在依赖仍被禁用、缺失或版本不兼容时拒绝写入，并返回阻塞依赖及原因；禁用成功后，其依赖方在下一次加载时显示为 blocked。

扩展配置

GET   /api/extensions/config-items     # 全部带配置项的扩展（含无代码模板包）
GET   /api/extensions/{id}/config
PATCH /api/extensions/{id}/config

读取与更新扩展配置。config-items 供配置中心一次性拉取全部可编辑扩展的 schema 与当前值。配置更新会经过扩展模型校验，失败时返回字段级错误且不修改原配置；键名含 key / secret / token 的字段以 <configured> 占位返回，回传该占位符表示不修改原值。

渲染引擎管理

GET  /api/extensions/renderers
POST /api/extensions/renderers/switch

查看可用渲染引擎（含当前选中）并切换。渲染引擎切换重启后生效。

模板管理

GET  /api/extensions/templates
POST /api/extensions/templates/switch

查看可用模板扩展并切换，模板切换即时生效。

资源扩展

GET /api/extensions/resources

返回可用资源扩展及资源状态。资源扩展不支持配置。

扩展市场安装与版本切换

POST /api/extensions/market/install
GET  /api/extensions/market/{id}/releases

market/install 提交后台安装任务，请求体：

字段说明
id扩展 id
version可选；留空表示自动选择兼容当前 UniBot 版本的最新历史版本，传具体版本号则安装该版本（可用于回退）

自动选择时：最新版本兼容则装最新；最新版不兼容但有兼容历史版本则回退并记录日志；一个兼容版本都没有时返回错误，提示此扩展不支持当前核心版本。

market/{id}/releases 返回该扩展的全部可选版本：

{
  "unibot_version": "1.0.3",
  "releases": [{ "version": "1.0.2", "unibot_version": ">= 1.0.2", "compatible": true, "installed": false }]
}

日志接口

GET /api/logs?level=INFO&limit=100  # 获取日志

任务接口

后台任务中心接口挂载于 /api/tasks，覆盖依赖同步、市场扩展安装/卸载、扩展热重载、Studio 启动、插件市场与版本更新。

注意

列表与详情接口要求已认证用户；取消、重试、手动依赖同步要求 管理员权限。

GET  /api/tasks                     # 任务列表 + 状态摘要
GET  /api/tasks/{id}                # 任务详情（含日志）
POST /api/tasks/{id}/cancel         # 取消任务
POST /api/tasks/{id}/retry          # 重试任务
POST /api/tasks/dependency-sync     # 手动触发依赖同步

任务快照字段：id、kind、title_params、status（pending / running / succeeded / failed / cancelled）、 message_key + message_params（阶段说明，由前端按界面语言翻译）、progress、error、result、 created_at / started_at / finished_at、retryable、log_count（详情接口额外返回 logs）。

任务状态变更会通过 WebSocket 的 task 事件实时推送。

WebSocket 推送

WS /api/ws

实时推送运行状态、日志增量、服务器事件等，供前端仪表盘实时更新。

如需完整的接口定义，可直接查阅后端源码 Scripts/Api/ 目录下的各路由文件。