白名单申请与审核

← 玩家与账号 · 所有分区

白名单申请

先由服主进入 设置 → 功能开关 开启「白名单申请」，再在成员页调整申请要求。关闭开关后隐藏入口并停止新申请；已有记录仍保存，重新开启后继续管理。

1. 在「成员 → 白名单申请」开放群内申请，选择是否要求同名注册账号、同名游戏绑定，设置申请冷却和待审核上限。默认关闭，不自动批准。
2. 玩家在服务器关联群发送 /白名单 玩家名 [申请理由]，机器人从消息发送者取得 QQ 号，不能代填他人的 QQ。/白名单状态 查询自己的最近申请。邮箱注册仍使用 /申请，两者分开。
3. 管理员在面板审核申请、填写审核备注，选择批准或拒绝。面板也支持管理员代提交申请；代提交不受开放开关或玩家资格限制，仍需要审核。
4. 批准后向游戏插件提交专用白名单任务。只有游戏端返回成功才显示「已加入白名单」，并通知原申请群。游戏离线或旧插件时保持「已批准，待下发」，连接后点击「重试下发」。

玩家名为 Java 版的 1–16 位字母、数字或下划线。首次入服通常不能先在游戏中绑定，需绑定限制按实际用途开启；需注册限制要求同名账号的 QQ 邮箱与申请人 QQ 一致。申请理由只作审核材料，未开启资格限制时管理员需自行核对申请者身份。

Paper / Spigot / Folia 游戏端使用 VexBot-0.5.5.jar，可在面板下载并替换旧 JAR 后重启 Minecraft 服务器；Forge / NeoForge / Fabric 按版本下载对应模组。Folia 安装与 Java 要求见 Folia 接入。游戏服务器的 whitelist 开关继续由服务器管理，不会被申请审批自动开启。审批不会自动绑定 QQ、修改登录密码或授予 OP；被游戏封禁的玩家不会通过白名单任务解封。

离线服务器首次申请使用 OfflinePlayer:<玩家名> 计算 UUID，玩家名大小写必须与进服时一致。正版服务器在有界后台线程查询 Minecraft 官方玩家身份，校验玩家名与可用的 UUID，超时、不存在或身份不匹配时返回失败；网络查询不会占用游戏主线程或 Folia 区域线程。Folia 的白名单与档案封禁任务在全局调度执行，涉及在线玩家的消息和踢出回到其实体线程，收到实际回执后才显示执行结果。启用代理 UUID 转发的服务器，请在审核窗口填写玩家的实际 UUID；正版服务器同时校验 UUID 与玩家名是否匹配。

重复的待审核、待下发、待确认申请会拦截；拒绝后的重新申请受冷却限制。待审核上限可设 1–500，终态历史最多保留 2000 条，每页 25 条。下发超过 75 秒没有确认标记为「执行未确认」，不会盲目重放；先检查游戏白名单，再决定重试。审核状态有版本校验，多个面板不能重复批准同一版本。

网站自助申请

官网登录后的本人服务也可提交申请并查看进度：POST /api/v1/me/whitelist 正文为 {server,reason}，使用当前用户短期令牌。玩家名和 QQ 由账号决定，不能代传他人身份，仍复用开关、资格、冷却和人工审核。详见官网本人服务。

备份与恢复

定时任务定义、运行历史、申请、审核备注、申请设置、插件授权都包含在备份中。恢复后定时任务自动停用，未完成的游戏执行和白名单下发撤销；确认服务器、群与命令后再启用任务。白名单申请记录恢复不会直接修改 Minecraft 的 whitelist 文件，游戏世界及服务端文件仍需独立备份。兼容升级前 0.4.0 的 VexBot 备份。

管理 API

审核需要服主或 whitelist.review 团队会话，申请设置变更仅服主可用。使用管理 Bearer 令牌，不接受网站密钥、普通用户或游戏桥接令牌。

方法	路径	用途
GET / PUT	/api/whitelist/settings	查询 / 保存 {settings,revision}
GET	/api/whitelist?status=pending&page=1	设置与申请列表
POST	/api/whitelist	管理员代提交 {server,player,qq,reason}
POST	/api/whitelist/{id}/review	{action,revision,note,uuid}；action 为 approve、reject、retry，note/uuid 可省略

409 表示版本冲突等状态变更，应重新读取再审核；执行未确认时先检查游戏端状态，避免重复下发。

业务记录使用 Bot 主数据库：新安装默认 SQLite，也可按MySQL 存储指南配置 MySQL。不要把‘默认 SQLite’理解为仅支持 SQLite。配置目录下的插件状态和网站设置仍为各自 JSON 文件；具体备份范围见备份与恢复。

完整自动化指南 · 团队权限。