- 版权类型
- 转载
- 插件中文名
- ItemGuard LITE — 物品记录器、历史追踪器与重复检测
- 插件英文名
- ItemGuard LITE
- 支持的核心 [服务端]
- Folia
- 语言支持
- 中文(简体)
- 适配Minecraft版本 [Java]
- 1.21
[MD]
## 简介
一名玩家带着第二把重锤登录。它是复制品、交易所得，还是原本就属于他？
以前你只能猜测；现在，使用 ItemGuard 执行一条命令即可查明。
# ItemGuard LITE：物品记录、历史追踪与重复检测
*一名玩家带着第二把重锤登录。它是复制品、交易所得，还是原本就属于他？*
*以前你只能猜测；现在，使用 ItemGuard 执行一条命令即可查明。*
每件有价值的物品在首次进入玩家手中时，都会获得一个永久 ID，并开始记录其流转历史。无论物品被丢弃、存入箱子、服务器重启，还是跨世界转移，其 ID 都会保留。当同一个 ID 同时出现在多个位置时，管理人员会收到警报，其中包含物品编号及发现位置的数量；随后可通过 **/ig history** 查看完整流转记录。
## 与 CoreProtect 的区别
**已经在使用 CoreProtect？请继续使用。**
CoreProtect 按地点和时间记录*操作行为*，例如谁在何时打开了哪个箱子；但它无法判断当前存在的两把剑是否为同一件实体物品。ItemGuard 专门回答这一问题，两者可以同时运行，功能互不重叠。
## 60 秒快速上手
1. 将 JAR 文件放入 `/plugins*and`，然后重启服务器。无需配置数据库，也没有前置依赖。
2. 手持任意工具、武器或盔甲，执行 **/ig check**。
3. 立即查看该物品的 ID 与完整流转轨迹，无需预先配置。
## 功能一览
- **减少与玩家的争议**：完整记录物品曾由谁持有、去过哪里。封禁决定基于记录，而非猜测。
- **发现藏在仓储中的重复物品**：扫描会读取无人开启过的箱子，但仅处理服务器已经加载的区块。插件不会自行加载区块，也不会读取运输矿车或驴子的背包。
- **一条命令判断物品是否合法**：对可疑掉落物执行 **/ig check**。
## 命令
```text
/ig check 查看这是什么物品，以及它曾属于谁
/ig history 查看单件物品的完整流转记录
/ig search 按物品编号搜索
/ig stats 查看追踪统计
/ig gui 通过图形界面浏览记录
```
玩家只能查看自己的物品。工作人员如需查看其他玩家的物品，需要权限：
```text
itemguard.history.others
```
## 限制说明
ItemGuard LITE 负责记录和报告，**不会删除物品，也不会执行回滚**。
- 仅追踪不可堆叠物品，例如工具、武器、盔甲和潜影盒。
- 不追踪可堆叠材料。
- 不扫描末影箱。
- 如需自动删除额外堆叠物品，应选择其他更适合的插件。
另有两点需要提前了解：
1. **历史记录不会自动删除。**数据库超过 500 MB 后，插件会在控制台输出警告，而不是丢弃证据。
2. **物品 ID 保存在物品自身的数据中。**即使卸载插件，这些 ID 仍会保留在物品数据内。
以下配置与说明会进一步解释这两点。
## 运行环境
支持：
- Paper、Purpur 或 Spigot `1.21.4` 及以上版本，包括 26.x
- Java 21
- 26.x 版本需要 Java 25
- 不支持 Folia
## Premium 规划
LITE 用于回答“这件物品从哪里来”；Premium 则着重于“如何把它还回去”。
以下功能目前尚未发布，仅用于说明后续方向，不承诺发布日期。LITE 将始终免费，并保留现有全部功能。
- **/ig restore**：为因崩溃、漏洞或诈骗而丢失物品的玩家重新发放物品，并保留原始身份。恢复后的物品仍可追踪，不会成为隐蔽的复制品。
- **/ig transfer**：将物品返还给合法所有者，并留下记录。
- **管理员审计日志**：每次恢复与转移操作都会记录执行该操作的工作人员。能够创建物品的工具，只有同时审计管理员才是安全的。
- **发放行为监控**：LITE 能告诉你一件物品的历史，但无法判断某位管理员是否在暗中大量发放装备。Premium 将按工作人员账户监控带标签物品进入世界的频率，并标记真正值得关注的模式：同一人反复发放高价值物品，或某个刚获得 OP 权限的账户突然开始这样做。系统将优先进行检测与记录；是否拦截由你自行开启，因为在活动期间误冻结正常管理员的影响，可能比仅报告问题更严重。
- **Discord 警报**与**WorldGuard 区域规则**。
之所以区分免费版与付费版，是因为：即使检测到重复物品，若无法帮助真正失去物品的玩家，检测本身的价值也有限。物品恢复能力将作为付费功能提供。
## 兼容性测试
下表中的每一行都对应一台真实服务器及一个人工放置的重复物品。检测结果直接读取自插件控制台，每项测试均有独立确认编号。所有测试均使用本页面发布的同一份 JAR 文件。
| 服务端 | 版本 | Java | 结果 |
|---|---:|---:|---|
| Paper `1.21.4` | 232 | 21 | PASS |
| Paper `1.21.5` | 114 | 21 | PASS |
| Paper `1.21.6` | 48 | 21 | PASS |
| Paper `1.21.7` | 32 | 21 | PASS |
| Paper `1.21.8` | 60 | 21 | PASS |
| Paper `1.21.9` | 59 | 21 | PASS |
| Paper `1.21.10` | 130 | 21 | PASS |
| Paper `1.21.11` | 132 | 21 | PASS |
| Paper `26.1.1` | 29 | 25 | PASS |
| Paper `26.1.2` | 74 | 25 | PASS |
| Paper `26.2` | 123 | 25 | PASS |
| Purpur `1.21.4` | 2416 | 21 | PASS |
| Purpur `1.21.11` | 2568 | 21 | PASS |
| Spigot `1.21.4` | 4458 | 21 | PASS |
Purpur 是基于相同 API 的 Paper 分支，因此测试了两个端点版本，而非其间的每一个版本。
Spigot 没有预构建下载文件，因此通过 BuildTools 编译。服务器报告的版本为：
```text
4458-Spigot-73860e0-fb3f2b6 (MC: 1.21.4)
```
仅测试了该 Spigot 版本。
由于 Spigot 缺少部分 Paper API，存在一项用户可见的差异：在 Spigot 上，物品会在玩家拾取、手持，或被容器扫描发现时才添加标签；而不是在物品生成到世界中的瞬间添加标签。
插件基于 `1.21.4` API 编译，因此最低版本由编译环境强制限制：旧版服务端会在加载时被拒绝，而不会在未经测试的环境中运行。更高版本尚未测试，可能可用，但不作保证。
## 性能测试
性能数据基于实测，而非估算。
测试共运行六台服务器：其中三台安装插件、三台未安装插件，交替执行相同负载。测试负载为 400 对漏斗持续转移受追踪物品，这是插件最繁忙的执行路径。每刻耗时通过服务端自身的计时器采样。
| 测试组 | 平均 ms/tick | 第 1 次 | 第 2 次 | 第 3 次 | 中位数 |
|---|---:|---:|---:|---:|---:|
| 未安装 ItemGuard | `0.87` | `0.79` | `0.87` | `0.87` | — |
| 安装 ItemGuard | `0.82` | `0.99` | `0.76` | `0.82` | — |
两组之间的差异为 0.05 ms，小于同一组重复测试之间的波动幅度，后者最高可达 0.23 ms。
这些测试使用的是当前版本前一个构建；此后新增的改动只会在玩家点击或交换物品时执行，不会影响本次测量的漏斗路径。因此，合理的结论不是给出一个看似精确的数字，而是给出上限：在该测试路径上，性能开销低于测试可分辨范围，约低于每个 50 ms 游戏刻预算中的 0.2 ms。基于这类数据宣称精确性能数值并不可靠。
本测试**不涵盖**以下情形：
- 一百名真实玩家同时使用命令和 GUI；
- 其他插件争抢同一刻的执行时间；
- 数周运行后的内存增长情况。
## 数据库与物品标签
### 历史记录不会自动删除
LITE 的数据库只会增长。这是有意为之：不完整的调查日志不值得信任。
数据库文件超过 **500 MB** 后，插件会向控制台输出警告，可通过 `database.warn-size-mb` 配置；设置为 `0` 可关闭警告。插件不会删除任何记录。如果数据库体积成为问题，请停止服务器后归档该文件；物品自身的 ID 不会受到影响。
### 物品 ID 保存在物品中
卸载插件后，物品标签仍会保留在物品数据内。它们在游戏中不可见且无害，但 LITE 没有移除标签的命令，因此需要明确说明这一点。
箱子扫描采用限速机制，默认每刻扫描 **8 个区块**，并且绝不会加载尚未驻留在内存中的区块，因此不会导致未加载地形被强制加载。
```yaml
anti-dupe:
sweep:
enabled: true
chunks-per-tick: 8
database:
warn-size-mb: 500 # 超过此大小时在控制台警告；0 = 关闭
```
## 数据与隐私
数据存储在插件目录内的本地 SQLite 文件中，不会上传任何数据。
唯一的外部连接为 bStats；如有需要，你可以将其关闭。
本页面 JAR 文件的 SHA-256：
```text
a952d16146082ffacfbcbf6032fdba0634c86e8099cbf6802685c2f76db71727
```
## 使用与分发许可
可在任何服务器上免费使用，包括向玩家收费的服务器。
禁止转售或重新上传。
## 问题反馈
如果发现插件漏检了重复物品，或遇到任何异常行为，请通过以下方式反馈：
[discord.gg/EnSNSNVV5G](https://discord.gg/EnSNSNVV5G)
[/MD]
## 简介
一名玩家带着第二把重锤登录。它是复制品、交易所得，还是原本就属于他？
以前你只能猜测；现在，使用 ItemGuard 执行一条命令即可查明。
# ItemGuard LITE：物品记录、历史追踪与重复检测
*一名玩家带着第二把重锤登录。它是复制品、交易所得，还是原本就属于他？*
*以前你只能猜测；现在，使用 ItemGuard 执行一条命令即可查明。*
每件有价值的物品在首次进入玩家手中时，都会获得一个永久 ID，并开始记录其流转历史。无论物品被丢弃、存入箱子、服务器重启，还是跨世界转移，其 ID 都会保留。当同一个 ID 同时出现在多个位置时，管理人员会收到警报，其中包含物品编号及发现位置的数量；随后可通过 **/ig history** 查看完整流转记录。
## 与 CoreProtect 的区别
**已经在使用 CoreProtect？请继续使用。**
CoreProtect 按地点和时间记录*操作行为*，例如谁在何时打开了哪个箱子；但它无法判断当前存在的两把剑是否为同一件实体物品。ItemGuard 专门回答这一问题，两者可以同时运行，功能互不重叠。
## 60 秒快速上手
1. 将 JAR 文件放入 `/plugins*and`，然后重启服务器。无需配置数据库，也没有前置依赖。
2. 手持任意工具、武器或盔甲，执行 **/ig check**。
3. 立即查看该物品的 ID 与完整流转轨迹，无需预先配置。
## 功能一览
- **减少与玩家的争议**：完整记录物品曾由谁持有、去过哪里。封禁决定基于记录，而非猜测。
- **发现藏在仓储中的重复物品**：扫描会读取无人开启过的箱子，但仅处理服务器已经加载的区块。插件不会自行加载区块，也不会读取运输矿车或驴子的背包。
- **一条命令判断物品是否合法**：对可疑掉落物执行 **/ig check**。
## 命令
```text
/ig check 查看这是什么物品，以及它曾属于谁
/ig history 查看单件物品的完整流转记录
/ig search 按物品编号搜索
/ig stats 查看追踪统计
/ig gui 通过图形界面浏览记录
```
玩家只能查看自己的物品。工作人员如需查看其他玩家的物品，需要权限：
```text
itemguard.history.others
```
## 限制说明
ItemGuard LITE 负责记录和报告，**不会删除物品，也不会执行回滚**。
- 仅追踪不可堆叠物品，例如工具、武器、盔甲和潜影盒。
- 不追踪可堆叠材料。
- 不扫描末影箱。
- 如需自动删除额外堆叠物品，应选择其他更适合的插件。
另有两点需要提前了解：
1. **历史记录不会自动删除。**数据库超过 500 MB 后，插件会在控制台输出警告，而不是丢弃证据。
2. **物品 ID 保存在物品自身的数据中。**即使卸载插件，这些 ID 仍会保留在物品数据内。
以下配置与说明会进一步解释这两点。
## 运行环境
支持：
- Paper、Purpur 或 Spigot `1.21.4` 及以上版本，包括 26.x
- Java 21
- 26.x 版本需要 Java 25
- 不支持 Folia
## Premium 规划
LITE 用于回答“这件物品从哪里来”；Premium 则着重于“如何把它还回去”。
以下功能目前尚未发布，仅用于说明后续方向，不承诺发布日期。LITE 将始终免费，并保留现有全部功能。
- **/ig restore**：为因崩溃、漏洞或诈骗而丢失物品的玩家重新发放物品，并保留原始身份。恢复后的物品仍可追踪，不会成为隐蔽的复制品。
- **/ig transfer**：将物品返还给合法所有者，并留下记录。
- **管理员审计日志**：每次恢复与转移操作都会记录执行该操作的工作人员。能够创建物品的工具，只有同时审计管理员才是安全的。
- **发放行为监控**：LITE 能告诉你一件物品的历史，但无法判断某位管理员是否在暗中大量发放装备。Premium 将按工作人员账户监控带标签物品进入世界的频率，并标记真正值得关注的模式：同一人反复发放高价值物品，或某个刚获得 OP 权限的账户突然开始这样做。系统将优先进行检测与记录；是否拦截由你自行开启，因为在活动期间误冻结正常管理员的影响，可能比仅报告问题更严重。
- **Discord 警报**与**WorldGuard 区域规则**。
之所以区分免费版与付费版，是因为：即使检测到重复物品，若无法帮助真正失去物品的玩家，检测本身的价值也有限。物品恢复能力将作为付费功能提供。
## 兼容性测试
下表中的每一行都对应一台真实服务器及一个人工放置的重复物品。检测结果直接读取自插件控制台，每项测试均有独立确认编号。所有测试均使用本页面发布的同一份 JAR 文件。
| 服务端 | 版本 | Java | 结果 |
|---|---:|---:|---|
| Paper `1.21.4` | 232 | 21 | PASS |
| Paper `1.21.5` | 114 | 21 | PASS |
| Paper `1.21.6` | 48 | 21 | PASS |
| Paper `1.21.7` | 32 | 21 | PASS |
| Paper `1.21.8` | 60 | 21 | PASS |
| Paper `1.21.9` | 59 | 21 | PASS |
| Paper `1.21.10` | 130 | 21 | PASS |
| Paper `1.21.11` | 132 | 21 | PASS |
| Paper `26.1.1` | 29 | 25 | PASS |
| Paper `26.1.2` | 74 | 25 | PASS |
| Paper `26.2` | 123 | 25 | PASS |
| Purpur `1.21.4` | 2416 | 21 | PASS |
| Purpur `1.21.11` | 2568 | 21 | PASS |
| Spigot `1.21.4` | 4458 | 21 | PASS |
Purpur 是基于相同 API 的 Paper 分支，因此测试了两个端点版本，而非其间的每一个版本。
Spigot 没有预构建下载文件，因此通过 BuildTools 编译。服务器报告的版本为：
```text
4458-Spigot-73860e0-fb3f2b6 (MC: 1.21.4)
```
仅测试了该 Spigot 版本。
由于 Spigot 缺少部分 Paper API，存在一项用户可见的差异：在 Spigot 上，物品会在玩家拾取、手持，或被容器扫描发现时才添加标签；而不是在物品生成到世界中的瞬间添加标签。
插件基于 `1.21.4` API 编译，因此最低版本由编译环境强制限制：旧版服务端会在加载时被拒绝，而不会在未经测试的环境中运行。更高版本尚未测试，可能可用，但不作保证。
## 性能测试
性能数据基于实测，而非估算。
测试共运行六台服务器：其中三台安装插件、三台未安装插件，交替执行相同负载。测试负载为 400 对漏斗持续转移受追踪物品，这是插件最繁忙的执行路径。每刻耗时通过服务端自身的计时器采样。
| 测试组 | 平均 ms/tick | 第 1 次 | 第 2 次 | 第 3 次 | 中位数 |
|---|---:|---:|---:|---:|---:|
| 未安装 ItemGuard | `0.87` | `0.79` | `0.87` | `0.87` | — |
| 安装 ItemGuard | `0.82` | `0.99` | `0.76` | `0.82` | — |
两组之间的差异为 0.05 ms，小于同一组重复测试之间的波动幅度，后者最高可达 0.23 ms。
这些测试使用的是当前版本前一个构建；此后新增的改动只会在玩家点击或交换物品时执行，不会影响本次测量的漏斗路径。因此，合理的结论不是给出一个看似精确的数字，而是给出上限：在该测试路径上，性能开销低于测试可分辨范围，约低于每个 50 ms 游戏刻预算中的 0.2 ms。基于这类数据宣称精确性能数值并不可靠。
本测试**不涵盖**以下情形：
- 一百名真实玩家同时使用命令和 GUI；
- 其他插件争抢同一刻的执行时间；
- 数周运行后的内存增长情况。
## 数据库与物品标签
### 历史记录不会自动删除
LITE 的数据库只会增长。这是有意为之：不完整的调查日志不值得信任。
数据库文件超过 **500 MB** 后，插件会向控制台输出警告，可通过 `database.warn-size-mb` 配置；设置为 `0` 可关闭警告。插件不会删除任何记录。如果数据库体积成为问题，请停止服务器后归档该文件；物品自身的 ID 不会受到影响。
### 物品 ID 保存在物品中
卸载插件后，物品标签仍会保留在物品数据内。它们在游戏中不可见且无害，但 LITE 没有移除标签的命令，因此需要明确说明这一点。
箱子扫描采用限速机制，默认每刻扫描 **8 个区块**，并且绝不会加载尚未驻留在内存中的区块，因此不会导致未加载地形被强制加载。
```yaml
anti-dupe:
sweep:
enabled: true
chunks-per-tick: 8
database:
warn-size-mb: 500 # 超过此大小时在控制台警告；0 = 关闭
```
## 数据与隐私
数据存储在插件目录内的本地 SQLite 文件中，不会上传任何数据。
唯一的外部连接为 bStats；如有需要，你可以将其关闭。
本页面 JAR 文件的 SHA-256：
```text
a952d16146082ffacfbcbf6032fdba0634c86e8099cbf6802685c2f76db71727
```
## 使用与分发许可
可在任何服务器上免费使用，包括向玩家收费的服务器。
禁止转售或重新上传。
## 问题反馈
如果发现插件漏检了重复物品，或遇到任何异常行为，请通过以下方式反馈：
[discord.gg/EnSNSNVV5G](https://discord.gg/EnSNSNVV5G)
[/MD]