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