---
url: 'https://bot.mcjpg.dev/guide/webui.md'
description: >-
  UniBot 内置 WebUI 管理面板使用指南：可视化配置环境变量、实时监控、服务器与玩家管理、白名单、日志查看，基于 Vue 3 与 REST API
  / WebSocket 的现代化管理界面。
---
# 管理面板

**WebUI** 是 UniBot 内置的现代化 Web 管理面板，基于 **Vue 3 + Vite + Pinia + reka-ui** 构建，通过 REST API 与 WebSocket 与后端交互。

它提供**可视化配置、实时监控、服务器 / 玩家管理、日志查看**等能力，是日常使用 UniBot 的主要入口。==使用 WebUI 后基本无需手动修改配置文件==，全程在浏览器中即可完成部署与运维。

## 功能一览

::: table title="WebUI 主要功能" copy="all"
| 视图 | 功能 |
|------|------|
| **::fluent-color:data-pie-24:: 仪表盘** | 实时查看运行状态、内存/CPU 占用、在线服务器数、已绑定玩家数；顶部含「快速开始」引导卡片 |
| **::fluent-color:clipboard-24:: 服务器** | 查看所有连接的服务器状态、在线玩家；进入详情页远程执行指令 |
| **::fluent-color:people-24:: 玩家管理** | 管理白名单绑定关系，将平台用户与游戏 ID 关联 |
| **::fluent-color:puzzle-piece-24:: 适配器** | 查看 / 安装 / 启用 / 配置各平台通信适配器（Minecraft、OneBot V11 等） |
| **::fluent-color:apps-list-24:: 插件管理** | 查看已加载的 NoneBot2 插件列表及启停状态 |
| **::fluent-color:toolbox-24:: 扩展管理** | 管理 UniBot 扩展：启停、配置、切换渲染引擎与模板、访问扩展市场 |
| **::fluent-color:settings-24:: 配置中心** | 可视化编辑 `Config.toml` 与 `.env`，Schema 校验、分组展示、支持源码模式 |
| **::fluent-color:document-24:: 日志查看** | 实时滚动查看运行日志，支持文件切换与分级筛选 |
| **::fluent-color:person-24:: 用户管理** | 管理 WebUI 登录账户、角色与权限 |
| **::fluent-color:person-key-24:: 个人设置** | 查看当前账户信息、修改密码 |
| **::fluent-color:lock-closed-24:: 登录认证** | JWT + 密码认证（HttpOnly Cookie），首次访问引导初始化管理员账户 |
:::

## 启用与访问

### 前置要求

WebUI 依赖需要先安装，且需在 `Config.toml` 中开启：

```bash
# 安装 webui 依赖（安装脚本 / 手动部署均需执行）
cd UniBot
uv sync --extra webui --inexact
```

```toml
[webui]
enabled = true
```

::: warning
\==未执行上述依赖安装时 WebUI 无法启用==，请先确认已安装。
:::

### 启动与访问

1. 启动机器人：`uv run Watchdog.py`。
2. 首次启动时，机器人会**自动从 GitHub Releases 下载与自身版本匹配的 WebUI 静态资源**并挂载。
3. 浏览器访问 `http://<你的IP>:<PORT>/webui`（默认 `http://127.0.0.1:8000/webui`）。

### 初始化管理员

**首次访问请先完成初始化**：页面会引导你创建管理员账户（用户名 + 密码）。创建完成后即可登录进入仪表盘。

::: note
管理员账户用于保护 WebUI 管理功能。若需多人协作，可在「用户管理」中创建更多账户。
:::

## 页面详解

### 仪表盘

登录后默认进入仪表盘，展示机器人的实时运行状态：

* 顶部状态条：连接状态、在线服务器数、在线玩家数、内存 / CPU 占用。
* **「快速开始」引导卡片**：贯穿部署全过程的进度清单，三步自动检测完成状态：

  1. **连接聊天平台** — 检测到已启用聊天平台适配器后自动完成；
  2. **接入 Minecraft 服务器** — 检测到服务器已接入（有在线服务器或已配置 WS 地址）后自动完成；
  3. **添加超级用户** — `SUPERUSERS` 非空后自动完成。

  全部完成后卡片自动收起，也可手动折叠（状态记忆在浏览器本地）。
* 服务器一览：所有已连接服务器的在线状态快速总览。

#### 快速开始引导卡片

「快速开始」引导卡片是仪表盘顶部的**部署进度清单**，按以下三步全自动判断完成状态：

::: steps

1. **连接聊天平台**

   检测到已安装并启用 QQ / Telegram 等平台适配器后自动完成，点击可跳转到适配器管理页。

2. **接入 Minecraft 服务器**

   检测到服务器已通过鹊桥插件接入（有在线服务器，或已配置 WebSocket 地址）后自动完成，点击可查看鹊桥安装文档。

3. **添加超级用户**

   设置管理员以使用管理命令，点击右侧的「令牌授权」按钮可快速完成授权。

:::

三步全部完成后，卡片会自动收起。**这张卡片只是部署进度的可视化清单**，与部署文档的步骤一一对应：

