OpenQQAuth

QQ 驱动的 Minecraft 登录 / 账户认证系统（MQE 开源版 + 增量）。

OpenQQAuth 运行在 Velocity 代理端：玩家未验证身份时被隔离在登录界面（图形化认证界面：dialog / 虚拟箱子菜单 / 虚拟铁砧，全协议版本适配），验证通过后才被放行到后端 Paper 主服。它以 QQ 为每个账户的强制归属凭证，支持三种登录方式：

离线密码登录 —— 铁砧界面输入密码
正版快捷登录 —— 加密握手 + hasJoined 验证，绑定 QQ 后免密
基岩版登录 —— 微软账号身份（Floodgate），绑定 QQ 即放行、可继承 Java 账户数据

并额外提供**登录凭证（Token）**能力：安装 Fabric / NeoForge 双端合一 mod 后，玩家可在多人游戏界面点击"用凭证连接"，输入由 QQ 群机器人私发的凭证即可免密进服（30 天有效，可吊销）。

领域术语表见 CONTEXT.md，架构决策见 docs/adr/，规格见 .scratch/qqauth/spec.md，外部 API 事实查证见 .scratch/qqauth/api-reference.md。

功能特性

门禁（Gate）：未验证身份连接被限制在登录界面内，验证通过后才放行到主服
图形化认证界面：1.21.6+ 客户端使用 dialog 选择界面，旧版本回退虚拟箱子菜单；密码输入统一使用虚拟铁砧（开窗 / 改名 / 左键确认 / 右键清空 / 灰色混凝土重置）
全协议版本适配：铁砧与物品序列化按协议族参数化（旧版族 1.7.2~~1.12.2 / 扁平化 1.13~~1.14.4 / 经典 NBT 1.15~~1.20.4 / 组件时代 1.20.5~~1.21.1 / 菜单重构 1.21.2~1.21.5 / dialog 时代 1.21.6+），改名传输分界（≤1.12.2 插件通道 / 1.13+ 改名包）
三种登录方式：离线密码、正版快捷（加密握手 + hasJoined 双保险校验）、基岩版免密
QQ 绑定：验证码机制（游戏内显示验证码 → 群里发送 绑定 <验证码>，发送者 QQ 与目标 QQ 必须一致，防抢答）
正版绑定：聊天栏可点击提示触发，正版会话 + QQ 验证码双因素；premiumUuid 固定命中（改名不影响登录）；/opa bindpremium 跨名绑定；顶名离线拒绝 + 冒名建号防线
基岩版支持：Floodgate 识别、Cumulus 表单绑定、/opa bindxbox 继承绑定（基岩绑到 Java 账户共享位置/背包）、Java/基岩互斥在线、/opa unbindxbox 解绑恢复独立身份
快捷登录：同 IP 30 分钟内且在线满 10 分钟断线重连免密（窗口内一次）；触发时向绑定 QQ 发送通知（"非本人操作请回复冻结"，可配置开关）
登录凭证（Token）：QQ 群 获取凭证 机器人私发 → mod 端"用凭证连接"免密进服；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 并发上限、绑定频率限制、会话超时踢出、防重放、全管理操作日志留痕

架构总览

┌──────────────┐     ┌──────────────────────────────┐     ┌──────────────┐
│  Minecraft   │────▶│  Velocity (OpenQQAuth 门禁)  │────▶│  Paper 主服   │
│  客户端      │     │  dialog/箱子/铁砧 认证界面      │     │ (只读 API/事件)│
└──────────────┘     │  登录判定管线 LoginPipeline    │     └──────────────┘
                     │  加密握手/正版验证/基岩 Floodgate│
                     └──────────────┬───────────────┘
                                    │ OneBot (WebSocket)
                     ┌──────────────▼───────────────┐
                     │   QQ 群机器人（绑定/重置/管理/凭证） │
                     └──────────────────────────────┘

模块	说明
`core`	全部领域逻辑：账户/验证码/状态机/登录判定管线/凭证/事件总线/命令框架，平台无关
`bootstrap/velocity`	Velocity 代理插件：门禁、虚拟窗口 UI、协议族编解码、OneBot 接线、mod 登录查询
`bootstrap/paper`	Paper 插件：只读 API 暴露（Bukkit ServicesManager）、领域事件订阅示例
`bootstrap/bukkit` / `bungeecord`	模板兼容骨架（当前仅加载占位）
`bootstrap/fabric` + `bootstrap/neoforge`	双端合一 jar：客户端"用凭证连接" UI 与凭证传输、服务端占位
`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 客户端 mod（凭证登录）

快速开始

1. 构建

gradle --no-daemon :bootstrap:velocity:build   # Velocity 插件
gradle --no-daemon :bootstrap:paper:build      # Paper 插件
gradle --no-daemon :bootstrap:fabric:build :bootstrap:neoforge:build  # mod 双端 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.ttl-days`	`30`	凭证有效期（天）

