BotServer + Fabric Mod 双项目支持

Minecraft QQBot 完整的群服互联生态

服务端 BotServer + 客户端 Fabric Mod
高性能 · 易配置 · 多版本支持

Minecraft Server

Fabric Mod 接入

WebSocket

BotServer

Nonebot2 驱动

QQ Group

系统架构

双项目协同工作,构建完整的群服互联生态

QQBotServer

服务端核心

  • 基于 Nonebot2 的 QQ 机器人框架
  • WebSocket 服务端,支持多服接入
  • WebUI 可视化配置界面
  • Docker 一键部署支持

QQBot Fabric

客户端模组

  • Fabric 模组,支持最新 Minecraft 版本
  • WebSocket 客户端,实时双向通讯
  • 游戏内 /qqbot 管理指令
  • 自动重连与心跳检测

BotServer

基于 Nonebot2 的 QQ 机器人服务端

多服互联

支持多个 Minecraft 服务器同时接入,消息跨服转发,统一管理。

WebUI 配置

可视化配置界面,实时修改配置,支持热重载,无需重启服务。

AI 支持

可接入 AI 功能,支持智能对话,一言卡片,戳一戳互动。

Docker 部署 (推荐)

docker-compose.yml
git clone https://github.com/IamJokerZHEN/QQBotServer_Rebuild
cd BotServer
docker-compose up -d
环境变量配置 (.env)
HOST=0.0.0.0
PORT=8000
TOKEN=your_token_here
SUPERUSERS=["your_qq"]
端口说明
  • • 8000: WebSocket 服务端口
  • • 8080: WebUI 管理界面
  • • 3000: Grafana 监控(可选)

QQBot Fabric

与 BotServer 对接的 Fabric 模组

配置文件

config/qq_bot.json 中创建配置文件:

{
  "uri": "ws://127.0.0.1:8000/",
  "name": "生存服",
  "token": "your_token",
  "reconnect_interval": 5
}

配置项说明

字段 类型 说明
uri string WebSocket 连接地址,格式 ws://host:port/
name string 服务器名称,中英文均可,显示在QQ群中
token string 验证令牌,需与 BotServer 配置一致
reconnect_interval int 断线重连间隔(秒),默认5秒

游戏内指令

/qqbot

查看 QQBot 状态信息

/qqbot reconnect

手动重连 WebSocket

/qqbot config

查看当前配置

/qqbot config uri "ws://..."

修改连接地址

/qqbot config token "xxx"

修改验证令牌

/qqbot test

测试与 BotServer 的连接

/qqbot info

查看详细的连接信息

安装步骤

  1. 下载最新版 Fabric Mod 从 Releases或者下载页
  2. 将 .jar 文件放入服务器的 mods 文件夹
  3. 启动服务器生成配置文件
  4. 编辑 config/qq_bot.json 填写 BotServer 地址
  5. 重启服务器或使用 /qqbot reconnect 连接

指令文档

QQ群指令与游戏内管理指令

Q QQ群指令

.luck 娱乐

查看今日幸运指数

.mcdr 管理

在指定服务器执行 MCDR 指令

.list 查询

查询各服务器在线玩家

.server 查询

查看服务器列表与资源占用

.bound 白名单

绑定/解绑白名单

.command 高级

发送原始指令到服务器

M 游戏内指令

/qqbot 管理员

显示状态面板

/qqbot reconnect 连接

重新连接 WebSocket

/qqbot config 配置

查看当前配置

/qqbot config uri "ws://..." 配置

修改服务器地址

/qqbot config token "xxx" 配置

修改验证令牌

/qqbot test 测试

测试连接状态

快速部署指南

三步完成群服互联搭建

1

部署 BotServer

使用 Docker Compose 快速启动服务端

git clone https://github.com/IamJokerZHEN/QQBotServer_Rebuild
cd QQBotServer_Rebuild
docker-compose up -d
• 默认端口: 8000 (WebSocket) • 默认端口: 8080 (WebUI)
2

安装 Fabric Mod

在 Minecraft 服务器中安装模组并配置连接

下载并放入 mods 文件夹
QQBot-Fabric-1.x.x.jar
config/qq_bot.json
{
  "uri": "ws://your-server:8000/",
  "token": "match-botserver"
}
3

连接与验证

启动服务并验证连接状态

检查 WebUI 状态面板
游戏内执行 /qqbot test
QQ群发送 .server 查看在线