CoreProtect — Minecraft Java Edition 1.16 - 1.21.11+

多人 Minecraft 服务器需要对玩家行为进行详细审计，以防止对地图进行未经授权的更改以及盗窃游戏中的贵重物品。服务器的原版核心不会记录地形编辑历史以及容器中物品的移动，因此管理员无法识别违规者，也无法在不从备份完整还原地图文件的情况下撤销破坏。服务端插件 CoreProtect 会记录所有改变世界的事件，建立详细的用户行为索引，并基于复杂的参数化查询对区域执行精确的回滚（rollbacks）。该工具以异步模式运行，将事务写入队列，以保护服务器主线程免受延迟影响。

1. 数据库与异步日志记录架构

CoreProtect 插件借助 Bukkit/Paper API 的事件处理器拦截服务器事件。为了防止在每秒处理数千条记录时阻塞服务器主线程（Server Thread），该插件采用异步日志记录模型。事件（破坏方块、更改箱子物品栏、使用命令）首先被放入内部动态缓冲区 DataQueue。后台消费者线程（Consumer Thread）从缓冲区读取事务，并以批处理事务（Batch processing）的方式将其写入数据库，从而降低存储设备的负载。

该插件支持使用两种数据库管理系统（DBMS）：

1. SQLite（默认本地）：所有信息都写入插件目录中的 database.db 文件。SQLite 无需安装第三方服务，因此便于事务量较低的小型本地服务器使用。

2. MySQL / MariaDB（外部服务器）：使用网络连接到独立的数据库服务器。该方案是大型服务器和在线人数较高的服务器网络（50 名玩家起）的行业标准。MySQL 可保证索引查询的高执行速度，并避免本地存储的碎片化。

数据库表结构

CoreProtect 创建一组关系表以优化数据存储。该插件不会为每条记录存储完整的文本字符串，而是使用字典表来存放唯一的玩家名称、世界、方块类型和实体。

所有坐标 x、y、z 都与世界标识符 wid 一同建立索引，以确保能在给定半径内即时检索事务。

2. 命令语法与过滤参数

与 CoreProtect 数据库的交互通过文本命令进行。主要操作有：检查、查询、回滚以及撤销回滚。

检查器模式 /co inspect 或 /co i)

该命令将客户端切换到本地审计模式。激活后，玩家可以与世界交互以获取日志：

·        左键单击现有方块会在聊天中显示放置它的人的昵称、日期、时间和坐标。

·        右键单击空白平面（或方块）会显示先前占据该空间或已被拆除的方块历史。

·        右键单击容器（箱子、熔炉、桶、潜影盒）会显示物品移动的日志。

查询过滤参数 /co rollback、 /co restore、 /co lookup)

为了筛选数据，该插件采用 参数:值 格式的组合参数。参数之间以空格分隔：

1. 用户 u:<名称>)：指定要检查的玩家。可以用逗号指定多个名称（例如 u:Stevie,Alex）。要回滚自然事件，需使用技术标识符：

·        u:#fire – 火焰蔓延。

·        u:#lava – 熔岩漫流。

·        u:#water – 水流漫延。

·        u:#creeper – CREEPER 爆炸。

·        u:#tnt – TNT 爆炸。

·        u:#enderman – ENDERMAN 搬运方块。

2. 时间 t:<数值>)：用于分析的时间区间。支持的计量单位：s（秒）、m（分钟）、h（小时）、d（天）、w（周）、y（年）。允许组合单位，例如：t:2w4d6h（2 周、4 天和 6 小时）。

3. 半径 r:<数字>)：以命令执行者为中心的搜索区域半径（以方块计）。同时支持特殊值：

·        r:#global – 在整个数据库中搜索（涵盖所有已加载的区块）。

·        r:#world – 在当前游戏世界范围内搜索。

·        r:#chunk – 在玩家当前所在区块内搜索。

·        r:#selection（或 r:#we）– 将搜索限制在当前 WorldEdit 选区范围内。

4. 操作 a:<类型>)：按操作类型过滤记录：

·        a:block – 方块的放置与破坏。

·        a:+block – 仅方块放置。

·        a:-block – 仅方块破坏。

·        a:container – 物品栏事务。

·        a:+container – 向容器中添加物品。

·        a:-container – 从容器中取出物品。

·        a:kill – 动物和怪物的死亡。

·        a:spawn – 实体的生成。

·        a:chat – 聊天消息。

·        a:command – 输入的命令。

·        a:session – 玩家登录。

5. 方块 b:<材料>)：将搜索限制为指定材料（例如 b:stone,oak_planks）。

6. 排除 e:<材料>)：将材料从处理中排除（例如 e:tnt）。

回滚预览与撤销操作

为了在大规模回滚期间最大限度减少错误，CoreProtect 支持可视化模拟系统：

1. 带有 #preview 标志执行回滚命令（例如 /co rollback u:Griefer t:2h r:20 #preview）不会更改地图文件。相反，客户端会在当前渲染会话中收到方块更改数据包。管理员看到的是"回滚后"状态的世界，而对其他玩家而言方块保持不变。

#preview

/co apply

2. 要应用结果，请使用命令 /co apply。

3. 要取消预览，请使用命令 /co cancel。

4. 要撤销已执行的物理回滚，需使用命令 /co undo，它会将坐标恢复到执行 /co rollback 之前的状态。

3. 配置文件 config.yml 的完整说明

该配置文件控制各项限制、日志记录参数以及数据库连接。

通用参数块（General Settings）

·        verbose: true – 在执行回滚期间，向控制台输出关于每个被修改坐标的详细报告。如果设为 false，则仅输出已更改方块的总数。

·        check-updates: true – 在启动时检查开发者服务器上是否有插件的新版本。

