常见问题与排查

← 入门与部署 · 所有分区

先进入 接入空间 → 连接诊断 查看当前状态，再进入 活动 → 运行日志 对照最近一次操作。记录错误时间、服务器 ID、Bot 和游戏端版本；分享日志时隐藏令牌、邮箱授权码和个人信息。

完整诊断操作见 连接诊断。本页对应 Bot 0.6.30 / Bukkit 游戏插件 0.5.5。

按现象检查

现象	先检查什么	对应教程
BAT 运行后面板没打开	安装输出、data/server.log、data/server-error.log、Python 与目录是否完整	Windows 安装
Linux 报环境或依赖错误	是否用当前项目虚拟环境，Python 是否为 3.11+	Linux 安装
面板登录失败	服主或团队账号的用户名、密码及启用状态是否正确；首次无服主账号时先创建	面板登录
新版控制台 5801 打不开或提示后台不可用	前端和 Bot 是两个进程；先检查 5800，再检查 webui-preview 是否启动及代理地址	新版 WebUI 控制台
新版控制台网站详细设置不显示	使用服主账号进入「控制台设置」；选择「自定义网站」显示地址，「VexBot 官网」还显示内容与外观	网站设置
QQ 一直未连接	反向 WebSocket URL、Universal、令牌与已登录 QQ 账号	OneBot 连接
游戏服未连接	JAR 是否启用、endpoint、服务器 ID、游戏令牌和启动日志	快速开始、版本与 Java
群里没有回复或聊天没同步	群路由、功能开关、机器人在线状态和实际目标游戏服	消息同步、群命令
绑定验证码无效	是否在有效期内、是否来自该群关联的服务器	QQ 绑定
注册邮件未收到	注册开关、SMTP、发送额度、邮箱垃圾邮件与故障记录	注册接口
游戏密码或 QQ 确认不通过	启用服务器、密码设置、已有绑定和原生登录插件要求	游戏登录
官网能打开但 API 不通	Bot API 地址、端口、HTTPS 与允许的网页来源	独立官网
定时任务没有运行	插件是否启用、任务是否启用、时间和动作授权	任务与申请
备份、恢复或更新失败	文件大小、磁盘空间、包格式与操作记录	备份、更新

面板与连接地址

127.0.0.1 指发起访问的机器自身。在另一台电脑或手机打开面板，需要使用 Bot 主机的可达地址；游戏服、QQ 实现端在别的机器上时，同样不能把 endpoint 或 WebSocket 地址写成它们自己的 127.0.0.1。

监听端口占用时先确认有没有已运行的 VexBot 实例。一个安装目录只运行一个 Bot；Windows 用 BAT 菜单管理，Linux 使用部署时的命令或服务管理方式。修改监听地址和端口后，保存并重启，再更新外部组件的连接地址。

QQ 已连接，群里仍没反应

1. 到「接入空间 → 服务器列表」检查该群是否关联到了预期服务器。
2. 在群里发送 状态 或 帮助，再看「活动 → 运行日志」。
3. 群命令可回复而聊天不同步时，分别检查群到游戏、游戏到群的开关。
4. 关键词回复要在「扩展 → 插件管理」启用内置插件，检查匹配方式、群范围和回复内容。

短时游戏桥接断线后，尚未过期的事件可能继续发送；长时间断线会导致消息过期，不保证补发。连接恢复后用新消息验收。看到 QQ 已连接也不代表游戏服收到消息，需分别验收两条连接。

游戏插件加载失败

日志线索	处理
UnsupportedClassVersionError	对照实际启动 Java、游戏核心和插件版本；不要只看电脑上另一个 java -version
NoClassDefFoundError / NoSuchMethodError	核对平台与加载器，保存完整核心版本和堆栈，对照兼容说明
JAR 未启用或游戏端无心跳	检查是否放在正确的 plugins/ 或 mods/ 目录，以及是否完整重启
令牌错误或未知服务器	核对该服 ID、Bot 服务器列表和游戏端配置，避免使用管理令牌代替游戏令牌

Paper / Spigot / Folia 用通用 Bukkit JAR；Forge、NeoForge、Fabric 用对应加载器和游戏版本的服务端模组，不能混装。Java 选择及已验证范围见 Minecraft 兼容说明。

注册、绑定与游戏登录

SMTP 检测只检查连接与认证，不证明真实收件成功；邮件到达需要通过一次实际注册或密码重置验收。保留验证限额，先检查邮箱垃圾邮件与最近错误，不连续重复发送。

社区账号、QQ 绑定、Minecraft UUID 是不同关系。只注册同名账号不会覆盖原有游戏身份；只有 QQ 登录且玩家尚未绑定时，待登录状态不能运行 /qbind。由管理员核实身份后绑定，或先开放密码登录，见 绑定前提。

nLogin 先用 /starbridge:login 或 /starbridge:ql，再完成原生 /login 或 /register；按文档合并其命令白名单并开放 VexBot 提示。普通 /login、/l 会与 nLogin 冲突。已有原生账号需要原密码或有效原生认证，不能拿网站密码覆盖。

LibreLogin 0.24.0 Paper 缺少可用 TOTP 校验器，带 TOTP 密钥的账号会被 VexBot 拒绝。Folia 不接入这些外部登录 API。完整规则和实服范围见 登录插件接入。

任务已提交但未成功

预设游戏命令、白名单、玩家管理和跨服处罚都需要游戏端回执。「已提交」「等待确认」只代表任务已创建，不能作为游戏操作成功的依据。

核对服务器在线状态、目标身份、权限与游戏命令白名单，再查看执行结果。白名单申请通过不会自动让原生 white-list 设置开启；跨服处罚也不会按同名猜测 UUID。工单与处罚 说明了重试与独立封禁的处理。

官网跨域和凭据

允许来源匹配网页的协议、域名与端口；路径不属于来源。不要用通配符代替精确来源。浏览器使用公开接口或玩家短期令牌；后端只读接口用独立网站 API 密钥，不能把该密钥写进网页。

选择「不接入」会移除绑定来源的授权，但不等于关闭所有独立配置的 API。官网和 Bot 分开部署时需要分别核对地址与更新，见 官网接入。

没有显卡是否能用

面板和官网没有 WebGL、背景视频或持续动画，使用文本、普通表格和短时过渡。性能还取决于 CPU、内存、浏览器和数据规模；排查时先关闭无关标签页、减少动态效果，并检查 Bot 有没有反复连接或大量错误日志。

需要反馈问题时，提供复现步骤、发生时间、核心及 Java 版本、相关日志片段和实际错误结果，不提供密码、管理令牌或邮件验证码。