Folia服务器1.20.4版本玩家登录卡死问题分析与解决方案

问题现象

在Folia服务器1.20.4版本中，当启用白名单功能后，如果玩家首次尝试加入服务器时因未在白名单中被踢出，后续即使被添加至白名单，也会出现无法正常登录的情况。具体表现为：

1. 客户端卡在"Joining world..."界面
2. 服务端日志仅显示玩家UUID认证信息，无后续加载流程
3. 必须通过完全重启服务器才能恢复

技术分析

该问题属于核心线程阻塞类故障，从现象来看涉及以下关键点：

1. 认证流程中断
   服务端日志显示玩家UUID认证完成后，未触发后续的玩家实体加载流程，表明白名单验证环节存在逻辑缺陷。

2. 状态机卡死
   首次白名单验证失败后，服务器未能正确重置玩家的连接状态，导致后续请求被错误拦截。

3. 版本特异性
   问题仅出现在特定Folia版本（git-Folia-"8939611"），回退到早期版本（git-Folia-"7bc26ec"）可规避，说明是版本迭代引入的回归问题。

影响范围

该缺陷主要影响：

• 使用白名单管理的服务器
• Folia 1.20.4特定构建版本
• 首次连接被拒的玩家账号

临时解决方案

1. 版本回退
   降级至稳定版本 git-Folia-"7bc26ec"

2. 服务端重启
   每次修改白名单后执行完整重启：

   /stop
   

3. 备用验证方式
   临时关闭白名单功能，改用其他权限管理插件

根本解决

该问题已在后续提交（e22501a）中修复，建议用户：

1. 更新至最新Folia版本
2. 验证白名单功能时使用/testfor命令检查状态
3. 监控玩家连接时的线程状态

最佳实践建议

1. 白名单修改后建议等待30秒再尝试连接
2. 重要操作前备份whitelist.json文件
3. 使用CoreProtect等插件记录管理员操作
4. 对新版本进行测试环境验证后再上线

该案例典型展示了分布式服务器架构中状态同步的复杂性，建议开发者在类似功能实现时加强连接状态机的健壮性测试。