`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`	查看在线列表
`获取凭证`	为发送者名下账户签发新登录凭证并私发（重复获取覆盖旧凭证）
`吊销凭证 [<账户名>]`	立即作废名下账户的凭证

验证码命令（群内确认敏感操作）

命令	说明
`绑定 <验证码>`	确认 QQ 绑定（游戏内界面显示的验证码）
`重置 <验证码>`	确认密码重置（铁砧灰色混凝土发起）
`解绑正版 <验证码>`	解绑正版身份关联
`解绑基岩 <验证码>`	解绑基岩账户（恢复独立身份）

管理员命令（`ADMIN`）

命令	说明
`bind 1 <QQ> <玩家名>`	强制绑定账户（随后自动私发登录凭证）
`bind 2 <QQ>`	重置账户密码（新密码打印控制台）
`ban @<目标> [名字]` / `unban`	封禁 / 解封账户（持久，仅管理员可解）
`freeze @<目标> [名字]` / `unfreeze`	冻结 / 解冻任意账户（临时可逆）
`check`	查看任意玩家完整信息与服务器概况
`exec <服务器> <指令>`	远程执行后端服务器命令（前后自动审计留痕）
`transfer confirm <账户> <目标QQ> <正版名>`	确认自愿移交（原主解绑后）
`transfer list`	查看待确认移交队列
`reload`	热重载配置
`reconnect`	重连 QQ 机器人

游戏内命令参考

游戏内使用 /opa 前缀（Velocity 命令注册）：

命令	说明
`/opa bindpremium <名字>`	跨名正版绑定（正版身份接管原离线账户）
`/opa bindxbox <名字>`	发起基岩继承绑定（基岩账户绑到指定 Java 账户，共享位置/背包）
`/opa unbindxbox`	解绑基岩继承（恢复独立身份，数据保留）
`/opa reload`	热重载配置（管理员）

登录与绑定流程

新玩家（离线）

进入服务器 → 被门禁拦截，直接进入 QQ 绑定流程
填写 QQ 号 → 游戏内界面显示验证码
在 QQ 群发送 绑定 <验证码>（发送者 QQ 必须与填写的 QQ 一致，防抢答）
绑定成功 → 铁砧界面创建密码（两次输入确认）→ 进入服务器

老玩家（离线）

登录界面选择"离线"→ 铁砧输入密码 → 验证通过放行
忘记密码：铁砧点击灰色混凝土发起重置 → 设置新密码 → 群里发 重置 <验证码> 确认

正版玩家

离线服上名字对应正版账号时，聊天栏出现"检测到 [id] 有正版账号，是否绑定"提示
点击提示 → 被踢出并提示"使用正版客户端进入服务器"
正版客户端重连 → 加密握手 + hasJoined 验证 → 群里发送 绑定正版 <验证码> 完成 QQ 第二因素
绑定后正版客户端登录免密（按 premiumUuid 命中账户并做身份替换，改名不影响）
名字不同但同属一人：/opa bindpremium 手动跨名绑定

基岩版玩家（Floodgate）

Floodgate 识别基岩连接 → 跳过 Java 登录界面，直接用 Cumulus 表单填写 QQ 号
群内发送 绑定 <验证码> 确认 → 绑定即放行（无密码）
/opa bindxbox：将基岩账户继承绑定到 Java 账户（共享位置/背包数据），Java/基岩互斥在线
/opa unbindxbox 或群内 解绑基岩：恢复独立身份（QQ 账户数未达上限时数据保留）

快捷登录

断线重连：同 IP 30 分钟内、之前在线满 10 分钟 → 免密自动放行（窗口内仅一次）
触发时向绑定 QQ 发送通知："账户 <名字> 刚通过快捷登录进入服务器，非本人操作请回复冻结"（fast-login-notify-qq 可关）

登录凭证（mod 端）

玩家使用

