管理面板
约 2558 字大约 9 分钟
WebUI 是 UniBot 内置的现代化 Web 管理面板，基于 Vue 3 + Vite + Pinia + reka-ui 构建，通过 REST API 与 WebSocket 与后端交互。
它提供可视化配置、实时监控、服务器 / 玩家管理、日志查看等能力，是日常使用 UniBot 的主要入口。使用 WebUI 后基本无需手动修改配置文件，全程在浏览器中即可完成部署与运维。
功能一览
| 视图 | 功能 |
|---|---|
| 仪表盘 | 实时查看运行状态、内存/CPU 占用、在线服务器数、已绑定玩家数；顶部含「快速开始」引导卡片 |
| 服务器 | 查看所有连接的服务器状态、在线玩家；进入详情页远程执行指令 |
| 玩家管理 | 管理白名单绑定关系，将平台用户与游戏 ID 关联 |
| 适配器 | 查看 / 安装 / 启用 / 配置各平台通信适配器（Minecraft、OneBot V11 等） |
| 插件管理 | 查看已加载的 NoneBot2 插件列表及启停状态 |
| 扩展管理 | 管理 UniBot 扩展：启停、配置、切换渲染引擎与模板、访问扩展市场 |
| 配置中心 | 可视化编辑 Config.toml 与 .env，Schema 校验、分组展示、支持源码模式 |
| 日志查看 | 实时滚动查看运行日志，支持文件切换与分级筛选 |
| 用户管理 | 管理 WebUI 登录账户、角色与权限 |
| 个人设置 | 查看当前账户信息、修改密码 |
| 登录认证 | JWT + 密码认证（HttpOnly Cookie），首次访问引导初始化管理员账户 |
WebUI 主要功能
启用与访问
前置要求
WebUI 依赖需要先安装，且需在 Config.toml 中开启：
# 安装 webui 依赖（安装脚本 / 手动部署均需执行）
cd UniBot
uv sync --extra webui --inexact[webui]
enabled = true注意
未执行上述依赖安装时 WebUI 无法启用，请先确认已安装。
启动与访问
- 启动机器人：
uv run Watchdog.py。 - 首次启动时，机器人会自动从 GitHub Releases 下载与自身版本匹配的 WebUI 静态资源并挂载。
- 浏览器访问
http://<你的IP>:<PORT>/webui（默认http://127.0.0.1:8000/webui）。
初始化管理员
首次访问请先完成初始化：页面会引导你创建管理员账户（用户名 + 密码）。创建完成后即可登录进入仪表盘。
注
管理员账户用于保护 WebUI 管理功能。若需多人协作，可在「用户管理」中创建更多账户。
页面详解
仪表盘
登录后默认进入仪表盘，展示机器人的实时运行状态：
顶部状态条：连接状态、在线服务器数、在线玩家数、内存 / CPU 占用。
「快速开始」引导卡片：贯穿部署全过程的进度清单，三步自动检测完成状态：
- 连接聊天平台 — 检测到已启用聊天平台适配器后自动完成；
- 接入 Minecraft 服务器 — 检测到服务器已接入（有在线服务器或已配置 WS 地址）后自动完成；
- 添加超级用户 —
SUPERUSERS非空后自动完成。
全部完成后卡片自动收起，也可手动折叠（状态记忆在浏览器本地）。
服务器一览：所有已连接服务器的在线状态快速总览。
快速开始引导卡片
「快速开始」引导卡片是仪表盘顶部的部署进度清单，按以下三步全自动判断完成状态：
连接聊天平台
检测到已安装并启用 QQ / Telegram 等平台适配器后自动完成，点击可跳转到适配器管理页。
接入 Minecraft 服务器
检测到服务器已通过鹊桥插件接入（有在线服务器，或已配置 WebSocket 地址）后自动完成，点击可查看鹊桥安装文档。
添加超级用户
设置管理员以使用管理命令，点击右侧的「令牌授权」按钮可快速完成授权。
三步全部完成后，卡片会自动收起。这张卡片只是部署进度的可视化清单，与部署文档的步骤一一对应：
| 引导卡片步骤 | 对应文档章节 |
|---|---|
| 连接聊天平台 | 快速开始 · 第三步 |
| 接入 Minecraft 服务器 | 快速开始 · 第二步 |
| 添加超级用户 | 快速开始 · 第四步 |
提示
引导卡片的完成状态由 WebUI 自动检测（有在线适配器 / 有在线服务器 / SUPERUSERS 非空），无需手动勾选。
令牌授权
在引导卡片「添加超级用户」步骤点击 令牌授权，提示框会显示当前有效的认证令牌：
- 复制令牌，在任意平台的群聊中发送该令牌；
- 机器人自动完成授权：将当前群加入消息群与指令群（
message_groups/command_groups），并将发送者设为超级用户（SUPERUSERS）； - 令牌即用即刷：使用一次后立即刷新，旧令牌自动作废。
无需 WebUI 也可授权
机器人每次启动时都会在控制台打印当前令牌（形如 认证令牌：A1B2C3D4E5），在任意平台群聊中发送即可完成同样的授权。
之后也可在 WebUI 的 配置中心 中手动添加超级用户。
服务器管理
- 服务器列表：查看所有服务器的连接状态、类型与在线情况。
- 服务器详情：查看单服在线玩家、服务端类型、状态详情，并远程执行指令（向服务器控制台发送命令）。
玩家管理
管理黑 / 白名单绑定关系：将平台用户（如 QQ 号）与游戏 ID 关联，支持搜索与新增 / 解除绑定。
适配器管理
- 查看已安装的平台适配器（Minecraft、OneBot V11 等）。
- 安装 / 启用 / 禁用 / 配置适配器。
- 核心适配器（如 Minecraft）标记为受保护，禁止操作。
注
通过 WebUI 安装平台适配器时，UniBot 会自动完成依赖安装与注册。详见 接入聊天平台。
插件管理
查看已加载的 NoneBot2 插件列表及其启停状态。插件均来自官方插件商店，安装后请参考插件 GitHub 说明，在 .env 中自行配置参数。
扩展管理
UniBot 扩展系统的管理入口（需管理员权限）：
- 查看全部已安装扩展及其状态（启用 / 禁用 / 隔离中）。
- 调整扩展业务配置（基于模型 JSON Schema 动态生成表单）。
- 切换渲染引擎与模板（模板切换即时生效）。
- 访问扩展市场，搜索并一键安装 / 升级 / 卸载扩展。
- 页面右上角的「创意工坊」按钮：自动下载（如缺失）并启动 AiStudio AI 扩展开发平台，随后弹出独立窗口进入工作台，用自然语言即可从零创建、调试并安装你自己的扩展（详见 使用 AiStudio 零代码开发扩展）。
详见 扩展系统 的「WebUI 管理」一节。
配置中心
Config.toml：分组展示配置项，支持 Schema 校验，修改后保存并（按需）重启。.env：分组展示环境变量（含机器人列表字段如QQ_BOTS、TELEGRAM_BOTS等的机器人卡片编辑），保存后需重启机器人生效。Messages.toml：消息模板文本编辑。- 也提供源码模式，直接编辑 TOML / env 源码。
注意
.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 / 无法加载
- 确认
[webui] enabled = true且已执行uv sync --extra webui --inexact。 - 确认访问路径为
/webui，且端口正确（默认8000）。 - 查看机器人日志，确认 WebUI 静态资源是否成功下载与挂载。
登录提示密码错误 / 忘记管理员密码
- 确认初始化管理员时设置的账号密码。
- 若遗忘，可在服务端数据中重置（详见 用户管理 相关接口）。
WebUI 修改配置后没生效
Config.toml修改后一般需要重启，Watchdog.py会在保存时自动处理。.env保存后必须重启机器人生效；若提示需重启请按页面提示操作。
如何保护 WebUI 不被他人访问
- 将机器人绑定到内网地址，或通过反向代理 + HTTPS + 访问控制保护
/webui路径。 - 妥善管理 WebUI 账户，及时禁用不需要的账号。