常见问题

Q: 启动后日志显示「OneBot 连接失败」

• 确认 NapCat 已启动并登录机器人 QQ
• 确认 NapCat 的 WS 端口与配置文件 target 一致
• 确认 BDS 服务器能访问到 NapCat（同机用 127.0.0.1，跨机用实际 IP）
• 若用了 access_token，两端必须一致

Q: 群消息能到游戏，但游戏消息到不了群

• 检查 sync.chat_to_group_enable 是否为 true
• 确认机器人 QQ 在目标群内
• 控制台执行 /lumen status 确认连接正常

Q: 白名单绑定提示「服务器未能添加白名单」

• 确认服务器已开启白名单（/whitelist on）
• 确认 XboxID 拼写正确（含空格需用引号包裹：绑定白名单 "Player One"）
• 查看控制台是否有 /whitelist add 的错误输出

Q: WebUI 打不开

• 确认 webui.enable 为 true
• 确认端口未被占用
• 若需外网访问，把 webui.host 改为 0.0.0.0，并在防火墙放行端口
• 安全建议：WebUI 暴露公网会被扫描器骚扰（虽已修复崩溃漏洞），建议用 127.0.0.1 + 反向代理 + IP 白名单

Q: 改了配置不生效

• 大部分配置可用 /lumen reload 热重载
• 连接参数（connection 下的字段）改动需重启服务器
• WebUI 修改配置会自动保存并热重载

Q: 如何更新插件

• 下载新版 .whl，覆盖 plugins 目录里的旧文件
• 重启服务器即可，配置文件和白名单数据会保留
• 若有破坏性变更，会在更新日志中说明

Q: 服务器日志频繁出现 ConnectionResetError

这是外网扫描器连上 WebUI 端口后断开导致的。v1.0.0 已修复此问题导致的崩溃，若仍看到少量日志，建议：

• WebUI 监听地址改为 127.0.0.1
• 或在防火墙限制 WebUI 端口的访问 IP

---