在 QQ 群发送 获取凭证 → 机器人私发 30 天有效的登录凭证
启动安装了 OpenQQAuth mod（Fabric 或 NeoForge）的客户端
多人游戏界面右下角点击 "用凭证连接" → 输入凭证 → 连接
服务器校验通过即免密进服；凭证泄露可随时群内 吊销凭证 作废

工作原理

登录阶段经 mod 通道（openqqauth:token）发送凭证，Velocity 端以 128 位随机 nonce 做挑战-响应防重放
校验（TokenLoginChecker）：凭证 + 账户绑定关系 + 未过期 + 未吊销 → 命中即免密放行
凭证校验失败不影响密码登录路径（保持密码输入界面）
非 mod 客户端（vanilla）不受影响，照常走密码登录
凭证明文本地保存可选（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）。

开发指南

票据与规格：.scratch/<feature>/（spec 与编号票据），见 docs/agents/issue-tracker.md
triage 标签：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）

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 客户端（名字→UUID、hasJoined）
├── onebot/       # OneBot 11 客户端（WebSocket 消息收发）
├── password/     # 密码哈希（jBCrypt）
├── qq/           # QQ 域：绑定/重置/解绑状态机、群命令、审计日志、自愿移交
├── token/        # 登录凭证：签发/吊销/校验、传输协议、mod 通道
├── util/         # 工具类
└── verify/       # 验证码服务

常见问题 FAQ

Q：提示"机器人离线"无法绑定？ A：新玩家绑定前置检查机器人在线状态（BotOnlineProvider），机器人离线时绑定类操作降级为提示并踢出。确认 OneBot 已连接（reconnect 可重连）。

Q：1.12.2 等旧版本客户端无法登录？ A：铁砧协议与物品序列化已按协议族参数化支持旧版族（1.7.2~~1.12.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 确认 → 目标接管），系统不提供强制夺权路径。

License

本项目采用 CC0 1.0 Universal 许可，你可按需自由使用（包括修改许可用于自己的项目）。

社区5群：923563248 进群吹水聊天！众多整合包作者、插件作者、玩家在内哦！不定时发福利，公布重要通知！

...

OpenQQAuth(OpenQQAuth)

QQ 驱动的 Minecraft 登录 / 账户认证系统

仅客户端多人信息管理

介绍更新日志下载(6)讨论(0)相关帖子问题反馈

资源外链

Github2 天前

OpenQQAuth

QQ 驱动的 Minecraft 登录 / 账户认证系统（MQE 开源版 + 增量）。

离线密码登录 —— 铁砧界面输入密码
正版快捷登录 —— 加密握手 + hasJoined 验证，绑定 QQ 后免密
基岩版登录 —— 微软账号身份（Floodgate），绑定 QQ 即放行、可继承 Java 账户数据

领域术语表见 CONTEXT.md，架构决策见 docs/adr/，规格见 .scratch/qqauth/spec.md，外部 API 事实查证见 .scratch/qqauth/api-reference.md。

功能特性

门禁（Gate）：未验证身份连接被限制在登录界面内，验证通过后才放行到主服
图形化认证界面：1.21.6+ 客户端使用 dialog 选择界面，旧版本回退虚拟箱子菜单；密码输入统一使用虚拟铁砧（开窗 / 改名 / 左键确认 / 右键清空 / 灰色混凝土重置）
全协议版本适配：铁砧与物品序列化按协议族参数化（旧版族 1.7.2~~1.12.2 / 扁平化 1.13~~1.14.4 / 经典 NBT 1.15~~1.20.4 / 组件时代 1.20.5~~1.21.1 / 菜单重构 1.21.2~1.21.5 / dialog 时代 1.21.6+），改名传输分界（≤1.12.2 插件通道 / 1.13+ 改名包）
三种登录方式：离线密码、正版快捷（加密握手 + hasJoined 双保险校验）、基岩版免密
QQ 绑定：验证码机制（游戏内显示验证码 → 群里发送 绑定 <验证码>，发送者 QQ 与目标 QQ 必须一致，防抢答）
正版绑定：聊天栏可点击提示触发，正版会话 + QQ 验证码双因素；premiumUuid 固定命中（改名不影响登录）；/opa bindpremium 跨名绑定；顶名离线拒绝 + 冒名建号防线
基岩版支持：Floodgate 识别、Cumulus 表单绑定、/opa bindxbox 继承绑定（基岩绑到 Java 账户共享位置/背包）、Java/基岩互斥在线、/opa unbindxbox 解绑恢复独立身份
快捷登录：同 IP 30 分钟内且在线满 10 分钟断线重连免密（窗口内一次）；触发时向绑定 QQ 发送通知（"非本人操作请回复冻结"，可配置开关）
登录凭证（Token）：QQ 群 获取凭证 机器人私发 → mod 端"用凭证连接"免密进服；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 并发上限、绑定频率限制、会话超时踢出、防重放、全管理操作日志留痕

