原创 前置/API 工具 世界管理 【插件发布】ServerAuthPlatform v0.5.1 —— 离线服专用账号认证，支持「外置登录验证」（网页 / APP / 群机器人均可接入） V0.5.1

一句话介绍
离线、正版Minecraft 服务端专用的**账号认证插件**。玩家进服后立刻被冻结（移动 / 聊天 / 交互 / 背包 / 伤害 / 命令六类限制），直到完成认证。**核心特色是 Remote 外置登录认证模式**：玩家在游戏里点一个按钮拿到登录链接，去你自己的网页 / APP / 群机器人确认身份，回到游戏自动登录——你的账号体系长什么样，认证就长什么样。

点击展开...

类型	服务端插件（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 认证）

这是本插件区别于普通登录插件的核心。**"这个游戏名是不是本人"的判断完全交给你的系统**，插件只负责三件事：发令牌、轮询结果、放行玩家。

▍玩家侧的体验

1. 玩家进服后执行 /remote（或点面板上的 [ 获取登录链接 ]）；
2. 聊天栏弹出可点击面板：[ 复制登录链接 ] [ 打开浏览器 ] [ 取消 ]；
3. 把链接粘贴到浏览器（或直接打开），在你的登录页输入账号密码；
4. 确认后返回游戏，无需任何操作，插件自动完成登录、解除限制。

▍接入侧的成本
你只需要实现 4 个 HTTP 端点 + 1 个登录页（完整契约、示例代码、排查清单都有配套文档）：

端点	作用
POST /auth/request	申请登录令牌（插件传 username / ip / server_id）
GET /auth/status/{token}	查询确认状态（插件每 5 秒轮询）
POST /auth/revoke	作废令牌（玩家掉线 / 重新获取时调用）
GET /auth/ping	健康检查（启动自检）

为什么用轮询而不是回调？MC 服务端通常不暴露公网端口、无法被动接收连接。轮询由插件主动发起，能穿过 NAT 与防火墙；代价只是确认有最多一个轮询间隔（默认 5 秒）的延迟。

点击展开...

▍几个刻意的设计（也是卖点）

• 按游戏名绑定，不用 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 模式（外置登录）

1. 按配套文档 REMOTE_API.md 实现 4 个端点 + 1 个登录页（附 Python / FastAPI 完整参考实现）；
2. 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"

3. 重启服务器（auth.mode 不支持热重载）；
4. 玩家进服执行 /remote → 点 [ 复制登录链接 ] → 浏览器登录 → 自动进服。

▍Local 模式（本地密码，默认）

1. 新玩家进服：/register → 聊天栏输入密码 → 再输一次确认 → 自动登录；
2. 老玩家进服：/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 权限保护。

安全声明：不建议与聊天记录类插件同时使用（密码输入链路无法 100% 保证不被低优先级监听器截获）；本插件不实现传输层加密（Minecraft 协议层不提供该能力）。完整 14 条安全声明见发布文档。

点击展开...

---

八、环境要求与安装

项	要求
服务端	Spigot 1.21.4 / Paper 1.21.4（1.21 系列理论兼容）
Java	Java 21
构建	项目自带 Gradle Wrapper（gradlew.bat build），无需本机安装 Gradle

1. 关闭服务器；
2. 把 MCServerAuthPlatform-0.5.1.jar 放进 plugins/ 目录；
3. 启动服务器（自动生成 config.yml、messages.yml 与 data.db）；
4. 按需修改配置后 /authadmin reload 或重启。

SQLite 驱动服务端已内置；MySQL 驱动已打包进插件，改 database.type: mysql 即可，无需服主准备驱动。

点击展开...

---

九、常见问题

Q：Remote 模式下浏览器显示登录成功，游戏里没反应？
A：这是对接问题的典型表现。按顺序排查：① 启动日志有没有"Remote 认证轮询已启动"；② 游戏内执行 /authadmin info 看是否有"等待确认"会话；③ 开 settings.debug: true 看轮询日志，对照返回体检查字段名（插件要求扁平 JSON 的 {"confirmed": true}）；④ 等 15 秒插件会自己打 WARNING 列出排查方向。

点击展开...

Q：玩家密码输错了怎么重置？
A：控制台执行 /authadmin unregister <玩家名>，玩家再次进服重新注册。

点击展开...

Q：服务器重启后玩家不用重新登录，是 bug 吗？
A：不是。这是跨重启会话特性（0.2.0 起）：认证成功后会话写入数据库，重启后重新载入。想禁用把 session.grace-period 设为 0。

点击展开...

Q：我的服务器切正版验证了，账号要迁移吗？
A：Remote 模式不用——绑定的是游戏名而非 UUID，玩家不改名就零迁移；Local 模式需要处理（正版 UUID 与离线 UUID 不同）。

点击展开...

---

十、版本路线

版本	内容	状态
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+