| 引导卡片步骤 | 对应文档章节 |
|------|------|
| 连接聊天平台 | [快速开始 · 第三步](/guide/quick-start.html#第三步-接入聊天平台) |
| 接入 Minecraft 服务器 | [快速开始 · 第二步](/guide/quick-start.html#第二步-安装鹊桥插件并配置) |
| 添加超级用户 | [快速开始 · 第四步](/guide/quick-start.html#第四步-验证启动) |

::: tip
引导卡片的完成状态由 WebUI 自动检测（有在线适配器 / 有在线服务器 / `SUPERUSERS` 非空），==无需手动勾选==。
:::

##### 令牌授权

在引导卡片「添加超级用户」步骤点击 **令牌授权**，提示框会显示当前有效的认证令牌：

* 复制令牌，在**任意平台的群聊**中发送该令牌；
* 机器人自动完成授权：将**当前群**加入消息群与指令群（`message_groups` / `command_groups`），并将**发送者**设为超级用户（`SUPERUSERS`）；
* 令牌**即用即刷**：使用一次后立即刷新，旧令牌自动作废。

::: note 无需 WebUI 也可授权
机器人每次启动时都会在控制台打印当前令牌（形如 `认证令牌：A1B2C3D4E5`），在任意平台群聊中发送即可完成同样的授权。

之后也可在 WebUI 的 [配置中心](#配置中心) 中手动添加超级用户。
:::

### 服务器管理

* **服务器列表**：查看所有服务器的连接状态、类型与在线情况。
* **服务器详情**：查看单服在线玩家、服务端类型、状态详情，并**远程执行指令**（向服务器控制台发送命令）。

### 玩家管理

管理黑 / 白名单绑定关系：将平台用户（如 QQ 号）与游戏 ID 关联，支持搜索与新增 / 解除绑定。

### 适配器管理

* 查看已安装的平台适配器（Minecraft、OneBot V11 等）。
* 安装 / 启用 / 禁用 / 配置适配器。
* 核心适配器（如 Minecraft）标记为**受保护**，禁止操作。

::: note
通过 WebUI 安装平台适配器时，UniBot 会自动完成依赖安装与注册。详见 [接入聊天平台](/adapter/connect-chat-platforms.html)。
:::

### 插件管理

查看已加载的 NoneBot2 插件列表及其启停状态。插件均来自官方插件商店，安装后请参考插件 GitHub 说明，在 `.env` 中自行配置参数。

### 扩展管理

UniBot 扩展系统的管理入口（需管理员权限）：

* 查看全部已安装扩展及其状态（启用 / 禁用 / 隔离中）。
* 调整扩展业务配置（基于模型 JSON Schema 动态生成表单）。
* 切换渲染引擎与模板（模板切换即时生效）。
* 访问**扩展市场**，搜索并一键安装 / 升级 / 卸载扩展。
* 页面**右上角**的「**创意工坊**」按钮：自动下载（如缺失）并启动 **AiStudio** AI 扩展开发平台，随后弹出独立窗口进入工作台，用自然语言即可从零创建、调试并安装你自己的扩展（详见 [使用 AiStudio 零代码开发扩展](/unibot/developing-extensions.html#使用-aistudio-零代码开发扩展)）。

详见 [扩展系统](/unibot/extension-system.html) 的「WebUI 管理」一节。

### 配置中心

* **`Config.toml`**：分组展示配置项，支持 Schema 校验，修改后保存并（按需）重启。
* **`.env`**：分组展示环境变量（含机器人列表字段如 `QQ_BOTS`、`TELEGRAM_BOTS` 等的**机器人卡片**编辑），保存后需**重启机器人生效**。
* **`Messages.toml`**：消息模板文本编辑。
* 也提供**源码模式**，直接编辑 TOML / env 源码。

::: warning
\==`.env` 的修改在保存后需要重启机器人才能生效==，重启操作由 `Watchdog.py` 处理，无需手动干预。
:::

### 日志查看器

通过 WebSocket 实时滚动查看运行日志，支持选择日志文件与按级别筛选，便于排查问题。

### 用户管理

管理 WebUI 登录账户：新建 / 编辑 / 禁用用户、分配角色权限、重置密码。（仅管理员可见）

### 个人设置

查看当前账户信息，修改自己的密码。

## 认证与安全

* WebUI 使用 **JWT + 密码认证**，令牌存放在 **HttpOnly Cookie**（`unibot_access_token` / `unibot_refresh_token`）中，前端 JS 无法读取，降低 XSS 风险。
* `access_token` 过期时会自动使用刷新令牌续期，无需重新登录。
* 未登录用户只能访问登录页；**配置中心**与**用户管理**页面仅管理员可访问。
* 建议在生产环境通过反向代理（Nginx / Caddy 等）为 WebUI 启用 HTTPS。

## 常见问题

### 访问 WebUI 显示 404 / 无法加载

1. 确认 `[webui] enabled = true` 且已执行 `uv sync --extra webui --inexact`。
2. 确认访问路径为 `/webui`，且端口正确（默认 `8000`）。
3. 查看机器人日志，确认 WebUI 静态资源是否成功下载与挂载。

### 登录提示密码错误 / 忘记管理员密码

* 确认初始化管理员时设置的账号密码。
* 若遗忘，可在服务端数据中重置（详见 [用户管理](/unibot/api-reference.html) 相关接口）。

### WebUI 修改配置后没生效

* `Config.toml` 修改后一般需要重启，`Watchdog.py` 会在保存时自动处理。
* `.env` 保存后**必须重启机器人生效**；若提示需重启请按页面提示操作。

### 如何保护 WebUI 不被他人访问

* 将机器人绑定到内网地址，或通过反向代理 + HTTPS + 访问控制保护 `/webui` 路径。
* 妥善管理 WebUI 账户，及时禁用不需要的账号。

## 更多

* **接口文档**：WebUI 后端 REST API 参考见 [接口文档](/unibot/api-reference.html)。
* **部署流程**：从零部署请参阅 [快速开始](/guide/quick-start.html)。
* **配置指南**：`.env` 与 `Config.toml` 全部配置项见 [配置指南](/guide/configuration.html)。