5.1 KiB
5.1 KiB
AuroraContainerLog
AuroraContainerLog 是一个面向 Spigot 1.12.2 的箱子容器日志插件，用于记录指定世界内玩家对箱子类容器的物品放入和取出行为，适合地皮服排查箱子物品被盗问题。
当前插件版本：1.1.5
1. 功能概览
- 支持指定世界监听箱子容器。
- 支持普通箱子、陷阱箱、大箱子记录与查询。
- 支持记录玩家名称和 UUID。
- 支持记录容器坐标：
world/x/y/z。 - 支持记录动作：
TAKE、PUT。 - 支持记录物品类型、数量、展示名、lore、附魔和完整 ItemStack Base64。
- 支持 SQLite 存储。
- 支持自动清理超过指定保留天数的历史数据。
- 支持按玩家、指定箱子、附近范围分页查询。
- 数据库写入和查询通过异步队列执行，避免阻塞主线程。
2. 运行环境
Java: 8
服务端: Spigot 1.12.2
构建工具: Maven
数据库: SQLite
运行依赖：
HikariCP
sqlite-jdbc
插件 JAR 不内置 HikariCP 和 sqlite-jdbc。运行环境必须通过服务端公共依赖、启动 classpath、依赖插件或统一依赖加载方案提供这两个依赖。
3. 安装方式
构建插件：
mvn package
构建完成后，将生成的插件包放入服务端：
plugins/AuroraContainerLog-1.1.5.jar
启动服务端后，插件会生成默认配置文件：
plugins/AuroraContainerLog/config.yml
4. 配置文件
默认配置：
listen-worlds:
- world
query:
page-size: 8
chest-recent-days: 30
max-near-radius: 50
default-page: 1
database:
file: containerlog.db
cleanup:
enabled: true
retention-days: 60
interval-hours: 24
message-prefix: "&8[&bACL&8] &7"
配置说明：
listen-worlds：启用箱子日志监听的世界列表。query.page-size：每页显示的日志数量。query.chest-recent-days：/acl chest默认查询最近多少天的记录。query.max-near-radius：/acl near允许的最大查询半径。query.default-page：未填写页码时使用的默认页。database.file：SQLite 数据库文件名。cleanup.enabled：是否启用过期日志自动清理。cleanup.retention-days：日志保留天数，超过后自动清理。cleanup.interval-hours：自动清理执行间隔。message-prefix：命令消息前缀。
5. 记录内容
每条日志会记录以下字段：
时间
世界
容器坐标 x/y/z
玩家名称
玩家 UUID
动作 TAKE / PUT
物品 material
物品 amount
物品 displayName
物品 lore
物品 enchantments
完整 ItemStack Base64
插件采用打开容器时快照、关闭容器时对比差异的方式记录变化，只记录箱子容器库存变化，不记录玩家背包自身变化。
6. 命令
管理命令需要权限：
auroracontainerlog.admin
重载配置：
/acl reload
查询指定玩家最近记录：
/acl player <玩家名> [天数] [页码]
查询当前看着的箱子最近记录：
/acl chest [页码]
查询附近箱子记录：
/acl near <半径> [天数] [页码]
命令别名：
/aclog
7. 权限
auroracontainerlog.admin
默认权限：
op
8. 数据库说明
当前版本仅支持 SQLite。
SQLite 使用 HikariCP 单连接池：
maximumPoolSize: 1
minimumIdle: 1
connectionTimeout: 10000
validationTimeout: 3000
idleTimeout: 600000
maxLifetime: 1700000
连接池大小固定为 1，避免 SQLite 多连接写入导致数据库锁竞争。
9. 自动清理规则
插件启动后会排队执行一次过期数据清理，之后按 cleanup.interval-hours 周期执行。
默认规则：
保留最近 60 天日志
每 24 小时清理一次
清理操作进入数据库异步执行队列，不在主线程直接执行 SQL。
10. 查询行为
/acl chest会查询玩家准星指向的箱子。- 大箱子查询会同时匹配相邻两侧箱子坐标。
- 玩家执行查询时，结果支持点击传送到记录坐标。
- 控制台查询会显示完整坐标文本。
- 查询结果按时间倒序分页显示。
11. 使用流程
- 确认服务端运行环境已提供
HikariCP和sqlite-jdbc。 - 将插件 JAR 放入服务端
plugins目录。 - 启动服务端生成默认配置。
- 修改
listen-worlds，填入需要监听的世界。 - 按需调整分页、自动清理和数据库文件配置。
- 执行
/acl reload重载配置。 - 使用
/acl chest、/acl player、/acl near查询日志。
12. 注意事项
- 插件包不包含
sqlite-jdbc和HikariCP，缺少运行依赖会导致 SQLite 连接池初始化失败。 - 修改监听世界后，只影响后续容器操作记录，不会修改历史数据。
- 关闭容器时只记录最终净变化，不记录打开期间每一次中间点击动作。
- 若玩家取出物品后又在关闭前放回相同数量，最终差异为 0，不会写入日志。
- 发布新版本前应确认
plugin.yml中版本号已递增。 - 上线前建议在测试服验证普通点击、shift-click、数字键、拖拽、大箱子和未监听世界场景。