架构总览

┌──────────────┐     ┌──────────────────────────────┐     ┌──────────────┐
│  Minecraft   │────▶│  Velocity (OpenQQAuth 门禁)  │────▶│  Paper 主服   │
│  客户端      │     │  dialog/箱子/铁砧 认证界面      │     │ (只读 API/事件)│
└──────────────┘     │  登录判定管线 LoginPipeline    │     └──────────────┘
                     │  加密握手/正版验证/基岩 Floodgate│
                     └──────────────┬───────────────┘
                                    │ OneBot (WebSocket)
                     ┌──────────────▼───────────────┐
                     │   QQ 群机器人（绑定/重置/管理/凭证） │
                     └──────────────────────────────┘

模块	说明
`core`	全部领域逻辑：账户/验证码/状态机/登录判定管线/凭证/事件总线/命令框架，平台无关
`bootstrap/velocity`	Velocity 代理插件：门禁、虚拟窗口 UI、协议族编解码、OneBot 接线、mod 登录查询
`bootstrap/paper`	Paper 插件：只读 API 暴露（Bukkit ServicesManager）、领域事件订阅示例
`bootstrap/bukkit` / `bungeecord`	模板兼容骨架（当前仅加载占位）
`bootstrap/fabric` + `bootstrap/neoforge`	双端合一 jar：客户端"用凭证连接" UI 与凭证传输、服务端占位
`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 客户端 mod（凭证登录）

快速开始

1. 构建

gradle --no-daemon :bootstrap:velocity:build   # Velocity 插件
gradle --no-daemon :bootstrap:paper:build      # Paper 插件
gradle --no-daemon :bootstrap:fabric:build :bootstrap:neoforge:build  # mod 双端 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.ttl-days`	`30`	凭证有效期（天）

`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`	查看在线列表
`获取凭证`	为发送者名下账户签发新登录凭证并私发（重复获取覆盖旧凭证）
`吊销凭证 [<账户名>]`	立即作废名下账户的凭证

验证码命令（群内确认敏感操作）

命令	说明
`绑定 <验证码>`	确认 QQ 绑定（游戏内界面显示的验证码）
`重置 <验证码>`	确认密码重置（铁砧灰色混凝土发起）
`解绑正版 <验证码>`	解绑正版身份关联
`解绑基岩 <验证码>`	解绑基岩账户（恢复独立身份）

管理员命令（`ADMIN`）

命令	说明
`bind 1 <QQ> <玩家名>`	强制绑定账户（随后自动私发登录凭证）
`bind 2 <QQ>`	重置账户密码（新密码打印控制台）
`ban @<目标> [名字]` / `unban`	封禁 / 解封账户（持久，仅管理员可解）
`freeze @<目标> [名字]` / `unfreeze`	冻结 / 解冻任意账户（临时可逆）
`check`	查看任意玩家完整信息与服务器概况
`exec <服务器> <指令>`	远程执行后端服务器命令（前后自动审计留痕）
`transfer confirm <账户> <目标QQ> <正版名>`	确认自愿移交（原主解绑后）
`transfer list`	查看待确认移交队列
`reload`	热重载配置
`reconnect`	重连 QQ 机器人

游戏内命令参考

游戏内使用 /opa 前缀（Velocity 命令注册）：

命令	说明
`/opa bindpremium <名字>`	跨名正版绑定（正版身份接管原离线账户）
`/opa bindxbox <名字>`	发起基岩继承绑定（基岩账户绑到指定 Java 账户，共享位置/背包）
`/opa unbindxbox`	解绑基岩继承（恢复独立身份，数据保留）
`/opa reload`	热重载配置（管理员）

登录与绑定流程

新玩家（离线）

进入服务器 → 被门禁拦截，直接进入 QQ 绑定流程
填写 QQ 号 → 游戏内界面显示验证码
在 QQ 群发送 绑定 <验证码>（发送者 QQ 必须与填写的 QQ 一致，防抢答）
绑定成功 → 铁砧界面创建密码（两次输入确认）→ 进入服务器

