simppassforfree
一个优秀的Minecraft身份验证项目, 可适用于主流加载器
SimpPassForFree - 身份验证与登录模组
一个跨加载器的 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 或更高版本
安装步骤
下载模组
- 从 Releases 页面下载对应 Minecraft 版本的 JAR 文件
安装 Fabric Loader
- 如尚未安装,请访问 Fabric 官网 下载并安装 Fabric Loader
安装 Fabric API
- 下载并安装 Fabric API
安装模组
- 将下载的模组 JAR 文件放入服务器的
mods目录 - 重启服务器
- 将下载的模组 JAR 文件放入服务器的
配置开发者 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:验证会话超时时间(秒),默认 120kick_on_timeout:超时时是否自动踢出玩家,默认 true
📝 使用指南
玩家流程
首次登录(账号绑定)
- 加入服务器后,玩家会收到欢迎消息和登录提示
- 玩家需要从微信小程序获取自己的 SimpPass UID
- 在游戏内使用命令:
/auth <SimpPassUID> - 系统将验证该 UID 的有效性
- 验证成功后,玩家需要在 120 秒内使用验证码完成登录
已绑定用户登录
- 加入服务器后,系统自动检测已绑定账号
- 玩家从微信小程序获取验证码
- 在游戏内使用命令:
/p <验证码> - 系统通过 SimpPass API 验证验证码
- 验证成功后,玩家可以正常游戏
命令
/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 等工具直接进行字节码注入,无需特定加载器实现
- 自动检测:自动检测服务器使用的加载器类型
- 统一实现:一套代码适用于所有加载器
- 性能优化:减少适配层开销,提升性能
安全机制实现
SimpPass API 验证
- 通过官方 SimpPass API 进行用户验证
- API 端处理 IP 地址、地理位置和其他安全检查
- 确保验证过程的安全性和可靠性
会话管理
- 120 秒验证窗口,超时自动过期
- 防止会话重放攻击
- 自动清理过期会话
游戏内保护
- 未验证玩家无法执行游戏操作
- 位置锁定防止未授权移动
- 命令拦截保护服务器安全
🛠️ 高级配置
自定义验证超时时间
修改配置文件中的 session_timeout_seconds 值(单位:秒):
{
"session_timeout_seconds": 180
}
配置超时踢出行为
你可以配置超时时是否自动踢出玩家:
{
"kick_on_timeout": false
}
当设置为 false 时,超时玩家不会被自动踢出,但仍无法执行游戏操作。
多服务器配置共享
如果你有多台服务器,可以共享用户数据:
- 将
config/simppassforfree/目录设置为共享存储(例如 NFS、SMB) - 确保所有服务器对共享目录具有读写权限
- 所有服务器将共享相同的用户绑定数据
🔒 安全建议
保护开发者 UUID
- 不要与他人分享你的开发者 UUID
- 如泄露请定期更换 UUID
- 使用环境变量或加密配置文件存储 UUID
服务器安全
- 定期更新服务器和模组版本
- 使用防火墙限制服务器访问
- 启用服务器日志记录
监控异常行为
- 定期检查服务器日志
- 关注异常登录尝试
- 及时处理安全事件
📊 性能指标
- 验证延迟:平均 < 500ms
- API 响应时间:平均 < 300ms
- 内存占用:< 10MB
- CPU 占用:< 1%(空闲时)
- 并发支持:支持 100+ 玩家同时在线验证
🐛 常见问题
问:玩家无法登录怎么办?
答:请检查以下内容:
- 确认玩家已正确绑定 SimpPass UID
- 检查验证码是否正确(6 位数字)
- 确认验证码未过期(120 秒内)
- 检查服务器网络连接是否正常
- 查看服务器日志获取详细错误信息
问:如何重置玩家的绑定信息?
答:删除 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。
📞 联系方式
- 问题反馈:GitHub Issues
- 自定义服务:https://buy.xiaofansmp.xin
- 技术支持:通过自定义服务网站联系
🙏 致谢
感谢所有为本项目做出贡献的开发者和用户!
注意:使用本模组即表示你同意遵守相关法律法规和服务器规则。请勿将本模组用于非法用途。
版本信息:
- 当前版本: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+)
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。