OpenQQAuth

插件

· 作者 Nmou_Zh

适用于 Minecraft(Velocity)的 QQ 驱动登录与账户认证:支持离线、正版、基岩版和令牌登录。

0 本站下载 0 关注 更新于 3 个月前

最新 1.0.0-SNAPSHOT · 26.2 · Velocity

一键开服(送7天)

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.21.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. 安装

  1. 将 Velocity 插件 jar 放入 velocity/plugins/,将 Paper 插件 jar 放入 paper/plugins/
  2. 启动 Velocity 一次以生成默认的 config.yml,然后根据需要进行编辑(参见配置参考)
  3. 配置 QQ 机器人(OneBot 11 WebSocket):设置 qq-bot.ws-url 和 qq-bot.ws-token,并将管理员 QQ 号添加到 qq-bot.admin-qqs
  4. 重启 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 热重载配置(管理员)

登录与绑定流程

新玩家(离线)

  1. 加入服务器 → 被网关拦截,直接进入 QQ 绑定流程
  2. 输入你的 QQ 号 → 游戏屏幕上显示验证码
  3. 在 QQ 群中发送 bind <code>(发送者 QQ 必须与输入的 QQ 一致 — 防止抢注)
  4. 绑定成功 → 在铁砧中设置密码(两次确认输入)→ 释放进入服务器

回归玩家(离线)

  • 在登录界面选择“离线” → 在铁砧中输入密码 → 验证通过后释放
  • 忘记密码:点击铁砧中的灰色混凝土开始重置 → 设置新密码 → 在群中用 重置 <code> 确认

正版玩家

  1. 当名称匹配到正版账号时,聊天栏会显示“检测到 [id] 拥有正版账号 — 是否绑定?”
  2. 点击提示 → 被踢出,提示“请使用正版客户端加入”
  3. 使用正版客户端重连 → 加密握手 + hasJoined 验证 → 在群中发送 绑定正版 <code> 以完成 QQ 二次验证
  4. 绑定后,正版登录无需密码(通过 premiumUuid 匹配账号并重写身份;名称更改不影响)
  5. 同一人使用不同名称:使用 /opa bindpremium 进行手动跨名称绑定

基岩版玩家 (Floodgate)

  1. Floodgate 检测到基岩版连接 → 跳过 Java 版登录界面,直接使用 Cumulus 表单输入 QQ 号
  2. 在群中发送 bind <code> 确认 → 绑定并释放(无需密码)
  3. /opa bindxbox: 将基岩版账号继承绑定至 Java 版账号(共享位置/物品栏),Java/基岩版互斥在线
  4. /opa unbindxbox 或在群中使用 解绑基岩: 恢复独立身份(在 QQ 账号限额下保留数据)

快速登录

  • 重连时:30 分钟内相同 IP,且之前在线 ≥10 分钟 → 免密自动释放(每个窗口期仅一次)
  • 触发时的 QQ 通知:“账号 <name> 刚刚通过快速登录加入 — 不是你?回复 freeze”(可通过 fast-login-notify-qq 开关切换)

登录令牌 (mod)

给玩家

  1. 在 QQ 群中发送 获取凭证 → 机器人私聊发送一个 30 天有效的令牌
  2. 启动安装了 OpenQQAuth mod 的客户端(Fabric 或 NeoForge)
  3. 在多玩家屏幕右下角点击 “Connect with Token” → 输入令牌 → 连接
  4. 服务器验证后免密释放你;如果令牌泄露,可随时使用 吊销凭证 撤销

工作原理

  • 在登录阶段,令牌通过 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. 1.7.2~1.12.1:Legacy 常量表存在,但此范围标记为“理论下限,未正式承诺”——可能会出现包 ID 漂移;生产环境推荐最低版本为 1.12.2
  2. 模组令牌端:构建基线为 MC 26.1.2;支持其他 MC 版本需要在构建配置中更改 minecraft = "26.1.2" 并重新构建
  3. 真实的 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 许可证授权 —— 您可以随意使用,包括为您的项目重新许可。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源