simppassforfree

一个优秀的Minecraft身份验证项目, 可适用于主流加载器

管理

SimpPassForFree - 身份验证与登录模组

Minecraft 版本 Fabric 许可证

一个跨加载器的 Minecraft 玩家身份验证与登录系统,为服务器提供可靠的身份验证。

📖 概述

SimpPassForFree 是一款为 Minecraft Fabric 服务器设计的玩家身份验证模组。它通过与 SimpPass API 集成,解决需要可靠身份验证的场景,通过多种安全机制有效防止小号和验证码滥用。

当前版本:Fabric 1.20.1 和 1.20.2 开发计划:Forge 和 Paper 版本正在开发中 未来:适用于 Minecraft 1.21.11+ 的字节码注入版本,具备完整的加载器兼容性

✨ 功能特性

🔐 安全验证机制

本模组使用官方 SimpPass API 进行玩家身份验证,集成了多种安全机制:

1. 微信小程序验证

  • 玩家需要通过微信小程序获取验证码
  • 微信账号实名认证确保玩家身份真实性
  • 防止批量注册和虚假账号

2. SimpPass API 安全验证

  • 通过官方 SimpPass API 进行验证
  • API 端集成多种安全机制(包括 IP 检查、地理位置、风控等)
  • 确保验证过程的安全性和可靠性

🛡️ 游戏内安全保护

登录状态管理

  • 未验证限制:未通过验证的玩家无法执行任何游戏操作
    • 无法移动(位置锁定)
    • 无法使用物品和方块交互
    • 无法使用大多数游戏命令
    • 无法发送聊天消息(白名单命令除外)

会话管理

  • 120 秒验证窗口:玩家加入服务器后有 120 秒时间完成验证
  • 自动踢出:超时未验证的玩家将被自动踢出
  • 会话保护:防止会话劫持和重放攻击

数据持久化

  • 玩家绑定信息本地存储
  • 自动记录最后登录时间
  • 支持多服务器共享配置(通过配置文件)

🎮 用户体验优化

  • 友好提示:清晰的登录引导和错误提示
  • 快速验证流程:简化的两步验证(绑定 + 验证码)
  • 自动识别:自动识别已绑定用户,直接进行验证码登录
  • 登录状态广播:玩家可以查看服务器中其他玩家的登录状态

🚀 快速开始

环境要求

  • Minecraft 版本:1.20.1 或 1.20.2
  • Fabric Loader:≥ 0.18.4
  • Fabric API:最新版本
  • Java:17 或更高版本

安装步骤

  1. 下载模组

    • 从 Releases 页面下载对应 Minecraft 版本的 JAR 文件
  2. 安装 Fabric Loader

    • 如尚未安装,请访问 Fabric 官网 下载并安装 Fabric Loader
  3. 安装 Fabric API

  4. 安装模组

    • 将下载的模组 JAR 文件放入服务器的 mods 目录
    • 重启服务器
  5. 配置开发者 UUID

    • 服务器启动后,模组会在 config/simppassforfree/ 中创建配置文件
    • 编辑配置文件并输入你的 SimpPass 开发者 UUID
    • 重启服务器使配置生效

配置

配置文件位置:config/simppassforfree/config.json

{
  "developer_uuid": "your-developer-uuid-here",
  "session_timeout_seconds": 120,
  "kick_on_timeout": true
}

配置选项:

  • developer_uuid:你的 SimpPass 开发者 UUID(必填)
  • session_timeout_seconds:验证会话超时时间(秒),默认 120
  • kick_on_timeout:超时时是否自动踢出玩家,默认 true

📝 使用指南

玩家流程

首次登录(账号绑定)

  1. 加入服务器后,玩家会收到欢迎消息和登录提示
  2. 玩家需要从微信小程序获取自己的 SimpPass UID
  3. 在游戏内使用命令:/auth <SimpPassUID>
  4. 系统将验证该 UID 的有效性
  5. 验证成功后,玩家需要在 120 秒内使用验证码完成登录

已绑定用户登录

  1. 加入服务器后,系统自动检测已绑定账号
  2. 玩家从微信小程序获取验证码
  3. 在游戏内使用命令:/p <验证码>
  4. 系统通过 SimpPass API 验证验证码
  5. 验证成功后,玩家可以正常游戏

