原创 开源 TrueUUID - 一个适用于 Forge 1.20.X 的离线服登录正版账号校验的模组 v1.0.1

[MD] # TrueUUID [English](README.md) | 简体中文 一个适用于 Forge 1.20.1 的离线服登录期正版校验 Mod，客户端本地调用 joinServer，令牌不出客户端；服务端用随机 nonce 调用 Mojang 会话服务校验，并在成功时替换为正版 UUID、矫正名称大小写、注入皮肤属性。失败/超时的处理可配置，并在玩家进服后通过标题与聊天消息告知在线/离线模式。 注意：客户端与服务端都需要安装本 Mod；服务器需设置为离线模式。 ## 特性 - 登录期安全校验：客户端本地 `joinServer(profile, token, nonce)`，令牌不上传。 - 服务端 `hasJoined` 校验通过： - 替换为正版 UUID - 使用 Mojang 返回的名称，统一大小写 - 注入皮肤属性（含签名），并在进服后强制刷新外观 - 超时/失败处理可配置（默认：超时踢出；失败放行离线） - 进服提示： - 正版：绿色标题“正版模式”，短副标题“已通过正版校验” - 离线：红色标题“离线模式”，短副标题“鉴权失败：离线模式”，并发送一条可配置的长聊天提示 ## 工作流程 1. 服务器离线模式下，HELLO 后下发自定义登录查询（identifier: `trueuuid:auth`，包含 nonce）。 2. 客户端拦截查询，读取 nonce，使用本地令牌调用 `MinecraftSessionService.joinServer(...)`，并仅回传一个布尔 ack。 3. 服务端调用 `https://sessionserver.mojang.com/session/minecraft/hasJoined?username={name}&serverId={nonce}[&ip={ip}]`。 4. 成功： - 用正版 UUID 和官方返回的名称构造新的 GameProfile - 注入皮肤 textures 属性（带签名），玩家加入后强制刷新一次玩家信息 - 显示绿色标题“正版模式” 5. 失败： - 默认行为：放行为原版离线（可配置为直接踢出） - 进服后显示红色标题“离线模式”，并发送一条可配置的聊天提示说明可能是网络问题导致鉴权失败 6. 超时： - 默认行为：踢出（提示语可配置） - 也可配置为超时时放行离线 ## 环境要求 - Minecraft：1.20.1 - Forge：47.x（如 47.4.8） - Java：17 - 客户端与服务端都安装本 Mod - 服务端 `server.properties`：`online-mode=false` ## 安装 - 服务器： - 将 `server.properties` 设为 `online-mode=false` - 把构建出的 JAR 放到 `mods/` - 客户端： - 把相同的 JAR 放到 `mods/` 提示：若客户端没有安装本 Mod，服务端将收不到有效回包。此时会按配置选择“踢出”或“放行为离线”。 ## 配置 首次运行后自动生成： - `config/trueuuid-common.toml` 关键项（默认值符合“超时踢出 / 失败放行离线”的需求）： - `auth.timeoutMs = 10000` - 登录阶段等待客户端回包的超时时间（毫秒） - `auth.allowOfflineOnTimeout = false` - false：超时踢出（默认） - true：超时放行为离线 - `auth.allowOfflineOnFailure = true` - true：任何鉴权失败放行为离线（默认） - false：失败时踢出 - `auth.timeoutKickMessage = "登录超时，未完成正版校验"` - 超时时的踢出提示语 - `auth.offlineFallbackMessage = "注意：你当前以离线模式进入服务器；如果你是正版账号，可能是网络原因导致无法成功鉴权。"` - 当以离线模式放行时，发送给玩家的聊天提示 - `auth.offlineShortSubtitle = "鉴权失败：离线模式"` - 离线模式下的标题短副标题（避免过长） - `auth.onlineShortSubtitle = "已通过正版校验"` - 正版模式下的标题短副标题 说明： - 标题的副标题使用“短文案”，防止超出屏幕；长说明走聊天提示。 - 需要自定义更多提示文案时，可直接修改以上配置项。 ## 兼容性与注意事项 - 代理（Bungee/Velocity）：服务端会在可行时把远端 IP 作为 `ip` 参数传给 Mojang 的 `hasJoined`。若代理隐藏了真实 IP，校验仍可成功（`ip` 参数为可选）。 - 皮肤：登录期已注入皮肤属性；玩家加入后会广播一次“移除+初始化”的玩家信息包来强制刷新外观。 - 未安装客户端 Mod：无法正确回包。根据配置，可能被踢出或被放行为离线。 ## 隐私 - 玩家 access token 不会离开客户端。客户端本地完成 `joinServer` 调用。 - 服务器仅收到一个布尔应答，随后由服务器自行调用 Mojang 会话服务校验 nonce。 ## 许可 - GNU LGPL 3.0（见项目说明/构建配置） ## 致谢 - Mojang authlib / Session Server - Sponge Mixin - ForgeGradle --- 维护者：[@YuWan-030](https://github.com/YuWan-030) [/MD]