老玩家（离线）

登录界面选择"离线"→ 铁砧输入密码 → 验证通过放行
忘记密码：铁砧点击灰色混凝土发起重置 → 设置新密码 → 群里发 重置 <验证码> 确认

正版玩家

离线服上名字对应正版账号时，聊天栏出现"检测到 [id] 有正版账号，是否绑定"提示
点击提示 → 被踢出并提示"使用正版客户端进入服务器"
正版客户端重连 → 加密握手 + hasJoined 验证 → 群里发送 绑定正版 <验证码> 完成 QQ 第二因素
绑定后正版客户端登录免密（按 premiumUuid 命中账户并做身份替换，改名不影响）
名字不同但同属一人：/opa bindpremium 手动跨名绑定

基岩版玩家（Floodgate）

Floodgate 识别基岩连接 → 跳过 Java 登录界面，直接用 Cumulus 表单填写 QQ 号
群内发送 绑定 <验证码> 确认 → 绑定即放行（无密码）
/opa bindxbox：将基岩账户继承绑定到 Java 账户（共享位置/背包数据），Java/基岩互斥在线
/opa unbindxbox 或群内 解绑基岩：恢复独立身份（QQ 账户数未达上限时数据保留）

快捷登录

断线重连：同 IP 30 分钟内、之前在线满 10 分钟 → 免密自动放行（窗口内仅一次）
触发时向绑定 QQ 发送通知："账户 <名字> 刚通过快捷登录进入服务器，非本人操作请回复冻结"（fast-login-notify-qq 可关）

登录凭证（mod 端）

玩家使用

在 QQ 群发送 获取凭证 → 机器人私发 30 天有效的登录凭证
启动安装了 OpenQQAuth mod（Fabric 或 NeoForge）的客户端
多人游戏界面右下角点击 "用凭证连接" → 输入凭证 → 连接
服务器校验通过即免密进服；凭证泄露可随时群内 吊销凭证 作废

工作原理

登录阶段经 mod 通道（openqqauth:token）发送凭证，Velocity 端以 128 位随机 nonce 做挑战-响应防重放
校验（TokenLoginChecker）：凭证 + 账户绑定关系 + 未过期 + 未吊销 → 命中即免密放行
凭证校验失败不影响密码登录路径（保持密码输入界面）
非 mod 客户端（vanilla）不受影响，照常走密码登录
凭证明文本地保存可选（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）。

开发指南

票据与规格：.scratch/<feature>/（spec 与编号票据），见 docs/agents/issue-tracker.md
triage 标签：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）

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 客户端（名字→UUID、hasJoined）
├── onebot/       # OneBot 11 客户端（WebSocket 消息收发）
├── password/     # 密码哈希（jBCrypt）
├── qq/           # QQ 域：绑定/重置/解绑状态机、群命令、审计日志、自愿移交
├── token/        # 登录凭证：签发/吊销/校验、传输协议、mod 通道
├── util/         # 工具类
└── verify/       # 验证码服务

常见问题 FAQ

Q：凭证校验失败会怎样？ A：不影响密码登录路径——校验失败仅记录日志，玩家回到密码输入界面，可正常用密码登录。

Q：数据存储在哪里？ A：默认 SQLite 文件 openqqauth.db（storage.sqlite-file 可改路径）。

License

本项目采用 CC0 1.0 Universal 许可，你可按需自由使用（包括修改许可用于自己的项目）。

资源打赏

参与人数打赏物品(0)积分(0)打赏时间

暂未收到任何礼物

快来成为第一个打赏人吧~

资源信息

资源版本

1.12.X1.13.X1.14.X1.15.X1.16.X1.17.X1.18.X1.19.X1.20.X1.21.X26.1.X

核心/平台

Bukkit

Velocity

Paper

打赏

加载中...

创作者

...

Nz_173这个人很懒，没有留下任何介绍...

其他信息

语言信息中文

更新于1 天前

发布时间2 天前

资源来源

Github

资源许可证/License

All-Rights-Reserved/No License

社区5群：923563248 进群吹水聊天！众多整合包作者、插件作者、玩家在内哦！不定时发福利，公布重要通知！

...

OpenQQAuth(OpenQQAuth)

QQ 驱动的 Minecraft 登录 / 账户认证系统

仅客户端多人信息管理

介绍更新日志下载(6)讨论(0)相关帖子问题反馈

资源外链

Github2 天前

