原创 前置/API 工具 世界管理 【插件发布】SPA 离线、正版均可用的服务器验证插件！ V0.1

一句话介绍
离线服务器上任何人都能顶着任意 ID 进服——冒用名字、拿走装备和领地。ServerAuthPlatform 在玩家进服后立刻施加全套限制，直到他完成 注册 / 登录。本插件开源构建、单文件部署、零 Paper 专有依赖，Spigot 与 Paper 双端实测可用。

点击展开...

• 别人可以冒用你的名字进服，拿走你的装备、领地、权限；
• 没有可靠的「这个人就是账号主人」的判断依据；
• 管理员的 OP 也可能被冒名顶替。

• 两段式注册 / 登录：执行 /register 或 /login 后，在聊天栏输入密码即可，密码不进入命令日志；
• 断线重连免登录：已登录玩家掉线后 300 秒（可配置）内重连自动恢复登录状态，可选 IP 严格校验；
• 图形认证面板：27 格 GUI，进服自动弹出，含登录 / 注册 / 关闭按钮与玩家头颅状态显示；
• 全套未登录限制：移动、聊天、交互、背包、伤害、命令六类限制，每一项都可独立开关；
• 命令白名单机制：基于 PlayerCommandPreprocessEvent 全量拦截，杜绝「漏注册命令 = 绕过点」；
• BCrypt 密码哈希：密码绝不明文入库，哈希在异步线程池执行，不卡主线程；
• SQLite 单文件存储：复制 data.db 即完成备份，启动自动执行幂等数据库迁移；
• 全量消息可配置：所有玩家可见文案集中在 messages.yml，支持 & 颜色代码与 {player} 等占位符，热重载即时生效；
• 配置语义校验：启动时配置有致命问题会拒绝启用并列出全部问题；热重载失败保留旧配置，不弄坏运行中的服务器；
• 对外 API：内置 AuthPluginAPI，其他插件可查询认证状态、用户信息、强制登出；
• OP 不绕过认证：防止管理权限被冒用，忘记密码用服务器控制台处理（刻意设计，无 bypass 开关）；
• 质量保障：67 个单元测试全通过，时间源可注入，测试不依赖运行中的服务器。

1. 进服自动弹出「账号认证」面板，聊天栏提示使用 /register 注册；
2. 输入 /register（推荐不带参数）；
3. 在聊天栏输入要设置的密码（这条消息不会进入聊天，也不会进入命令日志）；
4. 再输入一次确认；
5. 注册成功 → 自动登录 → 限制解除。

1. 输入 /login（推荐不带参数）；
2. 在聊天栏输入密码；
3. 登录成功 → 限制解除。

关于 OP：本插件不会让 OP 绕过认证。忘记密码的 OP 请在服务器控制台执行 /authadmin unregister <玩家>，然后重新进服注册。

点击展开...

# 认证设置
auth:
  min-password-length: 6      # 密码最小长度
  max-password-length: 32     # 密码最大长度（硬上限 64）
  bcrypt-cost: 12             # BCrypt 强度 4-31，推荐 10-14

# 会话设置
session:
  grace-period: 300           # 断线重连宽限期（秒），0 = 禁用免登录
  ip-strict: false            # 宽限期内是否要求来源 IP 一致
  input-timeout: 30           # 密码输入会话超时（秒）

# 未登录限制（均可独立开关）
restriction:
  freeze-movement: true       # 冻结移动（允许转视角）
  freeze-chat: true           # 禁止聊天
  freeze-interaction: true    # 禁止交互、破坏/放置方块
  freeze-inventory: true      # 禁止背包操作、丢弃物品、切换快捷栏
  freeze-damage: true         # 免疫伤害 & 禁止攻击
  allowed-commands:           # 未登录时允许的命令（小写、不带斜杠）
    - login
    - l
    - register
    - reg
    - auth
    - logout

# 图形面板
gui:
  enabled: true               # 是否启用图形面板
  auto-open: true             # 进服自动打开面板

# 数据库（Phase 1 仅 SQLite）
database:
  file: "data.db"             # 相对插件数据目录的数据库文件名

settings:
  debug: false                # 调试日志（排查问题时临时开启）

• 所有玩家可见文案集中在 messages.yml，颜色代码用 &（如 &a = 绿色）；
• 占位符：{player}、{min}、{max}、{prefix}；
• 修改后执行 /authadmin reload 即时生效；
• 若某条消息键被删除，玩家会看到 <missing:键名> —— 刻意设计，方便定位配置问题。

