LeavesAntiIllegal 服主手册

先确认运行环境

此版本以标准 Bukkit 主线程模型为目标，不再使用 Folia 区域调度器。插件以 Bukkit API 1.20.1 编译，可运行于 1.20 至 26.2 的 Bukkit API 兼容服务端，服务器需要 Java 17 或更高版本。

全新安装

1. 停止服务器并做世界备份至少保留所有世界目录和现有 plugins/。
2. 检查 Java 与核心使用 Java 17 或更高版本，核心版本为 Minecraft 1.20 至 26.2 的 Bukkit API 兼容服务端。
3. 放入插件将 LeavesAntiIllegal-3.1.1.jar 放到服务器 plugins/。
4. 启动一次等待生成 plugins/LeavesAntiIllegal/config.yml，确认控制台出现启用日志。
5. 先做演练把离线扫描的 dry-run 改成 true，重载后观察一个低峰窗口。

server/
├── server-1.20-to-26.2.jar
├── plugins/
│   ├── LeavesAntiIllegal-{version}.jar
│   └── LeavesAntiIllegal/
│       ├── config.yml
│       └── scanner-state.properties
└── world/playerdata/

scanner-state.properties 在一次离线全量扫描成功结束后生成，用于记录最近完成日期，避免同一天重复遍历。

从 FoliaAntiIllegal 升级

项目名、插件名、主类和 Java 包均已更改。Bukkit 会因此使用新的数据目录，旧配置不会自动进入新插件。

1. 关闭服务器不能热替换插件 JAR，也不要同时保留新旧两份 JAR。
2. 移走旧 JAR保留旧数据目录作为参考，但不要让旧插件再次加载。
3. 让新版本生成配置新配置包含 2.0.0以及更高版本 的全部字段和逐行中文注释。
4. 逐项合并业务规则迁移 banned-materials、附魔/属性阈值、白名单和自定义消息。
5. 演练后启用写回不要直接用旧配置覆盖配置版本 3。

推荐的分阶段上线

1. 第一阶段：只观察离线数据设置 scanners.offline-player-data.dry-run: true，在线与容器扫描仍会正常移除。
2. 第二阶段：核对误报重点检查不可破坏物品、玩家头颅、自定义属性装备和插件附魔。
3. 第三阶段：调整白名单和规则合法运营道具应从禁止材料中删除或放宽对应检测项，不要长期给普通玩家绕过权限。
4. 第四阶段：启用离线写回保持 backup-before-write: true，把 dry-run 改为 false。

scanners:
  offline-player-data:
    enabled: true
    dry-run: true
    backup-before-write: true
    log-each-removal: true

确认后将 log-each-removal 恢复为 false，否则大量历史违规可能显著增加日志量。

扫描器如何覆盖物品

嵌套扫描默认最多 3 层，覆盖潜影盒、带库存的方块状态物品和收纳袋。增加深度会提高恶意复杂 NBT 的处理成本。

关键配置怎么选

发行包中的 config.yml 已为每个节点、字段和列表项提供中文解释、默认值与示例。以下是运维时最常调整的参数。

扫描节奏

判定规则

低峰扫描的边界与保护

离线扫描只会在当前时间处于配置窗口、距离上次成功运行已满足天数且在线人数不高于阈值时开始。跨午夜窗口会归属到窗口开始日。

推荐窗口示例

scanners:
  offline-player-data:
    time-zone: "Asia/Shanghai"
    window-start: "03:30"
    window-end: "05:30"
    minimum-days-between-runs: 1
    max-online-players: 2
    files-per-batch: 5
    batch-delay-ticks: 40

• 窗口结束时未完成的一轮会停止，不写入成功日期，下个合适窗口会重新枚举。
• 在线人数超过阈值时当前批次暂停，不会继续读下一个文件。
• 玩家预登录、在线期间和退出后的保护时间内，其 UUID 文件会被跳过。
• dry-run: true 只检测和记录，不创建备份、不写回原文件。

命令与权限

命令别名为 /ai 和 /illegal。离线扫描还会自动跳过服务器 OP 与 UUID 白名单。

备份与单玩家恢复

默认设置下，离线扫描仅在确实发现违禁物且准备写回时，把原文件复制为 <UUID>.dat.fai.bak。同一玩家下次被修改会覆盖该备份，因此它不是长期版本库。

1. 停止服务器确保服务器不会同时保存该玩家数据。
2. 确认玩家 UUID 与世界从日志中的世界名和 UUID 找到对应 playerdata。
3. 保留当前文件把当前 <UUID>.dat 另行复制，以便反向恢复。
4. 恢复备份用 <UUID>.dat.fai.bak 替换 <UUID>.dat。
5. 先修正规则若不调整误报规则，下一次低峰扫描仍会再次移除。

按症状调优

常见问题

插件未加载或显示红色

• 确认服务端版本在 1.20 至 26.2 范围内，并使用 Java 17 或更高版本。
• 确认 JAR 名为 LeavesAntiIllegal-{version}.jar，没有同时保留旧版 JAR。
• 从控制台第一段异常开始检查，不要只看最后一行。

离线扫描没有启动

• 用 /antiillegal status 确认扫描器已启用且当前未在运行。
• 核对 time-zone、窗口起止、在线人数阈值和最近成功日期。
• 检查各世界是否存在 playerdata/，且文件名是标准 UUID。

合法物品被删除

• 从日志读取材料、路径和原因，定位对应规则。
• 运营头颅玩法时从 banned-materials 移除 PLAYER_HEAD。
• 任务物品使用不可破坏标记时关闭 check-unbreakable，或重新设计物品。
• 自定义附魔使用 custom-enchant-limits 明确设置允许值。

配置重载后没有生效

• 先检查 YAML 缩进和控制台解析错误，列表只能保留一种写法。
• 确认命令返回“配置与全部扫描器已重新加载”。
• 用 /antiillegal status 验证开关与任务状态。

正式上线检查表

• 已备份全部世界与旧插件数据目录。
• 服务器版本为 1.20 至 26.2，运行 Java 17 或更高版本。
• 旧 FoliaAntiIllegal JAR 已移除，没有重复加载。
• 已从新配置出发逐项合并规则，而非覆盖整个文件。
• 已检查 PLAYER_HEAD、不可破坏物品、自定义附魔和 RPG 属性。
• 离线扫描已用 dry-run: true 完成一次演练。
• 低峰窗口、时区、在线人数阈值和磁盘批次符合本服情况。
• backup-before-write 保持开启，并验证过单玩家恢复流程。
• 权限只授予需要的管理组，没有给普通玩家 antiillegal.bypass。
• 已执行 /antiillegal status 和一次指定玩家扫描。

插件已经注册bStats

• 为了统计此插件的使用数据（包括使用次数、用户服务器的地理位置（精确到国家）等非细节信息，我们会将数据推送至bStats平台）
• 请放心，此功能仅仅统计插件的使用次数，和您的服务器所在国家，不会上传其他任何数据