---
url: 'https://bot.mcjpg.dev/unibot/api-reference.md'
description: >-
  UniBot WebUI 后端 REST API 参考：JWT 认证、登录鉴权、服务器与玩家管理、配置读写等接口的路径、参数与响应说明（挂载在 /webui
  下，路由前缀 /api）。
---
# REST API 参考

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 概览

::: table title="API 概览" copy="all"
| 模块 | 路由前缀 | 说明 |
|------|----------|------|
| 认证 | `/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` | 实时推送 |
:::

## 认证接口

### 登录

```
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`。

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

### 扩展列表

```
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` 返回该扩展的全部可选版本：

```json
{
  "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 启动、插件市场与版本更新。

::: warning
列表与详情接口要求已认证用户；**取消、重试、手动依赖同步**要求 。
:::

```
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/` 目录下的各路由文件。*