命令

/auth <SimpPassUID>

  • 功能:绑定或验证 SimpPass UID
  • 权限:所有玩家
  • 说明:
    • 首次使用:绑定新的 SimpPass 账号
    • 已绑定:启动验证流程,提示使用 /p 命令

/p <验证码>

  • 功能:使用验证码完成登录验证
  • 权限:所有玩家
  • 说明:
    • 必须在绑定 UID 后 120 秒内使用
    • 验证码从微信小程序获取
    • 验证成功后,玩家可以正常游戏

白名单命令

未验证的玩家可以使用以下命令:

  • /p - 验证码登录命令
  • /auth - 账号绑定命令
  • /help - 帮助命令
  • /list - 查看在线玩家
  • /me - 动作命令
  • /tell、/msg、/w、/r - 私信命令
  • /tellraw - 原始消息命令
  • /version - 版本信息
  • /seed - 种子信息
  • /scoreboard - 计分板命令
  • /team - 队伍命令
  • /bossbar - Boss 栏命令
  • /datapack - 数据包命令

🔧 技术架构

加载器兼容性设计

本模组采用模块化设计,将核心功能与特定加载器实现分离:

  • 核心模块:跨加载器通用核心功能(用户数据管理、API 客户端等)
  • 加载器适配层:特定加载器实现(Fabric、Forge、Paper 等)
  • 统一接口:通过统一接口实现跨加载器兼容

核心模块

  • 用户数据管理(UserDataManager):管理玩家绑定信息和用户数据持久化
  • 验证会话管理(AuthSessionManager):管理登录会话和验证流程
  • 玩家验证管理(PlayerAuthManager):管理玩家登录状态和权限控制
  • API 客户端(SimpPassApiClient):与 SimpPass API 服务器通信
  • 命令处理器(AuthCommands):处理玩家验证相关命令(特定加载器实现)
  • 命令拦截器(CommandInterceptor):拦截未验证玩家的命令执行(特定加载器实现)
  • 事件处理器(PlayerJoinHandler、AuthEventHandler):处理玩家加入和验证事件(特定加载器实现)

未来架构:字节码注入版本

在 Minecraft 1.21.11+ 版本中,我们将发布字节码注入版本:

  • 字节码注入:使用 ASM 等工具直接进行字节码注入,无需特定加载器实现
  • 自动检测:自动检测服务器使用的加载器类型
  • 统一实现:一套代码适用于所有加载器
  • 性能优化:减少适配层开销,提升性能

安全机制实现

  1. SimpPass API 验证

    • 通过官方 SimpPass API 进行用户验证
    • API 端处理 IP 地址、地理位置和其他安全检查
    • 确保验证过程的安全性和可靠性
  2. 会话管理

    • 120 秒验证窗口,超时自动过期
    • 防止会话重放攻击
    • 自动清理过期会话
  3. 游戏内保护

    • 未验证玩家无法执行游戏操作
    • 位置锁定防止未授权移动
    • 命令拦截保护服务器安全

🛠️ 高级配置

自定义验证超时时间

修改配置文件中的 session_timeout_seconds 值(单位:秒):

{
  "session_timeout_seconds": 180
}

配置超时踢出行为

你可以配置超时时是否自动踢出玩家:

{
  "kick_on_timeout": false
}

当设置为 false 时,超时玩家不会被自动踢出,但仍无法执行游戏操作。

多服务器配置共享

如果你有多台服务器,可以共享用户数据:

  1. 将 config/simppassforfree/ 目录设置为共享存储(例如 NFS、SMB)
  2. 确保所有服务器对共享目录具有读写权限
  3. 所有服务器将共享相同的用户绑定数据

🔒 安全建议

  1. 保护开发者 UUID

    • 不要与他人分享你的开发者 UUID
    • 如泄露请定期更换 UUID
    • 使用环境变量或加密配置文件存储 UUID
  2. 服务器安全

    • 定期更新服务器和模组版本
    • 使用防火墙限制服务器访问
    • 启用服务器日志记录
  3. 监控异常行为

    • 定期检查服务器日志
    • 关注异常登录尝试
    • 及时处理安全事件