• 密码不会明文入库：数据库只保存 BCrypt 哈希（含随机盐），哈希不可逆；
• 默认输入路径避开命令日志：/register、/login 后在聊天栏输入密码，本插件在 LOWEST 优先级取消聊天事件，大多数插件拿不到内容；
• OP 不绕过认证：管理权限同样需要先完成登录，冒名者无法利用 OP 账号；
• 敏感操作受权限保护：/authadmin 全部子命令由 serverauthplatform.admin 权限节点控制；
• 配置校验兜底：启动校验失败拒绝启用，reload 失败保留旧配置，不会把运行中的服务器改坏。

安全声明（务必阅读）：
1. 通过 /login <密码> 等方式输入时，密码会进入服务端日志与事件链路，不推荐；
2. 聊天栏输入无法阻止优先级更低的插件或 NMS / 代理层监听器截获；
3. 不建议与聊天记录类插件同时使用；如必须，请自行评估风险；
4. 本插件不实现传输层加密（Minecraft 协议层不提供该能力）；
5. 生产环境对账号安全有强需求，建议等待 V2 的 Remote 认证模式（外部登录系统 + HTTPS）。

点击展开...

• 三执行域线程模型：主线程只碰 Bukkit API，2 线程认证池负责 BCrypt 与数据库，异步维护任务清理过期会话；回调必切主线程，插件卸载时等待 5 秒，杜绝「卸载后还在回调」的经典崩溃；
• SQLite 单连接 + 串行化：SQLite 写入本身串行，多连接只会带来 SQLITE_BUSY；认证场景 QPS 极低，连接池是过度设计；
• 取消事件而非接管玩家状态：不改速度、不上失明、不开无敌，最小侵入、最容易排查；移动事件只比对坐标，允许转动视角；
• 命令白名单全覆盖：用 PlayerCommandPreprocessEvent 拦截，是唯一能覆盖「所有命令」的位置，支持 /sap:login 这类带命名空间的写法；
• GUI 身份判定基于 InventoryHolder：不用标题字符串识别面板——标题是玩家可见文本，会随语言/颜色变化，用它做判定是典型事故来源；
• 身份模型钉死：离线服务器上 UUID 就是身份，登录一律按 UUID 查询；用户名仅是显示名，改名 = 换身份（不自动迁移，V1 提供迁移命令）；
• 时间源可注入：测试通过 LongSupplier 快进时钟，不使用 Thread.sleep，测试确定性高；
• 分层纪律：auth / session / database 包零 Bukkit 依赖，玩家可见文案只存在于 messages.yml；代码零 io.papermc.paper.* 引用，以 Spigot API 编译证明跨端兼容。

阶段	内容	状态
Phase 1 / MVP（0.1.0）	Local 认证 + SQLite + 内存会话 + 未登录限制 + 基础 GUI + 命令权限 + 67 个单元测试	当前版本
Phase 2 / V1	MySQL 支持、auth_sessions 跨重启会话、公开 API 扩展 + 自定义事件、UUID 迁移（离线→正版）、/authadmin migrate、PlaceholderAPI、TOTP 二次验证、改密码命令、登录审计表	未开始
Phase 3 / V2	Remote 认证：外部登录系统 + HTTPS + 一次性 Token + 批量轮询队列，API Key 不落日志	未开始
Phase 4 / V3	BOTH 模式（本地+远程混合）、多服共享数据库、Web 管理面板、Vault / LuckPerms 生态集成、自定义 GUI 主题	未开始

每个阶段独立可发布、独立可验证、独立可放弃。后续版本根据实际反馈决定是否开发——如果你在用，欢迎反馈需求！

点击展开...

# Windows
gradlew.bat build

# macOS / Linux
./gradlew build

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

服务器需要自带 SQLite JDBC 驱动。Spigot / Paper 服务端均已内置，一般无需额外操作。若启动日志出现「未找到 JDBC 驱动 org.sqlite.JDBC」，说明你的服务端是裁剪版，请把 sqlite-jdbc 放进服务端 libraries/ 或联系作者。

点击展开...

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

点击展开...

Q：为什么 /login <密码> 不推荐？
A：命令参数会被服务端写进 logs/latest.log。用 /login + 聊天栏输入可以避开命令日志。

点击展开...

Q：我装了聊天记录插件，密码会泄露吗？
A：本插件在 LOWEST 优先级取消聊天事件，NORMAL / MONITOR 优先级的插件拿不到。但优先级更低的插件或 NMS 层仍可能截获。装有聊天记录插件时不建议使用本插件。

点击展开...

Q：OP 玩家为什么也被冻结了？
A：设计如此（OP 不绕过认证），请用控制台处理紧急情况。

点击展开...

Q：能改成 MySQL 吗？
A：Phase 1 不支持，已列入 V1 计划。

点击展开...

• Author: Stephen Zhang
• Website: www.ywzltech.com
• 如果你正在使用本插件，欢迎反馈使用场景与问题 —— 这将直接决定 V1 / V2 的优先级！