- 版权类型
- 原创
- 插件中文名称
- 虚构认证
- 插件英文名称
- KyokouAuth
- 支持的核心(代理端)
- BungeeCord
- Velocity
- Waterfall
- 语言支持
- 多语言
- 适配版本(Java)
- 26.x
- 1.21
[MD]
# 🔐 KyokouAuth
### 正版玩家直接进服,其他 Java 玩家使用微软账号验证。
**为 Velocity 与 BungeeCord 系代理打造的账号认证插件。**
KyokouAuth 在代理入口完成身份验证:正版名字通过 Mojang 会话握手验证,其他 Java 名字进入内置验证空间,通过微软设备码确认 Xbox 身份,再进入真正的游戏子服。
无需客户端模组,也无需额外搭建独立登录服。
> 🎯 **代理端安装 · 内置验证空间 · 微软设备码 · 稳定角色 UUID · 可选基岩接入**
---
## ✨ 核心特色
### 🟢 正版登录,保持熟悉的体验
玩家使用正版名字连接时,代理自动完成 Mojang 会话验证。验证成功即可进入服务器,无需额外输入插件注册密码。
**知道一个正版名字,不代表拥有这个账号。** 离线客户端不能仅凭输入别人的正版名取得该角色;正版验证失败时,也不会降级为微软设备码登录。
### 🔗 微软设备码验证,不再新建一套密码
使用未被正版占用的 Java 名字连接时,玩家会进入内置 Limbo:
1. 在聊天栏打开微软验证链接。
2. 在微软页面登录自己的账号并完成授权。
3. 插件核验 Xbox 身份,将其绑定到本服角色。
4. 首次绑定后,按提示从服务器列表重连一次。
正常首次绑定不要求玩家为服务器再设置一份密码。微软账号凭据在微软页面输入,插件不持久保存登录令牌或刷新令牌。
### 🧭 验证空间内置,无需独立登录服
未验证的玩家留在代理管理的私有 Limbo,不会进入真实子服;验证完成后,再按配置连接目标服务器。
- 🚧 验证期间阻止切服,包括后端回退路径。
- ⌨️ 可配置隐藏和拦截的命令。
- ⏳ 支持超时、取消与失败处理。
- 🧩 不需要额外维护认证子服。
### 🆔 换名字,不换掉自己的角色
微软角色默认使用由 **XUID 派生的稳定 UUID**,而不是用玩家输入的名字决定身份。
开启自动改名后,同一个微软账号可以重新验证并绑定到空闲的非正版名字;UUID 不变,原版及按 UUID 保存的角色资料继续沿用。
旧名释放后,其他账号使用该名字会建立自己的角色,不会仅因名字相同继承原持有人的权限。
> 📌 数据连续性针对原版及严格按 UUID 索引的插件。按名字或私有账号表保存数据的插件,需要单独核对。
---
## 🌉 可选:基岩版接入与双角色选择
搭配 **Geyser + 同代理 Floodgate**,让基岩玩家加入现有代理网络。
- **基础基岩接入**:未关联的 Floodgate 玩家通过当前连接身份校验后进入,保留独立名字前缀。
- **官方关联账号选角**:启用角色选择后,具备 Geyser 官方 Global 关联的基岩玩家可以选择可用角色。
| 角色 | 身份 | 数据关系 |
|---|---|---|
| 🏷️ 微软角色(U) | XUID 对应的角色 UUID | 独立保存角色资料 |
| 💎 正版角色(J) | Mojang 官方 UUID | 不与微软角色合并 |
有两个可用角色时,通过原版箱子菜单选择;只有一个可用角色时可直接进入。选择结果与当前连接身份不同时,按提示普通重连一次。
**基岩接入和角色选择默认关闭,纯 Java 服务器无需配置这部分。**
---
## 🎨 把验证空间做成服务器的一部分
等待验证,不一定只能面对空白背景。
| 功能 | 支持内容 |
|---|---|
| 🗺️ 自定义地图 | WorldEdit 导出的 Sponge v2/v3 `.schem` 静态方块地图 |
| 📍 固定出生点 | 自定义位置、朝向与俯仰角 |
| 📋 侧栏计分板 | 最多 15 行静态提示 |
| 🌈 HEX 富文本 | `<#RRGGBB>` 颜色、自定义文案与链接 |
| 🌐 中英文消息 | 内置简体中文与英文,支持客户端语言匹配和自定义语言文件 |
地图、出生点和侧栏可以分别配置。Limbo 是认证专用空间,不是完整的游戏世界,不运行世界模拟。
---
## 📦 已有 AuthMe 服务器?支持旧档认领
无需让所有老玩家放弃原来的角色重新开始。
服主导入同源、停写的一致备份并确认启用后,符合条件的玩家可以在 Limbo 中完成:
**证明旧 AuthMe 账号 → 确认旧档 → 全新微软验证 → 再次确认 → 重连使用原 UUID。**
- 支持旧 AuthMe 离线档案认领到 **Java 微软角色(U)**。
- 成功认领后保留历史 Profile UUID,便于延续原版存档及按 UUID 保存的插件资料。
- 旧来源支持 SQLite、MySQL 和 MariaDB;确认启用后,玩家核验只访问本地快照。
- 自助密码核验支持 AuthMe 默认带盐 SHA256,数据库哈希格式为 `$SHA$<盐>$<哈希>`;启用 TOTP 或使用其他哈希格式的账号不在该自助路径范围内。
> ⚠️ 认领不会自动搬运世界或合并账号。旧存档仍需由服主恢复;基岩角色和 Java 正版角色不参与旧档认领。迁移前务必备份,并先在隔离环境验证。
---
## ⚙️ 服主常用功能
- ⏱️ **可配置免验会话**:默认验证后 12 小时内同 IP 免验,可调整时长或设为每次验证。
- 🚪 **验证后路由**:指定完成 Limbo 验证后进入的目标子服。
- 🛠️ **账号管理**:查询绑定、查看会话、改名、解除绑定、清除免验记录。
- 💾 **多种存储**:SQLite、H2、MySQL、MariaDB、PostgreSQL。
- 🧩 **可选皮肤集成**:微软角色可读取 SkinsRestorer 中为该角色设置的皮肤,正版角色使用官方皮肤。
- 📝 **保留自定义配置**:升级补齐缺失字段,保留已有配置与文案,修改前生成备份。
- 🔄 **消息热重载**:使用 `/ka reload` 重载语言文件;普通配置修改后需重启代理。
免验会话只服务于已绑定的微软角色,不替代正版握手。若多个玩家共享同一出口 IP,且希望每次都验证,可将 `session.hours` 设为 `0`。
---
## 🚀 安装概览
1. 选择与你的代理对应的 **Velocity 版**或 **BungeeCord 版**,放入代理的 `plugins/`。
2. 关闭代理全局正版模式,由插件按名字选择认证路径。
3. 配置转发:Velocity 使用 `modern`,BungeeCord 使用 `ip_forward: true`;下游子服需配置对应转发。
4. 通过绑定地址或防火墙,禁止玩家绕过代理直连子服。
5. 启动代理,按需调整生成的配置、语言、验证空间和目标子服。
**只安装在代理端,不安装在 Paper / Spigot 等下游子服。** 默认使用 SQLite,无需额外配置数据库服务。
完整配置、AuthMe 迁移步骤和故障排查请参阅项目 README。
---
## 🖥️ 环境与兼容范围
| 项目 | 要求 |
|---|---|
| 代理平台 | Velocity 4.3.1;满足必要原生接口检查的 BungeeCord 系代理 |
| BungeeCord 实测构建 | 官方 2110、2111 |
| Java 运行时 | 最低 Java 21,同时满足所用代理的运行要求 |
| 客户端版本 | Minecraft 1.21~26.3 正式版,协议 767~777,同时受代理支持范围限制 |
| 宿主网络库 | Netty 4.2 |
| 基岩接入集成 | Floodgate 2.2.5 b141、Geyser 2.12.1 b1303 |
BungeeCord 版不因构建号不同就直接拒绝,而是检查实际依赖的接口与连接状态。**Waterfall、XCord 等分支尚未专项实测,不作全版本兼容承诺。**
---
## ❓ 常见问题
**玩家需要安装客户端模组吗?**
不需要。Java 玩家使用标准客户端连接,设备码在浏览器中完成授权。
**通过微软验证,就能使用任意正版名字吗?**
不能。被 Mojang 持有的名字必须通过对应正版账号的会话握手,不能用另一个微软账号代替。
**为什么首次验证后需要重连?**
首次连接时还不知道玩家的 XUID,验证后才取得持久角色身份。重连用于以正确 UUID 完成登录,不会在已建立的 Player 上强改 UUID。
**微软角色和正版角色会共用背包吗?**
不会自动合并。两套角色使用独立 UUID,存档和权限分别保存。
**必须安装 Geyser、Floodgate 或 SkinsRestorer 吗?**
不必须。它们分别用于可选的基岩接入和皮肤功能,纯 Java 验证无需安装。
**微软或 Mojang 暂时不可用怎么办?**
相关认证会等待或失败,不会因为上游异常跳过身份验证。代理到官方认证服务的网络连通性是部署前提。
---
## 🔓 开源与许可
KyokouAuth 采用 **Apache-2.0** 许可条款,依赖项保留各自的许可证与声明。
**让登录名保持灵活,让角色身份保持稳定。** ✨
[/MD]