定时任务与白名单申请

← 插件与自动化 · 所有分区

VexBot 0.6.30。所有业务设置均在面板调整，不需要修改配置文件。定时任务和白名单申请默认保存在 SQLite，启用 MySQL 后写入所选数据库，随 VexBot 备份一起保存。

定时任务

进入「扩展 → 插件管理」，在内置「定时任务」插件卡片点击「管理任务」，再点击「新建任务」。全新安装时插件和新任务均默认停用；可在插件卡片或任务页启用插件，再按需启用任务。支持：

• 间隔执行：1–43200 分钟。保存、修改或重新启用时，从当前时间重新计时。
• 指定星期与时间：选择周一至周日及 HH:MM，使用北京时间（Asia/Shanghai / UTC+8），不随服务器系统时区变化。
• 动作：群公告、游戏公告、执行服务器已配置的预设命令、创建备份。命令不能输入任意脚本，只能选「自动化 → 游戏指令」中允许的命令。

群公告最多 2000 字，游戏公告最多 600 字，均发送文字消息。

「立即执行」可以验证停用的单个任务，但必须先启用定时任务插件，并满足动作和目标权限；它不会启用单个任务或改变周期。游戏公告与命令提交后等待游戏插件确认；结果未确认不视为成功，先核对游戏状态再重试。待确认的任务不能再次执行。修改关联群或命令后，每次执行仍会重新检查配置。关闭任务或插件只停止未来执行，不撤回已经发送或提交的操作。

插件卡片的「权限」分别控制群公告、游戏公告、预设命令和备份，并可限制服务器与群范围；任务执行时重新检查权限。QQ 使用者名单适用于群命令，不适用于由面板管理的定时任务。团队成员仍需 schedules.manage 管理任务，plugins.manage 用于管理插件权限。

首次升级时保留所有任务和执行记录；若原有启用的任务，自动启用定时任务插件以延续原行为。此迁移只执行一次，停用后的插件不会因重启、重新加载或扫描再次启用。重新启用插件时跳过暂停期间已经到期的任务，不集中补发。

主程序每 2 秒检查一次任务。停机期间超过 60 秒的过期任务跳过，不会重放或集中补发；程序重启后没有确认的执行标记为未完成。QQ 断线、游戏离线、队列已满或备份容量耗尽时，本次记为失败，下次按正常周期执行。执行记录保留最多 500 项，面板显示最近 30 次；任务最多 100 项。

自动备份保存在 data/backups，不会触发浏览器下载。最多保留 100 份，默认不自动删除；可在「备份与恢复」设置保留策略，或定期下载并删除不需要的备份。备份包含连接密钥与密码哈希，请妥善保管。

插件权限

在「扩展」的插件卡片点击「权限」。内置关键词回复和导入的 JSON 规则插件可设置：

权限	生效范围
发送群消息	总开关；关闭后不发送任何插件回复或通知
群命令 / 关键词回复	群内指令和关键词响应
游戏事件	入服、退服通知
读取绑定玩家名	回复模板中的绑定玩家名；关闭后不提供绑定姓名
读取服务器状态	在线人数、在线列表、在线状态；关闭后模板显示“未授权”
服务器 / 群范围	指定服务器 ID、QQ 群号；留空允许所有已关联范围
使用者	所有成员、已绑定成员、机器人管理员
QQ 允许名单	填写后，只有名单内 QQ 能使用群命令
QQ 拒绝名单	始终拒绝名单中的 QQ，即使同时在允许名单或是管理员

群命令同时受插件规则里的 admin_only / bound_only 限制，面板授权不能绕过规则。使用者和 QQ 名单针对群命令；游戏事件通知按事件权限及服务器、群范围筛选。插件始终只在已配置的服务器关联群运行，授权不会增加任意代码、网络、文件或控制台执行能力。

升级时已有插件保留原有权限。新导入插件仍默认停用，启用前可以先调整权限。权限单独保存并立即生效，重启、重新加载、备份恢复都保留；导入的 JSON 文件不能自行修改授权。

白名单申请

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

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 秒没有确认标记为「执行未确认」，不会盲目重放；先检查游戏白名单，再决定重试。审核状态有版本校验，多个面板不能重复批准同一版本。

备份与恢复

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

管理 API

以下接口接受服主管理令牌或具有相应权限的团队管理员会话令牌 Authorization: Bearer <token>，不接受网站注册密钥、普通用户会话或游戏桥接令牌。定时任务接口需要 schedules.manage，插件权限接口需要 plugins.manage；白名单审核需要 whitelist.review，申请设置变更仍仅服主可用。响应禁用缓存。

方法	路径	用途
GET / POST	/api/schedules	列表和最近执行 / 新建，正文 {definition}
PUT	/api/schedules/plugin	启停内置插件 {enabled,revision}；revision 使用列表中的 plugin_revision
PUT / DELETE	/api/schedules/{id}	完整更新 {definition,revision} / 删除 {revision}
POST	/api/schedules/{id}/run	立即执行 {revision}；结果可能仍待游戏端确认
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 可省略
PUT	/api/extensions/{id}	原插件设置接口增加 permissions，需当前插件 revision
GET	/api/operations/guide	下载本使用文档

任务 definition 的完整结构：

{
  "name": "每日备份", "enabled": false,
  "schedule": "daily", "interval_minutes": 60, "clock": "03:00",
  "weekdays": [1,2,3,4,5,6,7], "action": "backup",
  "server": "", "group": "", "message": "", "command": ""
}

schedule 为 interval 或 daily，action 为 qq_message、game_message、command、backup。与动作无关的字段仍提供合法默认值。任务时间戳使用 Unix 秒。