·        api-enabled: true – 允许第三方插件与 CoreProtect 的数据进行交互。

·        default-radius: 10 – 当命令中未指定该参数时使用的默认回滚半径。

·        max-radius: 250 – 限制单条命令的最大半径。值 0 表示取消该限制。

日志记录参数块（Logging Settings）

这些参数决定哪些事件会被写入数据库。关闭不需要的日志有助于减小数据库的体积：

·        block-place: true / block-break: true – 记录玩家对方块的常规放置与破坏。

·        natural-break: true – 记录因位移或支撑方块被破坏而导致的方块掉落（例如，破坏火把所附着的方块）。

·        block-movement: true – 记录沙子、沙砾或混凝土的重力下落。

·        pistons: true – 记录使用活塞移动方块。

·        block-burn: true – 记录方块被火烧毁。

·        block-ignite: true – 记录玩家使用打火石或火球点燃方块。

·        explosions: true – 记录 TNT、CREEPER、下界中的床或末地水晶的爆炸。

·        entity-kills: true – 记录村民、动物、怪物和盔甲架的死亡。

·        player-chat: true / player-command: true – 记录聊天消息和控制台命令。

·        player-session: true – 记录玩家登入和登出服务器的时间。

·        container-transactions: true – 记录在箱子、熔炉、漏斗和潜影盒中移动物品的操作。

数据库块（Database Settings）

·        use-mysql: false – 数据库类型开关。如果设为 true，插件将连接到外部的 MySQL DBMS。

·        table-prefix: co_ – SQL 表名的前缀。

·        mysql-host: localhost – MySQL 数据库服务器的 IP 地址或域名。

·        mysql-port: 3306 – 用于连接的网络端口。

·        mysql-database: minecraft – 目标数据库的名称。

·        mysql-username: root – 数据库用户名。

·        mysql-password: password – 用户的密码。

·        mysql-ssl: false – 启用到数据库服务器连接的 SSL 加密。

4. 面向插件开发者的 API

CoreProtect 通过 CoreProtectAPI 类为开发者提供访问其数据库的接口。这使得其他插件（例如 WorldEdit 或保护系统）能够记录其更改或执行自动的历史查询。

API 的初始化

要连接到 API，需使用初始化方法：

API 接口的主要方法

·        boolean logPlacement(String user, Location location, Material type, BlockData blockData) – 以指定用户的名义在数据库中记录方块的放置。

·        boolean logRemoval(String user, Location location, Material type, BlockData blockData) – 记录方块的破坏。

·        boolean logContainerTransaction(String user, Location location, Material type, ItemStack itemStack, boolean isAdded) – 记录从容器中添加（true）或取出（false）物品的操作。

·        List<String[]> performLookup(int time, List<String> restrictUsers, List<String> excludeUsers, List<Object> restrictBlocks, List<Object> excludeBlocks, List<Integer> restrictActions, int radius, Location location) – 按指定的过滤条件执行查询并返回结果数组。

·        List<String[]> performRollback(int time, List<String> restrictUsers, List<String> excludeUsers, List<Object> restrictBlocks, List<Object> excludeBlocks, List<Integer> restrictActions, int radius, Location location) – 启动对世界中更改的异步回滚。

·        List<String[]> performRestore(int time, List<String> restrictUsers, List<String> excludeUsers, List<Object> restrictBlocks, List<Object> excludeBlocks, List<Integer> restrictActions, int radius, Location location) – 启动对更改的异步还原。

·        boolean hasPlaced(String user, Block block, int time, int offset) – 检查指定玩家是否在某段时间内放置过该方块。

·        boolean hasRemoved(String user, Block block, int time, int offset) – 检查指定玩家是否破坏过该方块。

5. 性能、兼容性与维护

在高在线人数的服务器上使用 CoreProtect 时，管理员需考虑与现代服务器架构交互的特点：

·        Folia 支持：Folia 服务器核心采用区域化多线程（Regionized multithreading），这要求插件在操作世界时具备严格的线程安全性。CoreProtect 已适配 Folia：/co rollback 和 /co restore 操作的执行通过区域调度器（Region Scheduler）进行，从而避免区块访问冲突以及 ConcurrentModificationException 等严重错误。

·        MultiPaper 集群：在 MultiPaper 类型的服务器上，CoreProtect 被配置为使用单一的外部 MySQL 数据库。这有助于在集群的不同服务器节点之间同步玩家的行为历史。

·        数据库清理（Purge）：本地 SQLite 数据库会随时间产生碎片并不断膨胀，从而拖慢命令的执行。命令 /co purge t:30d 会删除超过 30 天的记录。清理数据库后，SQLite 文件 database.db 的体积不会自动缩小，因为 SQLite DBMS 会保留空闲页面以备将来写入。要在物理上缩小磁盘上的文件，需要通过数据库控制台执行 VACUUM 命令，或停止服务器并使用第三方工具进行压缩。使用 MySQL 可消除这一问题，因为 MySQL DBMS 能更高效地释放未使用的磁盘空间。

结论

CoreProtect 是 Minecraft Java Edition 服务器上日志记录与恢复系统的标准。与诸如 LogBlock（它仅支持使用 MySQL，且仅限于方块日志）或 Prism（它的配置结构更为复杂）这类替代方案不同，CoreProtect 提供了基于 SQLite 的完全独立运行、对容器内容的详细追踪，以及独特的回滚预览系统 #preview。该插件唯一的技术限制是在清理大型本地 SQLite 数据库时对磁盘存储造成的显著负载，因此建议大型项目在高速 NVMe 磁盘上使用专用的 MySQL DBMS。该插件既适合朋友之间的小型私人服务器，也适合拥有数百名活跃玩家的大型项目。