Minecraft UniBot 文档

简体中文

English

简体中文

English

外观

管理面板

复制页面

约 2842 字大约 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、Messages.toml 与扩展配置，Schema 校验、分组展示、支持源码模式
日志查看实时滚动查看运行日志，支持文件切换与分级筛选
任务中心右上角入口：查看依赖同步、扩展安装、插件安装、Studio 启动等后台任务的进度与日志，支持取消与重试
用户管理管理 WebUI 登录账户、角色与权限
个人设置查看当前账户信息、修改密码
登录认证JWT + 密码认证（HttpOnly Cookie），首次访问引导初始化管理员账户

WebUI 主要功能

启用与访问

前置要求

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

# 安装 webui 依赖（安装脚本 / 手动部署均需执行）
cd UniBot
uv sync --no-dev --extra webui
[webui]
enabled = true

注意

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

启动与访问

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

初始化管理员

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

注

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

页面详解

仪表盘

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

  • 顶部状态条：连接状态、在线服务器数、在线玩家数、内存 / CPU 占用。

  • 「快速开始」引导卡片：贯穿部署全过程的进度清单，三步自动检测完成状态：

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

    全部完成后卡片自动收起，也可手动折叠（状态记忆在浏览器本地）。

  • 服务器一览：所有已连接服务器的在线状态快速总览。

快速开始引导卡片

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

  1. 连接聊天平台

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

  2. 接入 Minecraft 服务器

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

  3. 添加超级用户

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

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

引导卡片步骤对应文档章节
连接聊天平台快速开始 · 第三步
接入 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 实时滚动查看运行日志，支持选择日志文件与按级别筛选，便于排查问题。

任务中心

右上角的任务列表图标（角标显示进行中的任务数）以抽屉形式列出全部后台任务：

  • 覆盖依赖同步、扩展市场安装/卸载、扩展热重载、Studio 下载与启动、插件市场安装/升级/卸载、版本更新。
  • 每个任务显示状态（排队中 / 执行中 / 已完成 / 失败 / 已取消）、阶段说明、创建时间与耗时，运行中显示进度条。
  • 展开任务可查看实时日志（通过 WebSocket 推送），并在需要时取消或重试任务。
  • 抽屉内可直接手动触发依赖同步（写入一律通过 uv add / uv remove，无需手工编辑 pyproject.toml）。

用户管理

管理 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 --no-dev --extra webui。
  2. 确认访问路径为 /webui，且端口正确（默认 8000）。
  3. 查看机器人日志，确认 WebUI 静态资源是否成功下载与挂载。

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

  • 确认初始化管理员时设置的账号密码。
  • 若遗忘，可在服务端数据中重置（详见 用户管理 相关接口）。

WebUI 修改配置后没生效

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

如何保护 WebUI 不被他人访问

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

更多

  • 接口文档：WebUI 后端 REST API 参考见 接口文档。
  • 部署流程：从零部署请参阅 快速开始。
  • 配置指南：.env 与 Config.toml 全部配置项见 配置指南。