OpenQQAuth

QQ 驱动的 Minecraft 登录 / 账户认证系统（MQE 开源版 + 增量）。

离线密码登录 —— 铁砧界面输入密码
正版快捷登录 —— 加密握手 + hasJoined 验证，绑定 QQ 后免密
基岩版登录 —— 微软账号身份（Floodgate），绑定 QQ 即放行、可继承 Java 账户数据

领域术语表见 CONTEXT.md，架构决策见 docs/adr/，规格见 .scratch/qqauth/spec.md，外部 API 事实查证见 .scratch/qqauth/api-reference.md。

功能特性

门禁（Gate）：未验证身份连接被限制在登录界面内，验证通过后才放行到主服
图形化认证界面：1.21.6+ 客户端使用 dialog 选择界面，旧版本回退虚拟箱子菜单；密码输入统一使用虚拟铁砧（开窗 / 改名 / 左键确认 / 右键清空 / 灰色混凝土重置）
全协议版本适配：铁砧与物品序列化按协议族参数化（旧版族 1.7.2~~1.12.2 / 扁平化 1.13~~1.14.4 / 经典 NBT 1.15~~1.20.4 / 组件时代 1.20.5~~1.21.1 / 菜单重构 1.21.2~1.21.5 / dialog 时代 1.21.6+），改名传输分界（≤1.12.2 插件通道 / 1.13+ 改名包）
三种登录方式：离线密码、正版快捷（加密握手 + hasJoined 双保险校验）、基岩版免密
QQ 绑定：验证码机制（游戏内显示验证码 → 群里发送 绑定 <验证码>，发送者 QQ 与目标 QQ 必须一致，防抢答）
正版绑定：聊天栏可点击提示触发，正版会话 + QQ 验证码双因素；premiumUuid 固定命中（改名不影响登录）；/opa bindpremium 跨名绑定；顶名离线拒绝 + 冒名建号防线
基岩版支持：Floodgate 识别、Cumulus 表单绑定、/opa bindxbox 继承绑定（基岩绑到 Java 账户共享位置/背包）、Java/基岩互斥在线、/opa unbindxbox 解绑恢复独立身份
快捷登录：同 IP 30 分钟内且在线满 10 分钟断线重连免密（窗口内一次）；触发时向绑定 QQ 发送通知（"非本人操作请回复冻结"，可配置开关）
登录凭证（Token）：QQ 群 获取凭证 机器人私发 → mod 端"用凭证连接"免密进服；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 并发上限、绑定频率限制、会话超时踢出、防重放、全管理操作日志留痕

架构总览

┌──────────────┐     ┌──────────────────────────────┐     ┌──────────────┐
│  Minecraft   │────▶│  Velocity (OpenQQAuth 门禁)  │────▶│  Paper 主服   │
│  客户端      │     │  dialog/箱子/铁砧 认证界面      │     │ (只读 API/事件)│
└──────────────┘     │  登录判定管线 LoginPipeline    │     └──────────────┘
                     │  加密握手/正版验证/基岩 Floodgate│
                     └──────────────┬───────────────┘
                                    │ OneBot (WebSocket)
                     ┌──────────────▼───────────────┐
                     │   QQ 群机器人（绑定/重置/管理/凭证） │
                     └──────────────────────────────┘

模块	说明
`core`	全部领域逻辑：账户/验证码/状态机/登录判定管线/凭证/事件总线/命令框架，平台无关
`bootstrap/velocity`	Velocity 代理插件：门禁、虚拟窗口 UI、协议族编解码、OneBot 接线、mod 登录查询
`bootstrap/paper`	Paper 插件：只读 API 暴露（Bukkit ServicesManager）、领域事件订阅示例
`bootstrap/bukkit` / `bungeecord`	模板兼容骨架（当前仅加载占位）
`bootstrap/fabric` + `bootstrap/neoforge`	双端合一 jar：客户端"用凭证连接" UI 与凭证传输、服务端占位
`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 客户端 mod（凭证登录）

快速开始

1. 构建

gradle --no-daemon :bootstrap:velocity:build   # Velocity 插件
gradle --no-daemon :bootstrap:paper:build      # Paper 插件
gradle --no-daemon :bootstrap:fabric:build :bootstrap:neoforge:build  # mod 双端 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.ttl-days`	`30`	凭证有效期（天）

`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`	查看在线列表
`获取凭证`	为发送者名下账户签发新登录凭证并私发（重复获取覆盖旧凭证）
`吊销凭证 [<账户名>]`	立即作废名下账户的凭证

