MixAuth

离线登录模组（Offline Login Mod）

为 NeoForge 1.21.1 离线模式服务器提供身份验证。

本模组有一个直接目标：

• 正版玩家可以在离线模式服务器上完成 Mojang 正版验证。
• 离线玩家必须先注册或登录，然后才能移动、交互、聊天或查看他们的真实物品栏。

主要特性

1. 离线玩家注册和密码登录

• 未注册的离线玩家可以在首次加入时使用 register <password> <confirmPassword>。
• 已注册的离线玩家可以使用 login <password>。
• 已在游戏内的玩家可以使用 auth changepassword <password> <confirmPassword> 更改其离线密码。

2. 正版账号验证

• 当玩家连接时，模组会在登录阶段主动启动正版握手和 Mojang 会话验证。
• 如果验证成功，玩家将作为正版账号继续登录，体验与正版服务器一致。
• 正版登录成功后，玩家使用正版 UUID，而不是离线模式服务器生成的 UUID，这样依赖正版 UUID 的模组（如 Figura 和 FTB Chunks）以及正版皮肤都能正常工作。

3. 已知玩家列表管理

• 每次成功登录（正版或离线）都会记录在已知玩家列表中，包括 UUID、用户名和登录模式。
• 下次登录时，玩家将根据其已知模式直接路由，跳过 Mojang 预检查，以避免触发 API 速率限制。
• 管理员可以使用 auth setmode <UUID|username> <online|offline> 手动指定玩家的登录模式。
• 如果玩家在列表中并被标记为在线（ONLINE），但正版验证失败，他们将立即被拒绝。
• 管理员可以使用 auth remove <UUID|username> 完全删除玩家的所有存储数据（已知玩家列表、离线密码、登录封锁和无密码登录记录）。玩家下次加入时将返回首次登录状态。

4. 无密码登录窗口

• 已注册的离线玩家成功登录后，模组会为该账号 UUID 和 IP 记录一个可信登录条目。
• 在配置的时间窗口内，同一 UUID 从同一 IP 再次登录时可以跳过密码输入。
• 如果在该窗口内同一 IP 关联了多个 UUID，这些 UUID 将失去无密码登录资格，并回退到正常密码登录。

5. 认证前隔离

在离线玩家完成注册或登录之前，模组会将玩家置于待认证状态。在该状态下，模组：

• 将玩家切换到旁观者模式。
• 锁定玩家的位置并持续施加失明效果。
• 发送空物品栏视图以隐藏真实物品栏。
• 阻止聊天、攻击、方块交互、容器访问、物品丢弃和其他游戏操作。
• 仅允许 register 和 login 认证命令。

6. 可配置的安全策略

• 最大密码重试次数。
• 临时封锁时长。
• 登录超时。
• 重复提示间隔。
• 最小密码长度。
• 密码黑名单（首次启动时自动创建，可直接编辑）。
• Mojang 网络请求超时。
• 默认语言和自动检测玩家语言。

配置

配置文件位置

• 服务器配置文件名为 mixauth-server.toml。
• NeoForge 将此文件作为服务器（SERVER）配置加载。
• 更改配置后，建议重启服务器，以便新的认证参数在下次启动时完全生效。

默认配置

[database]
path = "mixauth/mixauth"

[offline_login]
max_login_attempts = 3
temporary_block_minutes = 5
trusted_login_window_hours = 24
login_timeout_minutes = 5
prompt_interval_seconds = 5
bcrypt_cost = 12
min_password_length = 1
max_password_length = 72
password_blacklist_path = "mixauth/password_blacklist.txt"

[online_validation]
connect_timeout_seconds = 10
request_timeout_seconds = 10
pending_handshake_ttl_seconds = 120

[localization]
default_language = "en_us"
auto_detect_player_language = true

关键配置选项

选项	描述
database.path	H2 数据库的基础路径。相对路径从服务器根目录解析，默认生成 mixauth/mixauth.mv.db。
offline_login.max_login_attempts	待登录阶段允许的最大错误密码输入次数。
offline_login.temporary_block_minutes	达到失败尝试限制后的临时封锁时长。
offline_login.trusted_login_window_hours	同一 UUID 和 IP 的无密码登录窗口。
offline_login.login_timeout_minutes	已注册的离线玩家在待登录状态等待的超时时间。
offline_login.prompt_interval_seconds	待认证期间重复注册或登录提示的间隔。
offline_login.bcrypt_cost	用于离线密码哈希的 BCrypt 成本因子。
offline_login.min_password_length	最小密码长度（默认 1，范围 1–72）。BCrypt 输入限制为 72 字节。
offline_login.max_password_length	最大密码长度（默认 72，范围 1–72）。BCrypt 输入限制为 72 字节。
offline_login.password_blacklist_path	外部密码黑名单文件的路径。文件格式为每行一个密码；以 # 开头的行是注释。当文件不存在时，首次启动时会从内置资源自动创建。相对路径从服务器根目录解析。默认生成 mixauth/password_blacklist.txt。
online_validation.connect_timeout_seconds	连接到 Mojang 服务的超时时间。
online_validation.request_timeout_seconds	Mojang 服务请求的超时时间。
online_validation.pending_handshake_ttl_seconds	登录阶段待处理正版握手的保留时间。
localization.default_language	默认提示语言。支持的值：zh_cn、en_us、es_es、pt_br、ru_ru。
localization.auto_detect_player_language	是否在登录后使用玩家报告的客户端语言（当它与受支持的区域设置匹配时）。

附加说明：

• 登录前无法可靠地确定玩家的语言，因此该阶段始终使用 localization.default_language。
• 离线玩家 UUID 强制由服务器基于用户名生成（OfflinePlayer:<username> 的哈希），确保同一用户每次登录都使用相同的 UUID。
• 更改离线密码或通过管理员操作重置密码，会清除之前的可信登录记录。

命令

普通玩家命令

命令	描述
register <password> <confirmPassword>	首次注册离线密码。如果玩家已在游戏中但尚未设置离线密码，此命令也可以创建一个。
login <password>	使用离线密码完成登录。
auth changepassword <password> <confirmPassword>	更改玩家自己的离线密码。

管理员命令

命令	描述
`auth setpassword <UUID	username> `
`auth setmode <UUID	username> <online
`auth remove <UUID	username>`

环境

• NeoForge
• Minecraft 1.21.1