PeerBanHelper WebUI 登录故障排查指南

问题现象分析

在PeerBanHelper项目使用过程中，用户反馈从6.0.4版本升级到6.2.1后出现WebUI无法登录的情况。典型表现为：

1. 直接使用config.yml中的token无效
2. 清空token后未自动进入引导界面
3. 服务模式下新生成token仍无法登录

根本原因解析

该问题主要涉及两个关键因素：

1. 配置存储位置差异

• 普通用户模式：配置存储在C:\Users\[用户名]\AppData\Local\PeerBanHelper\config
• 系统服务模式：配置存储在系统目录（如C:\Windows\System32\config等）

2. 升级兼容性问题 版本跨度较大时，旧版配置文件可能不完全兼容新版程序，导致认证模块异常

解决方案

常规用户模式修复

1. 通过开始菜单快捷方式启动GUI模式
2. 在程序窗口顶部菜单栏选择"WebUI"→"重置Token"
3. 系统将自动生成新Token并进入引导界面

系统服务模式注意事项

1. 非必要不建议安装为系统服务
2. 如需使用服务模式，应注意：
   • 配置文件位于系统目录
   • 需要管理员权限才能修改
   • 建议通过服务管理器停止服务后再操作

最佳实践建议

1. 升级操作规范

• 升级前备份config.yml文件
• 使用官方卸载程序完全卸载旧版
• 安装新版后不要直接复用旧配置文件

2. 故障排查流程

• 首先尝试GUI模式启动
• 检查日志文件中的认证错误信息
• 确认配置文件路径是否正确

3. 日常维护提示

• 定期检查WebUI访问状态
• 重要操作前记录当前Token值
• 避免跨大版本直接升级

技术原理补充

PeerBanHelper的认证系统采用动态Token机制，该Token：

• 在首次启动时自动生成
• 存储在运行目录的配置文件中
• 与服务运行模式强相关
• 不同运行模式会使用不同的存储位置

理解这一机制有助于快速定位和解决类似认证问题。