验证码命令（群内确认敏感操作）

命令	说明
`绑定 <验证码>`	确认 QQ 绑定（游戏内界面显示的验证码）
`重置 <验证码>`	确认密码重置（铁砧灰色混凝土发起）
`解绑正版 <验证码>`	解绑正版身份关联
`解绑基岩 <验证码>`	解绑基岩账户（恢复独立身份）

管理员命令（`ADMIN`）

命令	说明
`bind 1 <QQ> <玩家名>`	强制绑定账户（随后自动私发登录凭证）
`bind 2 <QQ>`	重置账户密码（新密码打印控制台）
`ban @<目标> [名字]` / `unban`	封禁 / 解封账户（持久，仅管理员可解）
`freeze @<目标> [名字]` / `unfreeze`	冻结 / 解冻任意账户（临时可逆）
`check`	查看任意玩家完整信息与服务器概况
`exec <服务器> <指令>`	远程执行后端服务器命令（前后自动审计留痕）
`transfer confirm <账户> <目标QQ> <正版名>`	确认自愿移交（原主解绑后）
`transfer list`	查看待确认移交队列
`reload`	热重载配置
`reconnect`	重连 QQ 机器人

游戏内命令参考

游戏内使用 /opa 前缀（Velocity 命令注册）：

命令	说明
`/opa bindpremium <名字>`	跨名正版绑定（正版身份接管原离线账户）
`/opa bindxbox <名字>`	发起基岩继承绑定（基岩账户绑到指定 Java 账户，共享位置/背包）
`/opa unbindxbox`	解绑基岩继承（恢复独立身份，数据保留）
`/opa reload`	热重载配置（管理员）

登录与绑定流程

新玩家（离线）

进入服务器 → 被门禁拦截，直接进入 QQ 绑定流程
填写 QQ 号 → 游戏内界面显示验证码
在 QQ 群发送 绑定 <验证码>（发送者 QQ 必须与填写的 QQ 一致，防抢答）
绑定成功 → 铁砧界面创建密码（两次输入确认）→ 进入服务器

老玩家（离线）

登录界面选择"离线"→ 铁砧输入密码 → 验证通过放行
忘记密码：铁砧点击灰色混凝土发起重置 → 设置新密码 → 群里发 重置 <验证码> 确认

正版玩家

离线服上名字对应正版账号时，聊天栏出现"检测到 [id] 有正版账号，是否绑定"提示
点击提示 → 被踢出并提示"使用正版客户端进入服务器"
正版客户端重连 → 加密握手 + hasJoined 验证 → 群里发送 绑定正版 <验证码> 完成 QQ 第二因素
绑定后正版客户端登录免密（按 premiumUuid 命中账户并做身份替换，改名不影响）
名字不同但同属一人：/opa bindpremium 手动跨名绑定

基岩版玩家（Floodgate）

Floodgate 识别基岩连接 → 跳过 Java 登录界面，直接用 Cumulus 表单填写 QQ 号
群内发送 绑定 <验证码> 确认 → 绑定即放行（无密码）
/opa bindxbox：将基岩账户继承绑定到 Java 账户（共享位置/背包数据），Java/基岩互斥在线
/opa unbindxbox 或群内 解绑基岩：恢复独立身份（QQ 账户数未达上限时数据保留）

快捷登录

断线重连：同 IP 30 分钟内、之前在线满 10 分钟 → 免密自动放行（窗口内仅一次）
触发时向绑定 QQ 发送通知："账户 <名字> 刚通过快捷登录进入服务器，非本人操作请回复冻结"（fast-login-notify-qq 可关）

登录凭证（mod 端）

玩家使用

在 QQ 群发送 获取凭证 → 机器人私发 30 天有效的登录凭证
启动安装了 OpenQQAuth mod（Fabric 或 NeoForge）的客户端
多人游戏界面右下角点击 "用凭证连接" → 输入凭证 → 连接
服务器校验通过即免密进服；凭证泄露可随时群内 吊销凭证 作废

工作原理

登录阶段经 mod 通道（openqqauth:token）发送凭证，Velocity 端以 128 位随机 nonce 做挑战-响应防重放
校验（TokenLoginChecker）：凭证 + 账户绑定关系 + 未过期 + 未吊销 → 命中即免密放行
凭证校验失败不影响密码登录路径（保持密码输入界面）
非 mod 客户端（vanilla）不受影响，照常走密码登录
凭证明文本地保存可选（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）。

