白名单与验证码

Bukkit 子服在玩家登录时向机器人实时查询白名单结果。代理网关只负责将查询路由到登录校验子服，不参与玩家判定。

群内申请模式

玩家尝试进入服务器时，如果尚未加入白名单，插件会显示群内申请提示。玩家按提示在机器人所在群发送游戏 ID 即可申请。

游戏内提示 · 按提示在机器人所在群申请白名单

机器人可以要求申请者二次确认，避免输错游戏 ID 后还需要服主协助换绑；关闭二次确认后，申请会直接加入白名单。一个 QQ 可以申请多个游戏 ID，服主可在机器人后台设置单个 QQ 的申请数量上限，最高支持 15 个。

查看机器人后台白名单设置示意图

机器人后台 · 设置每人申请上限与是否开启二次确认

群内申请 · 确认游戏 ID，或修改后重新提交

验证码模式

玩家进入服务器时会获得一次性验证码。将验证码发送到机器人所在群，验证成功后按提示重新连接服务器即可完成白名单申请。

游戏内提示 · 获取本次登录验证码，并发送到机器人所在群

群内验证 · 验证通过后机器人会回复申请结果

模式配置

mode	行为
whitelist	无白名单玩家看到群内申请提示；已有白名单玩家放行
captcha	为玩家生成短期验证码；在群内验证后，玩家于有效期内重新连接

启用方式：

whitelist_check:
  enabled: true
  mode: "whitelist"
  login_query_timeout_ms: 1200

独立单服按需启用即可。代理集群中只能有一个子服设置 enabled: true 并使用 whitelist 或 captcha；其他子服保持关闭，否则代理会拦截白名单登录请求并报告冲突。

验证码

whitelist_check:
  captcha:
    timeout_seconds: 180
    length: 4
    type: "numeric"
    every_login: false

type 为 numeric 或 alphanumeric；后者使用大写字母和数字并排除易混淆字符。开启 every_login 后，已有白名单玩家每次登录也须由白名单绑定人发送验证码。验证通过不会让当前连接继续挂起，玩家应在有效时间内重新连接。

提示文本支持换行、&0 至 &f 颜色字符、{player} 和验证码提示中的 {code}。

登录校验

机器人是白名单数据的权威来源。Bukkit 插件在异步预登录阶段查询机器人，超时、机器人不可用或并发达到上限时会拒绝本次登录，避免未校验玩家进入服务器。验证码有效期、长度和字符类型可在 whitelist_check.captcha 中设置；every_login 可要求已有白名单玩家每次登录也进行验证。