OpenQQAuth
基于 QQ 的 Minecraft 登录与账号认证系统 —— 一个开源的 MQE 替代方案及更多。
OpenQQAuth 运行在 Velocity 代理上:玩家被隔离在一个图形化的认证门后(对话框屏幕、虚拟箱子菜单、虚拟铁砧——适配所有协议版本),直到其身份得到验证,随后才被放行至后端的 Paper 服务器。它使用 QQ 作为每个账号强制的所有权凭证,并支持三种登录方式:
- 离线密码登录 — 在虚拟铁砧中输入密码
- 正版快速登录 — 加密握手 + hasJoined 验证,绑定 QQ 后免密
- 基岩版登录 — Microsoft 账号身份(Floodgate),绑定 QQ 后免密,并可继承 Java 版账号的数据
此外,它还引入了 登录令牌(Login Token) 系统:安装 Fabric / NeoForge 双平台模组后,玩家可以在多人游戏界面点击 “Connect with Token”,并输入由 QQ 群机器人私发的凭证以即时免密进入(有效期 30 天,可撤销)。
域名术语表:CONTEXT.md · 架构决策:docs/adr/ · 规范:.scratch/qqauth/spec.md · 外部 API 研究:.scratch/qqauth/api-reference.md
目录
功能特性
- 门禁机制:未验证的连接被限制在登录界面,直到通过认证,然后才被释放到后端服务器
- 图形化认证 UI:对话框屏幕(1.21.6+)和虚拟箱子菜单(旧版本)用于选择登录方式;密码输入始终使用虚拟铁砧(打开 / 重命名 / 左键确认 / 右键清除 / 灰色混凝土重置)
- 全协议版本支持:铁砧数据包和物品序列化按协议族参数化(Legacy 1.7.2
1.12.2 / Flat 1.131.14.4 / Classic NBT 1.151.20.4 / Components 1.20.51.21.1 / Menu Refactor 1.21.2~1.21.5 / Dialog 1.21.6+),重命名传输分离(≤1.12.2 插件频道 / 1.13+ 重命名数据包)
- 三种登录方式:离线密码、正版快速登录(加密握手 + hasJoined 双重检查)、以及免密的基岩版登录
- QQ 绑定:验证码流程(游戏内获取代码 → 在群组中发送
bind <code>;发送者 QQ 必须与目标 QQ 匹配,防止验证码截获)
- 正版绑定:点击聊天提示触发,正版会话 + QQ 验证码作为双因素认证;基于
premiumUuid 的匹配可抵御改名攻击;/opa bindpremium 用于跨名称绑定;防冒充保护(拒绝已绑定正版的名称进行离线登录 + 防止创建傀儡账号)
- 基岩版支持:Floodgate 检测、Cumulus 表单绑定、
/opa bindxbox 继承绑定(共享 Java 版账号的位置/背包),Java/基岩版互斥,/opa unbindxbox 恢复独立身份
- 快速登录:在线 ≥10 分钟后,30 分钟内同 IP 重连免密(每窗口一次);触发时通知 QQ(“不是你?回复 freeze”,可切换)
- 登录令牌:在群组中发送
获取凭证 → 机器人私发凭证 → 模组端 “Connect with Token”;有效期 30 天,可撤销;防重放保护(一次性 nonce 挑战响应)
- 来自 QQ 的远程自助管理与运维:
kick / freeze / unfreeze / ban / unban / list / status / check / exec / reload / reconnect
- 自愿转移:当发生名称冲突时,原所有者解绑 → 管理员通过
transfer confirm 确认 → 目标接管(ADR-0007,无强制接管路径)
- 域事件:发布
PlayerAuthenticatedEvent / AccountBoundEvent / AccountFrozenEvent / AccountBannedEvent,供其他插件通过 Bukkit ServicesManager 使用
- 只读 API:
ReadOnlyAuthApi 供 Paper 侧插件使用(经济 / 领地主张 / 白名单集成)
- 聊天同步:可选的双向群组 ↔ 游戏内聊天转发
- 国际化 (i18n):双语消息(zh_CN / en_US),完整的翻译键覆盖
- 安全性:密码哈希(jBCrypt),失败尝试锁定(5 次尝试 / 1 分钟),每 IP 会话限制,绑定速率限制,会话超时,防重放保护,所有管理操作的审计日志
| 模块 |
描述 |
core |
所有核心逻辑:账户 / 验证码 / 状态机 / 登录流程 / Token / 事件总线 / 命令框架,平台无关 |
bootstrap/velocity |
Velocity 代理插件:网关、虚拟窗口 UI、协议族编解码器、OneBot 接入、模组登录查询 |
bootstrap/paper |
Paper 插件:只读 API 暴露(Bukkit ServicesManager)、领域事件订阅示例 |
bootstrap/bukkit / bungeecord |
模板兼容性骨架(仅加载占位符) |
bootstrap/fabric + bootstrap/neoforge |
双平台 jar:客户端“使用 Token 连接”UI 及 Token 传输,服务端占位符 |
build-logic |
Gradle 约定插件(统一的 Java/Kotlin 编译、checkstyle、spotless) |
环境要求
- Java 21(构建与运行)
- Gradle 9.6.1(系统安装;本项目不使用 Gradle Wrapper)
- Velocity 代理(生产环境的登录网关宿主)
- 一个 OneBot 11 实现(例如 NapCat / go-cqhttp),通过 WebSocket 连接
- Paper 服务器(后端)
- 可选:Floodgate / Geyser(基岩版支持)、Fabric / NeoForge 客户端模组(Token 登录)
快速开始
1. 构建
gradle --no-daemon :bootstrap:velocity:build # Velocity 插件
gradle --no-daemon :bootstrap:paper:build # Paper 插件
gradle --no-daemon :bootstrap:fabric:build :bootstrap:neoforge:build # 模组双平台 jar
构建产物位于各模块的 build/libs/ 目录下。
2. 安装
- 将 Velocity 插件 jar 放入
velocity/plugins/,将 Paper 插件 jar 放入 paper/plugins/
- 启动 Velocity 一次以生成默认的
config.yml,然后根据需要进行编辑(参见配置参考)
- 配置 QQ 机器人(OneBot 11 WebSocket):设置
qq-bot.ws-url 和 qq-bot.ws-token,并将管理员 QQ 号添加到 qq-bot.admin-qqs
- 重启 Velocity;在群聊中发送
reload 或作为管理员执行 /opa reload 以热重载配置
3. 最小可用配置
config-version: 1
qq-bot:
ws-url: "ws://127.0.0.1:6700" # OneBot WebSocket 端点
ws-token: "" # 访问令牌(如果启用了认证)
admin-qqs: # 管理员 QQ 列表
- "10001"
login:
max-failed-attempts: 5 # 密码锁定阈值
lockout-minutes: 1 # 锁定持续时间(分钟)
storage:
driver: sqlite
sqlite-file: openqqauth.db
配置参考
所有配置均位于 Velocity 插件目录下的 config.yml 中(QqAuthConfiguration,通过 Configurate 加载)。
qq-bot (OneBot)
| 键 |
默认值 |
描述 |
qq-bot.ws-url |
ws://127.0.0.1:6700 |
OneBot 11 WebSocket 端点 |
qq-bot.ws-token |
"" |
访问令牌 |
qq-bot.admin-qqs |
[] |
管理员 QQ 列表(拥有 ADMIN 权限) |
accounts
| 键 |
默认值 |
描述 |
accounts.per-qq-limit |
3 |
单个 QQ 可绑定的最大账户数 |
login
| 键 |
默认值 |
描述 |
login.fast-login-window |
30 |
快速登录窗口(分钟):免密重连的时间跨度 |
login.fast-login-min-online-minutes |
10 |
触发快速登录所需的最小在线时长(分钟) |
login.fast-login-notify-qq |
true |
触发快速登录时通知已绑定的 QQ |
login.max-failed-attempts |
5 |
密码尝试失败后的锁定阈值 |
login.lockout-minutes |
1 |
锁定持续时间(分钟) |
login.max-sessions-per-ip |
3 |
每个 IP 的最大并发会话数(超出部分将被拒绝) |
login.bind-frequency-per-minute |
3 |
绑定频率限制(每分钟) |
login.session-timeout-seconds |
300 |
会话超时踢出时间(秒) |
login.bind-timeout-seconds |
180 |
绑定流程超时时间(秒) |
login.inherit-bind-window-minutes |
5 |
基岩版继承绑定窗口期(分钟) |
login.max-name-length |
30 |
最大改名输入长度 |
verify-code
| 键 |
默认值 |
描述 |
verify-code.length |
4 |
验证码长度 |
verify-code.expire-seconds |
180 |
验证码有效期(秒) |
token
| 键 |
默认值 |
描述 |
token.enabled |
true |
启用 Token 登录路径 |
token.ttl-days |
30 |
Token 有效期(天) |
sync-groups (聊天同步)
| 键 |
默认值 |
描述 |
sync-groups.enabled |
false |
启用消息同步 |
sync-groups.group-ids |
[] |
参与同步的群 ID |
sync-groups.game-to-group |
true |
游戏内 → 群聊转发 |
sync-groups.group-to-game |
true |
群聊 → 游戏内转发 |
sync-groups.merge-window-seconds |
5 |
合并窗口期(秒) |
sync-groups.max-forwards-per-minute |
10 |
每分钟最大转发次数 |
storage
| 键 |
默认值 |
描述 |
storage.driver |
sqlite |
存储驱动(目前仅支持 SQLite) |
storage.sqlite-file |
openqqauth.db |
SQLite 数据库文件路径 |
premium (正版检测)
| 键 |
默认值 |
描述 |
premium.enabled |
true |
启用正版检测 |
premium.name-query-cache-hours |
24 |
名称→UUID 查询缓存持续时间(小时) |
premium.http-timeout-seconds |
5 |
Mojang API 超时时间(秒) |
premium.rate-limit-per-window |
600 |
限流窗口内的最大查询次数 |
premium.rate-limit-window-minutes |
10 |
限流窗口持续时间(分钟) |
premium.bind-wait-minutes |
5 |
正版绑定等待标记持续时间(分钟) |
QQ 群指令
指令由 QQ 群机器人接收。权限层级:参见权限模型。
玩家自助服务 (BOUND_MEMBER)
| 指令 |
说明 |
kick |
踢出发送者的所有在线账号(自助服务,用于应对异常登录) |
freeze |
冻结发送者的账号(临时状态,可自行解除) |
unfreeze |
解冻发送者的账号 |
status |
显示发送者的账号信息及验证状态 |
list |
显示在线列表 |
获取凭证 |
为发送者的账号签发新的登录令牌并私聊发送(重新签发会覆盖旧令牌) |
吊销凭证 [<account>] |
立即撤销发送者账号的所有令牌 |
验证码指令(群内确认)
| 指令 |
说明 |
bind <code> |
确认 QQ 绑定(屏幕显示的验证码) |
重置 <code> |
确认密码重置(由铁砧中的灰色混凝土触发) |
解绑正版 <code> |
解绑正版身份 |
解绑基岩 <code> |
解绑基岩版账号(恢复独立身份) |
管理员指令 (ADMIN)
| 指令 |
说明 |
bind 1 <QQ> <player> |
强制绑定账号(随后会私聊发送令牌) |
bind 2 <QQ> |
重置账号密码(新密码将打印至控制台) |
ban @<target> [name] / unban |
封禁/解封账号(持久化,仅限管理员) |
freeze @<target> [name] / unfreeze |
冻结/解冻任意账号(临时状态,可逆) |
check |
查看任意玩家的完整信息及服务器概览 |
exec <server> <command> |
在后端服务器上执行指令(执行前后均记录审计日志) |
transfer confirm <account> <targetQQ> <premiumName> |
确认自愿转移(在所有者解绑后生效) |
transfer list |
列出待确认的转移请求 |
reload |
热重载配置 |
reconnect |
重连 QQ 机器人 |
游戏内指令
游戏内指令使用 /opa 前缀(Velocity 指令注册):
| 指令 |
说明 |
/opa bindpremium <name> |
跨名称正版绑定(正版身份接管原始离线账号) |
/opa bindxbox <name> |
启动基岩版继承绑定(基岩版账号 → 指定的 Java 版账号,共享位置/物品栏) |
/opa unbindxbox |
解绑基岩版继承(恢复独立身份,数据保留) |
/opa reload |
热重载配置(管理员) |
登录与绑定流程
新玩家(离线)
- 加入服务器 → 被网关拦截,直接进入 QQ 绑定流程
- 输入你的 QQ 号 → 游戏屏幕上显示验证码
- 在 QQ 群中发送
bind <code>(发送者 QQ 必须与输入的 QQ 一致 — 防止抢注)
- 绑定成功 → 在铁砧中设置密码(两次确认输入)→ 释放进入服务器
回归玩家(离线)
- 在登录界面选择“离线” → 在铁砧中输入密码 → 验证通过后释放
- 忘记密码:点击铁砧中的灰色混凝土开始重置 → 设置新密码 → 在群中用
重置 <code> 确认
正版玩家
- 当名称匹配到正版账号时,聊天栏会显示“检测到 [id] 拥有正版账号 — 是否绑定?”
- 点击提示 → 被踢出,提示“请使用正版客户端加入”
- 使用正版客户端重连 → 加密握手 + hasJoined 验证 → 在群中发送
绑定正版 <code> 以完成 QQ 二次验证
- 绑定后,正版登录无需密码(通过
premiumUuid 匹配账号并重写身份;名称更改不影响)
- 同一人使用不同名称:使用
/opa bindpremium 进行手动跨名称绑定
基岩版玩家 (Floodgate)
- Floodgate 检测到基岩版连接 → 跳过 Java 版登录界面,直接使用 Cumulus 表单输入 QQ 号
- 在群中发送
bind <code> 确认 → 绑定并释放(无需密码)
/opa bindxbox: 将基岩版账号继承绑定至 Java 版账号(共享位置/物品栏),Java/基岩版互斥在线
/opa unbindxbox 或在群中使用 解绑基岩: 恢复独立身份(在 QQ 账号限额下保留数据)
快速登录
- 重连时:30 分钟内相同 IP,且之前在线 ≥10 分钟 → 免密自动释放(每个窗口期仅一次)
- 触发时的 QQ 通知:“账号 <name> 刚刚通过快速登录加入 — 不是你?回复 freeze”(可通过
fast-login-notify-qq 开关切换)
登录令牌 (mod)
给玩家
- 在 QQ 群中发送
获取凭证 → 机器人私聊发送一个 30 天有效的令牌
- 启动安装了 OpenQQAuth mod 的客户端(Fabric 或 NeoForge)
- 在多玩家屏幕右下角点击 “Connect with Token” → 输入令牌 → 连接
- 服务器验证后免密释放你;如果令牌泄露,可随时使用
吊销凭证 撤销
工作原理
- 在登录阶段,令牌通过 mod 通道 (
openqqauth:token) 发送;Velocity 端运行 128 位随机 nonce 挑战响应以防止重放攻击
- 验证 (
TokenLoginChecker):令牌 + 账号绑定 + 未过期 + 未撤销 → 命中则免密释放
- 令牌检查失败永远不会阻塞密码路径(玩家停留在密码输入界面)
- 非 mod(原版)客户端不受影响,照常使用密码登录
- 可选本地明文令牌存储 (
save-token 开关;禁用时清除)
聊天同步
启用 sync-groups.enabled 时:
- 群消息 → 游戏内聊天 (
group-to-game)
- 游戏内聊天 → 群 (
game-to-group)
- 游戏内使用
/opa at @ 群成员,使用 /opa re 回复群消息
权限模型
| 层级 |
含义 |
获取方式 |
ANY |
任何群成员 |
默认 |
BOUND_MEMBER |
已绑定账号的玩家 |
完成 QQ 绑定 |
ADMIN |
管理员 |
设置 qq-bot.admin-qqs |
管理员指令 (bind / ban / exec / check / transfer / reload / reconnect 等) 在执行前后均写入 CommandAuditLog。
从源码构建
# 完整构建:编译 + 测试 + checkstyle + spotless
gradle --no-daemon build
# 编译单个模块
gradle --no-daemon :core:compileJava
gradle --no-daemon :bootstrap:velocity:compileJava
gradle --no-daemon :bootstrap:paper:compileJava
gradle --no-daemon :bootstrap:fabric:compileJava
gradle --no-daemon :bootstrap:neoforge:compileJava
# 运行模块测试
gradle --no-daemon :core:test
gradle --no-daemon :bootstrap:velocity:test
# 代码风格检查
gradle --no-daemon :core:checkstyleMain :core:spotlessCheck
需要系统安装的 Gradle 9.6.1(不使用 Wrapper)。建议构建内存为 -Xmx2G(参见 gradle.properties)。
支持的版本
客户端 Minecraft 版本(协议族)
| 协议族 |
MC 版本 |
协议号 |
支持情况 |
| Legacy |
1.7.2 ~ 1.12.2 |
4 ~ 340 |
✅ 已承诺支持 1.12.2;1.7.2~1.12.1 为理论下限,未正式承诺(存在包 ID 漂移问题) |
| Flat |
1.13 ~ 1.14.4 |
393 ~ 498 |
⚠️ 已在 1.14.4 上校准;更早的 1.13 子版本未承诺支持 |
| Classic NBT |
1.15 ~ 1.20.4 |
573 ~ 765 |
✅ |
| Components |
1.20.5 ~ 1.21.1 |
766 ~ 767 |
✅ |
| Menu Refactor |
1.21.2 ~ 1.21.5 |
768 ~ 770 |
✅ |
| Dialog |
1.21.6 ~ latest (26.2) |
771+ |
✅ |
结论:从 1.12.2 到最新版本(26.2)的客户端均可登录。 UI 会根据版本自动分发:1.21.6+ 使用对话框界面,旧版本使用虚拟箱子菜单,并在所有地方提供用于输入密码的虚拟铁砧(重命名机制拆分:≤1.12.2 使用插件频道 / 1.13+ 使用重命名数据包;物品序列化:NBT ≤1.20.4 / 数据组件 ≥1.20.5)。
运行时要求
| 端 |
版本 |
| Velocity 代理 |
Velocity API 3.5.0-SNAPSHOT (Velocity 3.3.x 系列), Java 21 |
| Java |
21 |
| Paper 服务器 |
该 Velocity 版本所代理的任何版本 |
| Gradle |
9.6.1(仅构建时使用) |
| 模组端(令牌登录) |
Fabric (fabric-loom 1.17.9) / NeoForge (ModDevGradle 2.0.141), 目标 MC 26.1.2(构建基线) |
已知限制
- 1.7.2~1.12.1:Legacy 常量表存在,但此范围标记为“理论下限,未正式承诺”——可能会出现包 ID 漂移;生产环境推荐最低版本为 1.12.2
- 模组令牌端:构建基线为 MC 26.1.2;支持其他 MC 版本需要在构建配置中更改
minecraft = "26.1.2" 并重新构建
- 真实的 Velocity 连接布线:针对旧协议族 (<770) 的 ServerboundPacketHandler 桥接是后续待办事项;已在模拟层验证通过
开发指南
- 问题与规范:
.scratch/<feature>/(规范 + 编号工单),参见 docs/agents/issue-tracker.md
- 分类标签:
needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix,参见 docs/agents/triage-labels.md
- 领域术语表:
CONTEXT.md(账户 / QQ / 绑定 / 网关 / 登录界面 / 正版绑定 / 继承绑定等)
- 架构决策记录:
docs/adr/0001~0008(虚拟铁砧网关、离线正版检测、OneBot 11、登录界面分层、登录令牌、固定账户键、名称冲突、快速登录信任模型)
- 协作规范:参见
CLAUDE.md(worktree 隔离、影响范围验证、按工单提交、并发上限)
核心源码结构
core/src/main/java/dev/nmouzh/openqqauth/
├── account/ # 账户模型, SQLite 仓库
├── anvil/ # 铁砧窗口状态机 (UI 无关的核心逻辑)
├── api/ # 只读查询 API (供 Paper 插件使用)
├── bedrock/ # 基岩版支持 (表单发送器, 绑定流程)
├── configuration/# 配置模型 (Configurate)
├── event/ # 领域事件总线 (SimpleDomainEventBus)
├── gate/ # LoginPipeline, 会话, 锁定, 快速登录
├── i18n/ # TranslationKey 枚举 + 双语资源
├── mojang/ # Mojang API 客户端 (name→UUID, hasJoined)
├── onebot/ # OneBot 11 客户端 (WebSocket 消息)
├── password/ # 密码哈希 (jBCrypt)
├── qq/ # QQ 领域:绑定/重置/解绑状态机, 群命令, 审计日志, 自愿转移
├── token/ # 登录令牌:发放/撤销/验证, 传输协议, 模组频道
├── util/ # 工具类
└── verify/ # 验证码服务
常见问题
Q:“机器人离线” — 无法绑定?
A:新玩家绑定时会检查机器人的在线状态 (BotOnlineProvider);当机器人离线时,绑定操作将降级为提示 + 踢出。请确认 OneBot 连接(reconnect 可重连)。
Q:旧客户端如 1.12.2 无法登录?
A:铁砧协议和物品序列化已针对支持 Legacy 范围的协议族进行了参数化处理(理论下限 1.7.2,1.12.2 已承诺支持)。更早的 1.13 子版本和 1.7.2~1.12.1 的包 ID 漂移属于“未正式承诺”;真实的 Velocity 连接布线(内部 MinecraftConnection 桥接)是单独的后续待办事项。
Q:如果令牌验证失败会发生什么?
A:它不会阻塞密码路径——失败仅会被记录,玩家仍停留在密码界面并可正常登录。
Q:其他插件如何读取账户信息?
A:在 Paper 上,通过 Bukkit ServicesManager 获取 ReadOnlyAuthApi(账户/会话查询),并订阅领域事件(PlayerAuthenticatedEvent 等)。参见 bootstrap/paper 中的 PaperAuthEvents 以获取集成示例。
Q:数据存储在哪里?
A:默认存储在 SQLite 文件 openqqauth.db 中(storage.sqlite-file 可配置)。
Q:如何处理名称冲突?
A:根据 ADR-0007(“过去先来先得,未来正版优先”):冲突方可以使用自愿转移(所有者解绑 → 管理员 transfer confirm → 目标接管)。系统不提供强制接管路径。
许可证
本项目采用 CC0 1.0 Universal 许可证授权 —— 您可以随意使用,包括为您的项目重新许可。
OpenQQAuth
QQ-driven login & account authentication system for Minecraft — an open-source MQE alternative and beyond.
OpenQQAuth runs on the Velocity proxy: players are isolated behind a graphical authentication gate (dialog screens, virtual chest menu, virtual anvil — adapted across every protocol generation) until their identity is verified, then released to the backend Paper server. It uses QQ as the mandatory ownership credential for every account and supports three login methods:
- Offline password login — enter your password in the virtual anvil
- Premium fast login — encrypted handshake + hasJoined verification, passwordless once bound to QQ
- Bedrock login — Microsoft account identity (Floodgate), passwordless after QQ binding, with optional inheritance of a Java account's data
It also adds a login token system: after installing the Fabric / NeoForge dual-platform mod, players can click "Connect with Token" in the multiplayer screen and enter a credential privately sent by the QQ group bot for instant passwordless entry (30-day validity, revocable).
Domain glossary: CONTEXT.md · Architecture decisions: docs/adr/ · Spec: .scratch/qqauth/spec.md · External API research: .scratch/qqauth/api-reference.md
Table of Contents
Features
- Gate: unverified connections are confined to the login screen until authenticated, then released to the backend server
- Graphical authentication UI: dialog screens (1.21.6+) and virtual chest menus (older versions) for login-method selection; password entry always uses a virtual anvil (open / rename / left-click confirm / right-click clear / gray concrete to reset)
- Full protocol-generation support: anvil packets and item serialization are parameterized per protocol family (Legacy 1.7.2
1.12.2 / Flat 1.131.14.4 / Classic NBT 1.151.20.4 / Components 1.20.51.21.1 / Menu Refactor 1.21.2~1.21.5 / Dialog 1.21.6+), with rename-transport split (≤1.12.2 plugin channel / 1.13+ rename packet)
- Three login methods: offline password, premium fast login (encrypted handshake + hasJoined double check), and passwordless Bedrock
- QQ binding: verification-code flow (in-game code → send
bind <code> in the group; sender QQ must match the target QQ, preventing code sniping)
- Premium binding: clickable chat hint to trigger, premium session + QQ verification code as two factors;
premiumUuid-based matching survives name changes; /opa bindpremium for cross-name binding; impersonation protection (reject offline logins on premium-bound names + anti-sockpuppet account creation)
- Bedrock support: Floodgate detection, Cumulus form binding,
/opa bindxbox inheritance binding (share a Java account's location/inventory), Java/Bedrock mutual exclusivity, /opa unbindxbox to restore an independent identity
- Fast login: same-IP reconnect within 30 minutes after ≥10 minutes online is passwordless (once per window); QQ notification on trigger ("not you? reply freeze", toggleable)
- Login tokens:
获取凭证 in the group → bot sends a credential privately → mod-side "Connect with Token"; 30-day validity, revocable; replay-protected (one-time nonce challenge-response)
- Remote self-service & administration from QQ:
kick / freeze / unfreeze / ban / unban / list / status / check / exec / reload / reconnect
- Voluntary transfer: on name conflict, the original owner unbinds → admin confirms via
transfer confirm → target takes over (ADR-0007, no forced takeover path)
- Domain events:
PlayerAuthenticatedEvent / AccountBoundEvent / AccountFrozenEvent / AccountBannedEvent published for other plugins via Bukkit ServicesManager
- Read-only API:
ReadOnlyAuthApi for Paper-side plugins (economy / land claims / whitelist integrations)
- Chat sync: optional bidirectional group ↔ in-game chat forwarding
- i18n: bilingual messages (zh_CN / en_US) with full translation-key coverage
- Security: password hashing (jBCrypt), failed-attempt lockout (5 tries / 1 min), per-IP session limits, bind rate limiting, session timeouts, replay protection, audit log for all admin operations
Architecture
┌──────────────┐ ┌──────────────────────────────┐ ┌──────────────┐
│ Minecraft │────▶│ Velocity (OpenQQAuth gate) │────▶│ Paper server │
│ client │ │ dialog/chest/anvil auth UI │ │ (API/events) │
└──────────────┘ │ LoginPipeline decision core │ └──────────────┘
│ handshake/premium/Bedrock │
└──────────────┬───────────────┘
│ OneBot (WebSocket)
┌──────────────▼───────────────┐
│ QQ group bot (bind/admin) │
└──────────────────────────────┘
| Module |
Description |
core |
All domain logic: accounts / verify codes / state machines / login pipeline / tokens / event bus / command framework, platform-independent |
bootstrap/velocity |
Velocity proxy plugin: gate, virtual window UI, protocol-family codecs, OneBot wiring, mod login queries |
bootstrap/paper |
Paper plugin: read-only API exposure (Bukkit ServicesManager), domain-event subscription example |
bootstrap/bukkit / bungeecord |
Template compatibility skeletons (load-placeholder only) |
bootstrap/fabric + bootstrap/neoforge |
Dual-platform jar: client-side "Connect with Token" UI & token transport, server-side placeholder |
build-logic |
Gradle convention plugins (unified Java/Kotlin compile, checkstyle, spotless) |
Requirements
- Java 21 (build & run)
- Gradle 9.6.1 (system-installed; this project does not use the Gradle wrapper)
- Velocity proxy (the production login-gate host)
- An OneBot 11 implementation (e.g. NapCat / go-cqhttp) over WebSocket
- Paper server (backend)
- Optional: Floodgate / Geyser (Bedrock support), Fabric / NeoForge client mod (token login)
Quick Start
1. Build
gradle --no-daemon :bootstrap:velocity:build # Velocity plugin
gradle --no-daemon :bootstrap:paper:build # Paper plugin
gradle --no-daemon :bootstrap:fabric:build :bootstrap:neoforge:build # mod dual-platform jar
Artifacts land in each module's build/libs/.
2. Install
- Put the velocity plugin jar in
velocity/plugins/, the paper jar in paper/plugins/
- Start Velocity once to generate the default
config.yml, then edit as needed (see Configuration Reference)
- Configure the QQ bot (OneBot 11 WebSocket): set
qq-bot.ws-url and qq-bot.ws-token, and add admin QQs to qq-bot.admin-qqs
- Restart Velocity; send
reload in the group or run /opa reload as an admin to hot-reload config
3. Minimal working configuration
config-version: 1
qq-bot:
ws-url: "ws://127.0.0.1:6700" # OneBot WebSocket endpoint
ws-token: "" # access token (if auth enabled)
admin-qqs: # admin QQ list
- "10001"
login:
max-failed-attempts: 5 # password lockout threshold
lockout-minutes: 1 # lockout duration (minutes)
storage:
driver: sqlite
sqlite-file: openqqauth.db
Configuration Reference
All configuration lives in config.yml in the Velocity plugin directory (QqAuthConfiguration, loaded via Configurate).
qq-bot (OneBot)
| Key |
Default |
Description |
qq-bot.ws-url |
ws://127.0.0.1:6700 |
OneBot 11 WebSocket endpoint |
qq-bot.ws-token |
"" |
Access token |
qq-bot.admin-qqs |
[] |
Admin QQ list (ADMIN permission) |
accounts
| Key |
Default |
Description |
accounts.per-qq-limit |
3 |
Max accounts bindable to a single QQ |
login
| Key |
Default |
Description |
login.fast-login-window |
30 |
Fast-login window (minutes): passwordless reconnect time span |
login.fast-login-min-online-minutes |
10 |
Prior online time required to trigger fast login (minutes) |
login.fast-login-notify-qq |
true |
Notify the bound QQ when fast login triggers |
login.max-failed-attempts |
5 |
Password lockout threshold |
login.lockout-minutes |
1 |
Lockout duration (minutes) |
login.max-sessions-per-ip |
3 |
Max concurrent sessions per IP (excess rejected) |
login.bind-frequency-per-minute |
3 |
Bind rate limit (per minute) |
login.session-timeout-seconds |
300 |
Session timeout kick (seconds) |
login.bind-timeout-seconds |
180 |
Binding flow timeout (seconds) |
login.inherit-bind-window-minutes |
5 |
Bedrock inheritance-binding window (minutes) |
login.max-name-length |
30 |
Max rename input length |
verify-code
| Key |
Default |
Description |
verify-code.length |
4 |
Verification code length |
verify-code.expire-seconds |
180 |
Verification code validity (seconds) |
token
| Key |
Default |
Description |
token.enabled |
true |
Enable the token login path |
token.ttl-days |
30 |
Token validity (days) |
sync-groups (chat sync)
| Key |
Default |
Description |
sync-groups.enabled |
false |
Enable message sync |
sync-groups.group-ids |
[] |
Group IDs participating in sync |
sync-groups.game-to-group |
true |
In-game → group forwarding |
sync-groups.group-to-game |
true |
Group → in-game forwarding |
sync-groups.merge-window-seconds |
5 |
Merge window (seconds) |
sync-groups.max-forwards-per-minute |
10 |
Max forwards per minute |
storage
| Key |
Default |
Description |
storage.driver |
sqlite |
Storage driver (SQLite currently) |
storage.sqlite-file |
openqqauth.db |
SQLite database file path |
premium (premium detection)
| Key |
Default |
Description |
premium.enabled |
true |
Enable premium detection |
premium.name-query-cache-hours |
24 |
Name→UUID query cache duration (hours) |
premium.http-timeout-seconds |
5 |
Mojang API timeout (seconds) |
premium.rate-limit-per-window |
600 |
Max queries per rate-limit window |
premium.rate-limit-window-minutes |
10 |
Rate-limit window (minutes) |
premium.bind-wait-minutes |
5 |
Premium binding wait-marker duration (minutes) |
QQ Group Commands
Commands are received by the QQ group bot. Permission tiers: see Permission Model.
Player self-service (BOUND_MEMBER)
| Command |
Description |
kick |
Kick all online accounts of the sender (self-service against abnormal logins) |
freeze |
Freeze the sender's accounts (temporary, self-reversible) |
unfreeze |
Unfreeze the sender's accounts |
status |
Show the sender's account info & verification state |
list |
Show the online list |
获取凭证 |
Issue a new login token for the sender's account and send it privately (re-issuing overrides the old one) |
吊销凭证 [<account>] |
Immediately revoke the tokens of the sender's accounts |
Verification-code commands (in-group confirmation)
| Command |
Description |
bind <code> |
Confirm QQ binding (code shown on the in-game screen) |
重置 <code> |
Confirm password reset (started from the gray concrete in the anvil) |
解绑正版 <code> |
Unbind the premium identity |
解绑基岩 <code> |
Unbind the Bedrock account (restore independent identity) |
Admin commands (ADMIN)
| Command |
Description |
bind 1 <QQ> <player> |
Force-bind an account (a token is then sent privately) |
bind 2 <QQ> |
Reset an account's password (new password printed to console) |
ban @<target> [name] / unban |
Ban / unban an account (persistent, admin-only) |
freeze @<target> [name] / unfreeze |
Freeze / unfreeze any account (temporary, reversible) |
check |
View any player's full info & server overview |
exec <server> <command> |
Run a command on the backend server (audit-logged before/after) |
transfer confirm <account> <targetQQ> <premiumName> |
Confirm a voluntary transfer (after the owner unbinds) |
transfer list |
List pending transfer confirmations |
reload |
Hot-reload configuration |
reconnect |
Reconnect the QQ bot |
In-Game Commands
In-game commands use the /opa prefix (Velocity command registration):
| Command |
Description |
/opa bindpremium <name> |
Cross-name premium binding (premium identity takes over the original offline account) |
/opa bindxbox <name> |
Start Bedrock inheritance binding (Bedrock account → specified Java account, sharing location/inventory) |
/opa unbindxbox |
Unbind Bedrock inheritance (restore independent identity, data kept) |
/opa reload |
Hot-reload configuration (admin) |
Login & Binding Flows
New player (offline)
- Join the server → intercepted by the gate, enters the QQ binding flow directly
- Enter your QQ number → the in-game screen shows a verification code
- Send
bind <code> in the QQ group (sender QQ must match the entered QQ — anti-sniping)
- Binding succeeds → create a password in the anvil (two confirmation inputs) → released into the server
Returning player (offline)
- Select "offline" on the login screen → enter your password in the anvil → verified and released
- Forgot your password: click the gray concrete in the anvil to start a reset → set a new password → confirm with
重置 <code> in the group
Premium player
- When the name matches a premium account, the chat shows "detected [id] has a premium account — bind?"
- Click the hint → kicked with "use a premium client to join"
- Reconnect with the premium client → encrypted handshake + hasJoined verification → send
绑定正版 <code> in the group to complete the QQ second factor
- After binding, premium logins are passwordless (account matched by
premiumUuid with identity rewrite; name changes don't matter)
- Same person with a different name:
/opa bindpremium for manual cross-name binding
Bedrock player (Floodgate)
- Floodgate detects the Bedrock connection → skips the Java login screens, uses a Cumulus form to enter the QQ number directly
- Send
bind <code> in the group to confirm → bound and released (passwordless)
/opa bindxbox: inheritance-bind the Bedrock account to a Java account (shared location/inventory), Java/Bedrock mutually exclusive online
/opa unbindxbox or 解绑基岩 in the group: restore an independent identity (data kept while under the QQ account limit)
Fast login
- On reconnect: same IP within 30 minutes, previously online ≥10 minutes → passwordless auto-release (once per window)
- QQ notification on trigger: "account <name> just joined via fast login — not you? reply freeze" (toggleable via
fast-login-notify-qq)
Login Tokens (mod)
For players
- Send
获取凭证 in the QQ group → the bot privately sends a 30-day token
- Launch a client with the OpenQQAuth mod installed (Fabric or NeoForge)
- Click "Connect with Token" in the bottom-right of the multiplayer screen → enter the token → connect
- The server verifies and releases you passwordless; revoke at any time with
吊销凭证 if the token leaks
How it works
- During the login phase the token is sent over the mod channel (
openqqauth:token); the Velocity side runs a 128-bit random nonce challenge-response to prevent replay
- Verification (
TokenLoginChecker): token + account binding + not expired + not revoked → passwordless release on hit
- A failed token check never blocks the password path (the player stays at the password screen)
- Non-mod (vanilla) clients are unaffected and use password login as usual
- Optional local plaintext token storage (
save-token toggle; cleared when disabled)
Chat Sync
With sync-groups.enabled:
- Group messages → in-game chat (
group-to-game)
- In-game chat → group (
game-to-group)
- In-game
/opa at to @ a group member, /opa re to reply to a group message
Permission Model
| Tier |
Meaning |
How to get |
ANY |
Any group member |
Default |
BOUND_MEMBER |
Player with a bound account |
Complete QQ binding |
ADMIN |
Administrator |
Set qq-bot.admin-qqs |
Admin commands (bind / ban / exec / check / transfer / reload / reconnect, etc.) are written to the CommandAuditLog before and after execution.
Building from Source
# Full build: compile + test + checkstyle + spotless
gradle --no-daemon build
# Compile a single module
gradle --no-daemon :core:compileJava
gradle --no-daemon :bootstrap:velocity:compileJava
gradle --no-daemon :bootstrap:paper:compileJava
gradle --no-daemon :bootstrap:fabric:compileJava
gradle --no-daemon :bootstrap:neoforge:compileJava
# Run a module's tests
gradle --no-daemon :core:test
gradle --no-daemon :bootstrap:velocity:test
# Style checks
gradle --no-daemon :core:checkstyleMain :core:spotlessCheck
System-installed Gradle 9.6.1 is required (no wrapper). Build memory of -Xmx2G is recommended (see gradle.properties).
Supported Versions
Client Minecraft versions (protocol families)
| Protocol family |
MC versions |
Protocol |
Support |
| Legacy |
1.7.2 ~ 1.12.2 |
4 ~ 340 |
✅ 1.12.2 committed; 1.7.2~1.12.1 theoretical floor, not committed (packet-ID drift) |
| Flat |
1.13 ~ 1.14.4 |
393 ~ 498 |
⚠️ calibrated on 1.14.4; earlier 1.13 sub-versions not committed |
| Classic NBT |
1.15 ~ 1.20.4 |
573 ~ 765 |
✅ |
| Components |
1.20.5 ~ 1.21.1 |
766 ~ 767 |
✅ |
| Menu Refactor |
1.21.2 ~ 1.21.5 |
768 ~ 770 |
✅ |
| Dialog |
1.21.6 ~ latest (26.2) |
771+ |
✅ |
Conclusion: clients from 1.12.2 up to the latest release (26.2) can log in. The UI auto-dispatches per version: dialog screens for 1.21.6+, virtual chest menus for older versions, and a virtual anvil for password input everywhere (rename split: ≤1.12.2 plugin channel / 1.13+ rename packet; item serialization: NBT ≤1.20.4 / Data Components ≥1.20.5).
Runtime requirements
| Side |
Version |
| Velocity proxy |
Velocity API 3.5.0-SNAPSHOT (Velocity 3.3.x series), Java 21 |
| Java |
21 |
| Paper server |
any version proxied by that Velocity release |
| Gradle |
9.6.1 (build only) |
| mod side (token login) |
Fabric (fabric-loom 1.17.9) / NeoForge (ModDevGradle 2.0.141), target MC 26.1.2 (build baseline) |
Known limits
- 1.7.2~1.12.1: the Legacy constant table exists, but this range is marked "theoretical floor, not committed" — packet-ID drift may occur; 1.12.2 is the recommended minimum for production
- mod token side: the build baseline is MC 26.1.2; supporting other MC versions requires bumping
minecraft = "26.1.2" in the build config and rebuilding
- real Velocity connection wiring: ServerboundPacketHandler bridging for old families (<770) is a follow-up ticket; verified at the mock layer
Development Guide
- Issues & spec:
.scratch/<feature>/ (spec + numbered tickets), see docs/agents/issue-tracker.md
- Triage labels:
needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix, see docs/agents/triage-labels.md
- Domain glossary:
CONTEXT.md (account / QQ / bind / gate / login screen / premium binding / inheritance binding, etc.)
- Architecture decisions:
docs/adr/0001~0008 (virtual-anvil gate, offline premium detection, OneBot 11, login-screen layering, login tokens, fixed account keys, name conflict, fast-login trust model)
- Collaboration conventions: see
CLAUDE.md (worktree isolation, impact-scope verification, per-ticket commits, concurrency cap)
Core source layout
core/src/main/java/dev/nmouzh/openqqauth/
├── account/ # account model, SQLite repository
├── anvil/ # anvil window state machine (UI-agnostic core)
├── api/ # read-only query API (for Paper plugins)
├── bedrock/ # Bedrock support (form sender, bind flow)
├── configuration/# config model (Configurate)
├── event/ # domain event bus (SimpleDomainEventBus)
├── gate/ # LoginPipeline, sessions, lockout, fast login
├── i18n/ # TranslationKey enum + bilingual resources
├── mojang/ # Mojang API client (name→UUID, hasJoined)
├── onebot/ # OneBot 11 client (WebSocket messaging)
├── password/ # password hashing (jBCrypt)
├── qq/ # QQ domain: bind/reset/unbind state machines, group commands, audit log, voluntary transfer
├── token/ # login tokens: issue/revoke/verify, transport protocol, mod channel
├── util/ # utilities
└── verify/ # verification code service
FAQ
Q: "Bot offline" — can't bind?
A: New-player binding checks the bot's online state (BotOnlineProvider); when the bot is offline, binding operations degrade to a hint + kick. Confirm the OneBot connection (reconnect reconnects).
Q: Old clients like 1.12.2 can't log in?
A: The anvil protocol and item serialization are parameterized per protocol family supporting the Legacy range (theoretical floor 1.7.2, 1.12.2 committed). Earlier 1.13 sub-versions and 1.7.2~1.12.1 packet-ID drift are "not committed"; real Velocity connection wiring (internal MinecraftConnection bridging) is a separate follow-up ticket.
Q: What happens if token verification fails?
A: It never blocks the password path — the failure is only logged and the player stays at the password screen and can log in normally.
Q: How can other plugins read account info?
A: On Paper, get ReadOnlyAuthApi (account/session queries) via Bukkit ServicesManager, and subscribe to domain events (PlayerAuthenticatedEvent, etc.). See PaperAuthEvents in bootstrap/paper for an integration example.
Q: Where is data stored?
A: By default in the SQLite file openqqauth.db (storage.sqlite-file is configurable).
Q: How are name conflicts handled?
A: Per ADR-0007 ("first come, first served for the past; premium-priority for the future"): conflicting parties can use voluntary transfer (owner unbinds → admin transfer confirm → target takes over). The system provides no forced-takeover path.
License
This project is licensed under CC0 1.0 Universal — free to use however you like, including relicensing for your own projects.
评论 0
登录后参与评分
还没有评论,来抢沙发吧