Minecraft UniBot 文档

简体中文

English

简体中文

English

外观

架构设计

复制页面

约 1412 字大约 5 分钟

UniBot 采用 NoneBot2 事件驱动 架构，核心框架与扩展体系分离，职责清晰。

整体架构

nonebot2 核心# 异步事件驱动框架

nonebot-adapter-minecraft# Minecraft WebSocket 通信

nonebot-plugin-alconna# 跨平台命令解析

nonebot-plugin-uninfo# 统一会话信息

Plugins

Scripts

Extensions# 扩展包（本地 / 市场）

WebUi# Vue 3 管理面板前端

通信流程

核心机制

事件驱动

机器人基于 NoneBot2 的事件驱动模型。Plugins/Events.py 作为事件处理中枢，接收来自 MC 适配器的服务器事件（玩家加入/离开、聊天、死亡等），并分发到对应的同步逻辑。

管理器单例

所有管理器采用 单例模式，在文件底部实例化，通过 Scripts/Managers/__init__.py 统一导出：

  • data_manager：数据持久化（玩家、服务器、用户数据）
  • server_manager：服务器连接管理
  • plugin_manager：插件管理
  • version_manager：版本管理
  • webui_manager：WebUI 资源管理
  • config_manager：配置管理
  • task_center：后台任务中心（依赖同步、市场安装、热重载等统一登记与进度推送）

双入口启动

  • Bot.py：初始化 NoneBot、注册适配器、加载插件、加载扩展、构建指令、挂载 WebUI，然后运行。
  • Watchdog.py：守护进程，启动 Bot.py 子进程，监控异常退出并自动重启，并处理 WebUI 重启请求与版本更新后的重启（依赖同步由 Bot 进程内的任务中心执行）。

日常使用推荐 Watchdog.py：机器人异常退出会自动重启，还能处理 WebUI 的重启请求。

加载时序

机器人在启动时按以下顺序完成初始化：

  1. 初始化配置管理器，注册各平台适配器。
  2. 加载 NoneBot 插件（通用生态插件）。
  3. 加载扩展：发现、校验、拓扑排序、导入绑定、注册能力。
  4. 构建指令：统一校验并构建全部指令匹配器（内置 + 扩展）。
  5. 运行 NoneBot 主循环。

指令构建必须在全部指令声明完成后一次性提交；任一指令定义、参数或处理器校验失败时，不得注册部分匹配器。

扩展系统

扩展系统是 UniBot 的原生能力框架，与 NoneBot 插件体系严格分离。扩展可以完整访问内部能力（配置、管理器、渲染与消息工具），并通过声明式注册向框架暴露指令、服务、渲染引擎、模板与资源。详见 扩展系统。

UniBot 底层完整保留 NoneBot2 生态：NB 插件商店中的现成插件可无缝接入，与原生扩展协同工作。

核心组件：

  • Loader：扫描 Extensions/ 目录，解析清单，建立依赖图并拓扑排序，导入并绑定扩展实例。
  • ExtensionManager：扩展注册表与状态管理（enabled / disabled / blocked / failed）。
  • CommandManager：统一收集指令定义，校验后构建 Alconna 匹配器。
  • ServiceRegistry：服务注册与获取。
  • RendererManager：渲染引擎、模板与资源的统一编排入口。

图片渲染

渲染系统由三个正交层次构成：渲染引擎（将页面渲染为图片）、模板（提供版式）与资源（提供静态素材）。RendererManager 作为唯一编排入口，完成「选择模板 → 注入配置与资源函数 → 渲染页面 → 委托渲染引擎成图」的完整流程，详见 扩展系统。

数据持久化

Data/ 目录下以 JSON 格式存储玩家、服务器、用户数据，通过 data_manager 管理，UTF-8 编码。

安全设计

  • JWT 认证：access_token（2h）与 refresh_token（7d）通过 HttpOnly Cookie 下发。
  • get_current_user 优先读取 Cookie，fallback 到 Authorization: Bearer Header。
  • WebSocket 认证通过 Cookie 自动携带。
  • 前端 fetch 启用 credentials: 'include'。