开发指南

票据与规格：.scratch/<feature>/（spec 与编号票据），见 docs/agents/issue-tracker.md
triage 标签：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）

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 客户端（名字→UUID、hasJoined）
├── onebot/       # OneBot 11 客户端（WebSocket 消息收发）
├── password/     # 密码哈希（jBCrypt）
├── qq/           # QQ 域：绑定/重置/解绑状态机、群命令、审计日志、自愿移交
├── token/        # 登录凭证：签发/吊销/校验、传输协议、mod 通道
├── util/         # 工具类
└── verify/       # 验证码服务

常见问题 FAQ

Q：凭证校验失败会怎样？ A：不影响密码登录路径——校验失败仅记录日志，玩家回到密码输入界面，可正常用密码登录。

Q：数据存储在哪里？ A：默认 SQLite 文件 openqqauth.db（storage.sqlite-file 可改路径）。

License

本项目采用 CC0 1.0 Universal 许可，你可按需自由使用（包括修改许可用于自己的项目）。

资源打赏

参与人数打赏物品(0)积分(0)打赏时间

暂未收到任何礼物

快来成为第一个打赏人吧~

资源信息

资源版本

1.12.X1.13.X1.14.X1.15.X1.16.X1.17.X1.18.X1.19.X1.20.X1.21.X26.1.X

核心/平台

Bukkit

Velocity

Paper

打赏

加载中...

创作者

...

Nz_173这个人很懒，没有留下任何介绍...

其他信息

语言信息中文

更新于1 天前

发布时间2 天前

资源来源

Github

资源许可证/License

All-Rights-Reserved/No License

OpenQQAuth

目录

功能特性

架构总览

环境要求

快速开始

1. 构建

2. 安装

3. 最小可用配置示例

配置文件说明

qq-bot（OneBot 机器人）

accounts（账户）

login（登录判定）

verify-code（验证码）

token（登录凭证）

sync-groups（群聊互通）

storage（存储）

premium（正版检测）

QQ 群命令参考

玩家自助命令（BOUND_MEMBER）

验证码命令（群内确认敏感操作）

管理员命令（ADMIN）

游戏内命令参考

登录与绑定流程

新玩家（离线）

老玩家（离线）

正版玩家

基岩版玩家（Floodgate）

快捷登录

登录凭证（mod 端）

玩家使用

工作原理

消息互通

权限模型

从源码构建

开发指南

代码结构速览（core）

常见问题 FAQ

License

OpenQQAuth

目录

功能特性

架构总览

环境要求

快速开始

1. 构建

2. 安装

3. 最小可用配置示例

配置文件说明

qq-bot（OneBot 机器人）

accounts（账户）

login（登录判定）

verify-code（验证码）

token（登录凭证）

sync-groups（群聊互通）

storage（存储）

premium（正版检测）

QQ 群命令参考

玩家自助命令（BOUND_MEMBER）

验证码命令（群内确认敏感操作）

管理员命令（ADMIN）

游戏内命令参考

登录与绑定流程

新玩家（离线）

老玩家（离线）

正版玩家

基岩版玩家（Floodgate）

快捷登录

登录凭证（mod 端）

玩家使用

工作原理

消息互通

权限模型

从源码构建

开发指南

代码结构速览（core）

常见问题 FAQ

License

OpenQQAuth

目录

`qq-bot`（OneBot 机器人）

`accounts`（账户）

`login`（登录判定）

`verify-code`（验证码）

`token`（登录凭证）

`sync-groups`（群聊互通）

`storage`（存储）

`premium`（正版检测）

玩家自助命令（`BOUND_MEMBER`）

管理员命令（`ADMIN`）

`qq-bot`（OneBot 机器人）

`accounts`（账户）

`login`（登录判定）

`verify-code`（验证码）

`token`（登录凭证）

`sync-groups`（群聊互通）

`storage`（存储）

`premium`（正版检测）

玩家自助命令（`BOUND_MEMBER`）

管理员命令（`ADMIN`）

`qq-bot`（OneBot 机器人）

`accounts`（账户）

`login`（登录判定）

`verify-code`（验证码）

`token`（登录凭证）

`sync-groups`（群聊互通）

`storage`（存储）

`premium`（正版检测）

玩家自助命令（`BOUND_MEMBER`）

管理员命令（`ADMIN`）