- 版权类型
- 原创
- 插件中文名称
- 我的世界服务器认证平台插件
- 插件英文名称
- ServerAuthPlatform
- 原帖地址
- #
- 支持的核心（服务端）
- Spigot
- Paper
- Purpur
- Leaves
- 其他核心
- 语言支持
- 多语言
- 适配版本（Java）
- 26.x
- 1.21
【插件发布】ServerAuthPlatform v0.5.1 —— 离线服专用账号认证，支持「外置登录验证」（网页 / APP / 群机器人均可接入）· Paper 1.21+
不只是本地密码登录 —— 让「谁是你的玩家」由你自己的系统说了算
一、特色功能：外置登录验证（Remote 认证）
这是本插件区别于普通登录插件的核心。**"这个游戏名是不是本人"的判断完全交给你的系统**，插件只负责三件事：发令牌、轮询结果、放行玩家。
▍玩家侧的体验
▍接入侧的成本
你只需要实现 4 个 HTTP 端点 + 1 个登录页（完整契约、示例代码、排查清单都有配套文档）：
▍几个刻意的设计（也是卖点）
二、截图展示
图1 · 游戏内 Remote 认证面板（TUI）：点击复制登录链接 / 直接打开浏览器，链接与有效期一目了然
图2 · 你的 Web 登录管理页示例：玩家绑定游戏角色、确认状态统计（待确认 / 已确认 / 已作废）
图3 · 认证成功（游戏内）
图4 · 账号认证主面板（TUI）：登录 / 注册 / 帮助全部可点击
三、本地密码认证（Local 模式）同样完整
不想接外部系统的服主直接用默认的 Local 模式，开箱即用：
四、全特性一览
五、快速上手
▍Remote 模式（外置登录）
▍Local 模式（本地密码，默认）
六、命令与权限
别名：/login → /l，/register → /reg
七、安全设计
八、环境要求与安装
九、常见问题
十、版本路线
十一、联系与反馈
ServerAuthPlatform v0.5.1 · 离线服账号认证 · Local + Remote 外置登录验证 · Paper 1.21+
不只是本地密码登录 —— 让「谁是你的玩家」由你自己的系统说了算
| 类型 | 服务端插件（Bukkit / Spigot / Paper） |
| 当前版本 | 0.5.1 |
| 目标 API | Bukkit API 1.21+（api-version 1.21） |
| 实测环境 | Paper 1.21.4 / Spigot 1.21.4（1.21 系列理论兼容） |
| 运行环境 | Java 21（编译与运行目标均为 21） |
| 认证模式 | Local（本地密码，默认） / Remote（外置登录验证），BOTH 计划中 |
| 数据存储 | SQLite 单文件 / MySQL 多服共享（驱动已内嵌，无需服主准备） |
| 密码算法 | BCrypt（默认 cost=12，异步线程池执行） |
| 部署形态 | 单文件 fat jar（约 4.6 MB），零 Paper 专有依赖 |
一、特色功能：外置登录验证（Remote 认证）
这是本插件区别于普通登录插件的核心。**"这个游戏名是不是本人"的判断完全交给你的系统**，插件只负责三件事：发令牌、轮询结果、放行玩家。
▍玩家侧的体验
- 玩家进服后执行 /remote（或点面板上的 [ 获取登录链接 ]）；
- 聊天栏弹出可点击面板：[ 复制登录链接 ] [ 打开浏览器 ] [ 取消 ]；
- 把链接粘贴到浏览器（或直接打开），在你的登录页输入账号密码；
- 确认后返回游戏，无需任何操作，插件自动完成登录、解除限制。
▍接入侧的成本
你只需要实现 4 个 HTTP 端点 + 1 个登录页（完整契约、示例代码、排查清单都有配套文档）：
| 端点 | 作用 |
| POST /auth/request | 申请登录令牌（插件传 username / ip / server_id） |
| GET /auth/status/{token} | 查询确认状态（插件每 5 秒轮询） |
| POST /auth/revoke | 作废令牌（玩家掉线 / 重新获取时调用） |
| GET /auth/ping | 健康检查（启动自检） |
▍几个刻意的设计（也是卖点）
- 按游戏名绑定，不用 UUID：离线服的 UUID 是服务端按玩家名算出来的派生值，外部系统既无法验证、玩家也无法提供。改用游戏名后三方天然对齐；日后服务器切换正版验证（online-mode=true），Remote 模式零迁移；
- 登录页必须做"归属校验"：确认时校验"该 token 所属游戏名"已绑定到"当前 Web 登录账号"，防止令牌与账号错配（文档里有攻击场景详解）；
- 强制 HTTPS（https-only: true，配 http:// 直接拒绝启动）：API Key 在 Authorization 头里，明文过网等于交出认证系统控制权；
- 一次性令牌 + 有效期（默认 300 秒）+ 数据库 CAS 防并发消费；令牌与 API Key 写入日志前自动脱敏（保留前 6 / 4 位）；
- 不跟随重定向（followRedirects(NEVER)）：防止携带 Authorization 头跳到第三方域名；
- 网络抖动不踢人：轮询遇到非 2xx 视为"还没确认"继续等，等 15 秒会自动打出 WARNING 并直接给出排查方向。
二、截图展示
图1 · 游戏内 Remote 认证面板（TUI）：点击复制登录链接 / 直接打开浏览器，链接与有效期一目了然
图2 · 你的 Web 登录管理页示例：玩家绑定游戏角色、确认状态统计（待确认 / 已确认 / 已作废）
图3 · 认证成功（游戏内）
图4 · 账号认证主面板（TUI）：登录 / 注册 / 帮助全部可点击
三、本地密码认证（Local 模式）同样完整
不想接外部系统的服主直接用默认的 Local 模式，开箱即用：
- 两段式注册 / 登录：执行 /register 或 /login 后在聊天栏输入密码，密码不进入命令日志；
- 断线重连免登录：掉线后 300 秒（可配置）内重连自动恢复，服务器重启同样有效（会话落库）；
- 聊天栏可点击面板（TUI）：所有功能点按钮完成，不用记任何命令；按钮外框可选 [ 登录 ] / 【登录】 / ▸ 登录 ◂ / 登录 四种风格；
- 图形认证面板：27 格 GUI，进服自动弹出，登录 / 注册 / 关闭按钮 + 玩家头颅状态；
- 全套未登录限制：移动（冻结但可转视角）、聊天、交互、背包、伤害、命令六类，每一项独立开关；
- 命令白名单全覆盖：基于 PlayerCommandPreprocessEvent 全量拦截，杜绝"漏注册命令 = 绕过点"；
- OP 不绕过认证：防止管理权限被冒用（忘记密码用控制台 /authadmin unregister 处理）。
四、全特性一览
Remote 外置登录认证：外部系统决定玩家身份，网页 / APP / 群机器人均可接入；- Local 本地密码认证：BCrypt 存储，默认模式开箱即用；
- SQLite / MySQL 双存储：单机用 SQLite 复制即备份；多服共享用 MySQL（表前缀隔离，驱动已内嵌）；
- 跨重启会话：登录状态落库，重启后宽限期内重连免登录；
- 登录审计日志：记录登录 / 注册 / 远程认证事件与结果，不记录密码，默认保留 30 天；
- 公开 API：AuthPluginAPI 经 Bukkit ServicesManager 提供，其他插件可查询认证状态；
- 自定义事件：PlayerAuthLoginEvent / PlayerAuthRegisterEvent / PlayerAuthLogoutEvent（均不携带密码或哈希）；
- PlaceholderAPI 支持：%sap_authenticated% 等 10 个变量，软依赖未安装不影响功能；
- 全量消息可配置：messages.yml 集中管理，& 颜色代码 + {player} 等占位符，热重载即时生效；
- 配置语义校验：致命问题拒绝启用并列出全部问题；reload 失败保留旧配置，不弄坏运行中的服务器；
- 数据库自动迁移：0.1.0 ~ 0.4.0 升级直接替换 jar，幂等迁移自动执行。
五、快速上手
▍Remote 模式（外置登录）
- 按配套文档 REMOTE_API.md 实现 4 个端点 + 1 个登录页（附 Python / FastAPI 完整参考实现）；
- config.yml 配置：
代码：auth: mode: remote remote: api-url: "https://auth.example.com/api" login-url: "https://auth.example.com/login?token={token}" api-key: "your-secret-key" server-id: "server-1" - 重启服务器（auth.mode 不支持热重载）；
- 玩家进服执行 /remote → 点 [ 复制登录链接 ] → 浏览器登录 → 自动进服。
▍Local 模式（本地密码，默认）
- 新玩家进服：/register → 聊天栏输入密码 → 再输一次确认 → 自动登录；
- 老玩家进服：/login → 聊天栏输入密码 → 限制解除。
六、命令与权限
| 命令 | 权限 | 默认 | 说明 |
| /login（推荐） | 无 | 所有人 | 进入密码输入会话，聊天栏输密码 |
| /register（推荐） | 无 | 所有人 | 两段式注册，聊天栏输两次密码 |
| /logout | 无 | 所有人 | 立即登出 |
| /auth | 无 | 所有人 | 打开认证面板（TUI + GUI） |
| /remote | 无 | 所有人 | 发起外置登录认证（remote / both 模式） |
| /remote refresh | 无 | 所有人 | 重新获取登录链接（旧链接立即失效） |
| /remote cancel | 无 | 所有人 | 放弃本次远程认证 |
| /authadmin reload | serverauthplatform.admin | OP | 热重载配置与消息（database / auth.mode 除外） |
| /authadmin unregister <玩家> | serverauthplatform.admin | OP | 删除账号（玩家需重新注册） |
| /authadmin force <玩家> | serverauthplatform.admin | OP | 强制将在线玩家置为已登录 |
| /authadmin revoke <玩家> | serverauthplatform.admin | OP | 撤销持久化会话（重连也需重新登录） |
| /authadmin info [玩家] | serverauthplatform.admin | OP | 查看存储 / 账号 / 会话 / 等待中的远程认证 |
别名：/login → /l，/register → /reg
七、安全设计
- 密码不明文入库：数据库只存 BCrypt 哈希（含随机盐，cost 默认 12，异步执行不卡主线程）；
- 默认输入路径避开命令日志：聊天栏输密码时插件在 LOWEST 优先级取消聊天事件；
- 审计日志不记录密码：只记事件类型与结果；
- Remote 强制 HTTPS + API Key 双向认证：明文 http:// 直接拒绝启动；
- 令牌一次性 + 绑定游戏名 + 过期时间：并发消费由数据库 CAS 保证；
- 日志脱敏：令牌与 API Key 写日志前掩码；
- OP 不绕过认证；敏感操作受 serverauthplatform.admin 权限保护。
八、环境要求与安装
| 项 | 要求 |
| 服务端 | Spigot 1.21.4 / Paper 1.21.4（1.21 系列理论兼容） |
| Java | Java 21 |
| 构建 | 项目自带 Gradle Wrapper（gradlew.bat build），无需本机安装 Gradle |
- 关闭服务器；
- 把 MCServerAuthPlatform-0.5.1.jar 放进 plugins/ 目录；
- 启动服务器（自动生成 config.yml、messages.yml 与 data.db）；
- 按需修改配置后 /authadmin reload 或重启。
九、常见问题
十、版本路线
| 版本 | 内容 | 状态 |
| 0.1.0 | Local 认证 + SQLite + 内存会话 + 六类限制 + 基础 GUI | |
| 0.2.0 | MySQL、跨重启会话、公开 API、自定义事件、审计日志、PlaceholderAPI | |
| 0.4.0 | Remote 外置登录认证 + 聊天栏 TUI 面板 | |
| 0.5.0 / 0.5.1 | Remote 改为按玩家名绑定（去 UUID）、修复静默故障、等待会话可视化 | 当前版本 |
| V3（规划） | BOTH 模式（本地 + 远程并行）、多服实时会话同步 | 未开发，按反馈决定 |
十一、联系与反馈
- Author: Stephen Zhang
- 官网：www.ywzlidc.com
- 问题反馈：soft.ywzlidc.com
- 交流 QQ 群：816467347
- 附：完整发布文档（Markdown，含 Remote 对接契约索引、命令权限全表、安全声明、FAQ）
ServerAuthPlatform v0.5.1 · 离线服账号认证 · Local + Remote 外置登录验证 · Paper 1.21+
