SmoothLogin

SmoothLogin

将登录时的文件处理移出服务器线程，让玩家加入过程保持流畅。

SmoothLogin 是一款服务端 Fabric 性能优化模组，会在玩家进入世界前异步准备玩家数据。玩家 NBT、统计数据和进度会由可配置的工作线程池读取并解析，减少大量玩家同时登录时服务器线程需要执行的繁重文件操作。

它还提供可选的 UUID 迁移工具，供切换身份验证模式的服务器使用。自动迁移默认关闭，检查配置并创建备份后，可手动启用。

为什么选择 SmoothLogin？

玩家登录时会涉及多个文件。在主线程读取玩家 NBT、解析统计数据或进度，可能会在存储速度较慢或多人同时加入时造成明显的游戏刻卡顿。SmoothLogin 会在专用工作线程上准备这些数据，再将处理结果交回正常的服务器登录流程。

用户缓存的保存操作也会交由异步写入器串行处理，避免并发登录时互相覆盖更新。

异步登录功能

• 在后台线程准备玩家数据 — 读取玩家 NBT 时不会阻塞正常的服务器游戏刻循环。
• 预先解析统计数据和进度 — 在主线程需要数据之前，先完成文件读取和 JSON 解析。
• 可配置的工作线程池 — 可根据服务器的 CPU 和存储情况，选择 1 到 32 个登录工作线程。
• 串行写入用户缓存 — 防止并发登录任务互相覆盖usercache.json更新。
• 生命周期安全的缓存 — 已准备的数据仅供对应的登录流程使用，并会在使用后或断开连接时清除。
• 仅服务端 — 玩家无需安装此模组。

可选 UUID 迁移

更改身份验证方式可能会导致同一玩家获得不同的 UUID。SmoothLogin 提供迁移工具，可在离线模式、经过身份验证的皮肤站以及 Mojang 身份验证之间迁移与 UUID 关联的数据。

• 启用后自动迁移 — 默认关闭；启用后，会检测与同一玩家名称关联的旧 UUID，并且只有通过策略与安全检查时才会执行迁移。
• 手动迁移工具 — 查看身份记录、绑定已知旧 UUID、启动迁移，或撤销最近一次迁移；无需启用自动迁移。
• 广泛的数据覆盖范围 — 支持原版玩家数据、统计数据、进度、管理员、白名单和封禁名单，也支持受支持的 UUID 命名路径及世界数据中的 UUID 引用。
• 事务安全 — 检查源和目标状态、创建备份、记录迁移历史，并在迁移失败时尝试回滚。
• 冲突保护 — 绝不会自动覆盖目标 UUID 下已有的玩家数据。情况不明确时会记录下来，供管理员检查。
• 登录保护 — 如果源玩家或目标玩家在线，或正在登录，则拒绝迁移。

支持环境

• Minecraft 26.1 或更高版本
• Fabric Loader 0.17.3 或更高版本
• Fabric API
• 专用服务器；无需在客户端安装

安装

1. 在服务器上安装 Fabric Loader 和 Fabric API。
2. 将 SmoothLogin 放入服务器的mods目录。
3. 启动服务器一次以生成config/smoothlogin.json。
4. 默认配置即可使用异步登录流程；无需进行迁移设置。
5. 如果需要迁移 UUID，请先检查相关设置并完整备份世界，再启用autoMigrate或运行迁移命令。

命令

所有命令都需要管理员权限。

| 命令 | 用途 |
| ——————————————————– | ——————————————————————————- |
| /smoothlogin info <name> | 显示匹配的用户缓存身份信息和最近的迁移记录。 |
| /smoothlogin migrate <name> | 检测旧身份，并在安全的情况下启动迁移。 |
| /smoothlogin bind <name> <old-uuid> | 手动将已知旧 UUID 迁移到当前解析出的玩家 UUID。 |
| /smoothlogin undo <name> | 使用对应的准确备份还原最近一次可撤销的迁移。 |
| /smoothlogin conflicts list | 显示尚未解决的迁移冲突。 |
| /smoothlogin conflicts resolve <name> <keep\|old\|new> | 记录管理员的处理决定，但不会自动删除玩家文件。 |
| /smoothlogin automigrate | 显示自动迁移是否已启用。 |
| /smoothlogin automigrate <on\|off> | 启用或禁用自动迁移，并保存设置。 |
| /smoothlogin reload | 重新加载配置并应用运行时设置。 |

配置

配置文件位于config/smoothlogin.json。

| 选项 | 默认值 | 说明 |
| ————————— | ——–: | —————————————————————————————————————————————— |
| autoMigrate | false | 启用登录时自动迁移 UUID。异步登录准备无需启用此选项。 |
| notifyPlayerOnMigrate | true | 迁移成功后通知玩家。 |
| backupKeep | 10 | 保留的迁移备份数量。 |
| migratePlayerdata | true | 迁移物品栏、位置及其他玩家 NBT 数据。 |
| migrateStats | true | 迁移统计数据。 |
| migrateAdvancements | true | 迁移进度。 |
| migrateOpsWhitelistBans | true | 同步管理员、白名单和封禁名单条目。 |
| skinStationNamesUnique | true | 允许在当前配置的身份验证环境中根据玩家名称自动迁移。如果无法保证名称唯一，请禁用此项。 |
| strictMode | false | 拒绝可信度较低的名称匹配证据，并要求手动审核。 |
| usercacheMaxEntries | 10000 | 用户缓存中保留的条目上限。 |
| loginThreadPoolSize | 4 | 用于登录准备的工作线程数；有效范围为 1–32。 |

重要说明

• UUID 迁移是可选功能，异步登录准备不依赖此功能。
• SmoothLogin 无法在所有身份验证配置下证明两个身份属于同一玩家。如果要启用自动迁移，请使用strictMode，禁用skinStationNamesUnique；如果玩家名称不足以作为可靠的身份依据，请使用手动绑定。
• 自动迁移需要可用的身份历史记录，通常来自服务器的用户缓存。
• 如果目标 UUID 下已存在数据，则会视为冲突，不会覆盖。
• 请另行保留完整的服务器备份。SmoothLogin 的事务备份针对单次迁移设计，不能替代常规备份策略。

基于GPL-3.0-only许可。