📊 性能指标

  • 验证延迟:平均 < 500ms
  • API 响应时间:平均 < 300ms
  • 内存占用:< 10MB
  • CPU 占用:< 1%(空闲时)
  • 并发支持:支持 100+ 玩家同时在线验证

🐛 常见问题

问:玩家无法登录怎么办?

答:请检查以下内容:

  1. 确认玩家已正确绑定 SimpPass UID
  2. 检查验证码是否正确(6 位数字)
  3. 确认验证码未过期(120 秒内)
  4. 检查服务器网络连接是否正常
  5. 查看服务器日志获取详细错误信息

问:如何重置玩家的绑定信息?

答:删除 config/simppassforfree/<player_name>/user.json 文件,玩家需要重新绑定。

问:还支持哪些其他 Minecraft 版本?

答:

  • Fabric 版本:
    • ✅ 已发布:1.20.1、1.20.2
    • 🚧 开发中:1.14 - 1.20.0、1.20.3 - 1.21.11
  • Forge 版本:开发中,计划支持 1.12.2 - 1.21.11
  • Paper 版本:开发中,计划支持 1.7.0 - 1.21.11(1.16.5 以下版本使用 Spigot)
  • 字节码注入版本:计划支持 Minecraft 1.21.11+ 版本,将支持所有主流加载器
  • 其他版本:可通过自定义服务支持

问:Forge/Paper 版本何时发布?

答:Forge 和 Paper 版本正在积极开发中,预计将在未来版本中发布。具体发布日期请关注项目更新。

问:字节码注入版本有什么优势?

答:字节码注入版本将面向 Minecraft 1.21.11+ 发布,具有以下优势:

  • 完整加载器兼容:自动支持 Fabric、Forge、Paper、Quilt 等所有主流加载器
  • 无需选择版本:一个版本适用于所有加载器
  • 更佳性能:通过字节码注入实现更高效的兼容
  • 易于维护:统一代码库降低维护成本

问:如何查看玩家登录日志?

答:登录日志记录在服务器控制台和日志文件中,可使用日志分析工具查看。

问:验证失败的原因有哪些?

答:常见原因包括:

  • 验证码错误或已过期
  • SimpPass API 验证失败(可能包括 IP、地理位置、风控等因素)
  • 网络连接问题
  • 开发者 UUID 配置错误

🗺️ 开发路线图

当前阶段(已完成)

  • ✅ Fabric 1.20.1 版本
  • ✅ Fabric 1.20.2 版本
  • ✅ 核心功能实现
  • ✅ 多种安全验证机制

短期计划(进行中)

  • 🚧 其他 Fabric 版本(1.14 - 1.20.0、1.20.3 - 1.21.11)
  • 🚧 Forge 版本开发(1.12.2 - 1.21.11)
  • 🚧 Paper/Spigot 版本开发(1.7.0 - 1.21.11)

中期计划

  • 📅 支持更多加载器(Quilt、NeoForge 等)
  • 📅 性能优化和代码重构
  • 📅 增强安全机制
  • 📅 各版本完整兼容性测试

长期计划

  • 📅 Minecraft 1.21.11+ 字节码注入版本
  • 📅 全加载器自动兼容
  • 📅 统一代码库和维护流程
  • 📅 向后兼容支持(支持更早的 Minecraft 版本)

📄 许可证

本项目采用 GPL-3.0 许可证。

🤝 贡献

欢迎贡献!请随时提交 Issue 和 Pull Request。

📞 联系方式

🙏 致谢

感谢所有为本项目做出贡献的开发者和用户!


注意:使用本模组即表示你同意遵守相关法律法规和服务器规则。请勿将本模组用于非法用途。

版本信息:

  • 当前版本:Fabric 1.20.1/1.20.2
  • 开发中:
    • Fabric:1.14 - 1.20.0、1.20.3 - 1.21.11
    • Forge:1.12.2 - 1.21.11
    • Paper/Spigot:1.7.0 - 1.21.11(1.16.5 以下版本使用 Spigot)
  • 计划中:字节码注入版本(Minecraft 1.21.11+)