Might Vaults
适用于 Paper 1.21.11(Java 21)的玩家储物箱,数据存储在嵌入式 H2 数据库中,并对每一次进出物品操作提供完整的管理员审计追踪,同时针对复制漏洞进行了专门的加固。
该 jar 包是自包含的:H2 已被阴影打包(shaded in),因此运行时不会下载任何额外内容。
命令
| 命令 |
权限 |
描述 |
/pv [number] |
mightvaults.vaults.<number> |
打开你自己的其中一个储物箱。默认为 1 号箱。别名:/playervault、/pvault |
/mightvaults help |
mightvaults.admin |
命令列表 |
/mightvaults open <player> <number> |
mightvaults.admin |
打开其他人的储物箱。你所做的每处更改都会记录为 ADMIN_ 操作 |
/mightvaults logs <player> [number|all] [page] |
mightvaults.admin |
查看储物箱中物品的进出记录,最新条目在前。悬停物品可查看具体堆栈详情 |
/mightvaults recent [page] |
mightvaults.admin |
查看所有储物箱中的最新活动 |
/mightvaults info <player> |
mightvaults.admin |
查看玩家拥有的储物箱数量及其来源 |
/mightvaults clear <player> <number> confirm |
mightvaults.admin |
删除指定储物箱中的所有物品。需要输入 confirm,并记录每个被移除的物品堆栈 |
/mightvaults stats |
mightvaults.admin |
存储总量统计 |
/mightvaults reload |
mightvaults.admin |
重新读取 config.yml |
管理员命令的别名:/mvaults、/pvadmin。
权限
| 节点 |
含义 |
mightvaults.vaults.<number> |
授予该储物箱 以及所有编号更低的储物箱 的使用权 |
mightvaults.vaults.* |
授予从 1 到 max-vaults 的所有储物箱使用权 |
mightvaults.admin |
所有管理员命令,以及访问所有储物箱的权限 |
mightvaults.bypass.cooldown |
忽略 /pv 的冷却时间 |
mightvaults.vaults.5 会授予 1、2、3、4 和 5 号储物箱。这不仅仅是插件层面的检查:
在启动时,插件会将 mightvaults.vaults.1 .. max-vaults 注册到权限系统中,每个节点都将其下方的节点作为子节点,因此这种继承关系在 Bukkit 自身的权限引擎中是真实存在的,并且对 LuckPerms 等插件可见。
权限是授予储物箱的唯一方式。没有针对单个玩家的覆盖选项,因此储物箱数量始终由配置文件和玩家权限完全决定。
使用随附的配置文件时,default-vaults 为 0,因此没有任何权限的玩家没有任何储物箱。
配置
config.yml 包含完整的注释。以下是值得注意的设置:
default-vaults: 0 - 没有任何权限时默认授予的储物箱数量。
max-vaults: 100 - 上限值,以及注册的权限节点数量。
rows: 6 - 储物箱大小(1-6)。调高它会扩大现有储物箱;调低它 绝不会 缩小那些在上层格子中已有物品的储物箱,因此配置文件更改不会导致物品丢失。
sounds.* - 铜箱子声音,以纯注册键形式表示。任何声音键均可用;如果你更喜欢,也可以使用 block.copper_chest.oxidized_open / _weathered_open。
saving.mode: IMMEDIATE - 详见下文。
security.* - 开启时的门禁检查和物品黑名单。
logging.* - 审计详细程度和保留策略。
如何防止复制
储物箱类插件通常通过几种众所周知的方式产生复制品。这里每一种都已封堵:
- 同一储物箱的两个副本。 每个储物箱最多只有一个
VaultSession,无论是所有者还是管理员,每个人看到的都是同一个 Inventory 对象。不可能存在两个持有相同物品的独立库存。默认情况下 allow-simultaneous-viewers: false 更进一步,直接拒绝第二个查看者,这也确保了审计日志的无歧义性。
- 竞态加载。 针对同一储物箱的并发打开请求会被合并为单次加载;处于加载中或保存中的储物箱会被锁定,对其进行的任何点击都会被取消。
- 在其他库存界面中打开储物箱。 当有其他库存界面处于打开状态或光标上有物品时,
/pv 命令会被拒绝,从而堵住了经典的“在 GUI 中打开 GUI”这一漏洞向量。
- 崩溃回滚。 在默认的
IMMEDIATE 保存模式下,每次更改后储物箱都会立即写入 H2,且 H2 的写入延迟设置为 0,因此崩溃无法将储物箱恢复到其物品仍存在于玩家背包中的状态。autosave-seconds 作为备份机制。
- 重载覆盖写入。 每个数据库操作都在一个 FIFO 线程上运行,因此重新读取永远不会超过同一储物箱的待处理写入。储物箱行还携带一个
revision 版本号,用作比较并设置保护;如果版本不匹配,则会发出严重日志警告,并重写内存状态(权威数据)而不是丢弃它。
- 损坏读取。 无法解码的数据负载会中止打开操作。储物箱永远不会被呈现为空然后覆盖保存回良好数据。损坏情况会被记录为
LOAD_FAILED。
- 超大堆栈。 超出合法最大值的堆栈会在加载储物箱时被拆分,这正是点击转移合并漏洞发生的地方。如果拆分后的堆栈仍超出限制,原始堆栈将被原样恢复——插件绝不会为了符合限制而销毁物品。
- 自动化。 涉及储物箱的
InventoryMoveItemEvent 会被取消,因此漏斗或其他插件无法通过储物箱传输物品。
- 断开连接与关闭。 退出游戏时会关闭并保存储物箱,
onDisable 会在排队最终写入和排空数据库队列之前关闭所有打开的储物箱(返回光标上的物品)。
明确声明不适用:这里没有任何措施可以阻止发生在服务器端、其他插件中或从未触及储物箱库存的客户端漏洞所产生的复制品。
审计追踪
每次打开、关闭、存入、取出、拦截物品、管理员操作和加载失败都会进入 mv_audit 表,包含时间戳、操作者、所有者、储物箱编号、数量以及物品的序列化副本,以便 /mightvaults logs 能够在悬停时显示确切的物品堆栈。
物品移动是基于保险箱在“操作前”与“操作后”的网络状态对比得出的,而非来自单个点击事件。因此,Shift 键点击、拖拽、快捷栏交换以及堆叠合并都会被正确记录,而仅仅重新排列保险箱内的物品则不会产生日志条目。
存储与备份
数据存储在 plugins/MightVaults/data/mightvaults.mv.db(包含表 mv_vaults、mv_players、mv_audit、mv_meta)。复制该文件前请停止服务器。
H2 故意未在着色 JAR(shaded jar)中进行包重定位。H2 的 MVStore 会将其内部类型的完全限定类名写入数据库文件中,因此在重定位后,只有使用相同着色前缀的 JAR 才能重新打开该文件;任何标准 H2 工具都无法读取它,且重命名此插件的包会导致所有已存储的保险箱数据孤立。由于包名保持为 org.h2,任何 H2 2.5.x 版本的 JAR 均可直接打开该文件:
java -cp h2-2.5.250.jar org.h2.tools.Shell -url "jdbc:h2:file:/path/to/mightvaults" -user mightvaults
限制
- 数据库是嵌入式的,因此仅属于单一服务器。请勿让两个服务器指向同一个文件;H2 的文件锁将拒绝第二个服务器的连接。若需共享网络设置,则需要使用真正的数据库服务器。
- 不支持 Folia(
folia-supported: false);该插件假设存在单一服务器线程。
storage.file 仅在启动时应用,不会在 /mightvaults reload 命令中生效。
- 保险箱内的物品移动按刻(tick)进行归属判定。如果开启了
allow-simultaneous-viewers,且两人在同一刻内对同一保险箱进行操作,则该刻内的变更将归属于其中一人。
Might Vaults
Player vaults for Paper 1.21.11 on Java 21, stored in an embedded H2 database, with a
full admin audit trail of every item that moves in or out and deliberate hardening against
duplication exploits.
The jar is self-contained: H2 is shaded in, so nothing is downloaded at runtime.
Commands
| Command |
Permission |
Description |
/pv [number] |
mightvaults.vaults.<number> |
Open one of your own vaults. Defaults to vault 1. Aliases: /playervault, /pvault |
/mightvaults help |
mightvaults.admin |
Command list |
/mightvaults open <player> <number> |
mightvaults.admin |
Open someone else's vault. Every change you make is logged as an ADMIN_ action |
/mightvaults logs <player> [number|all] [page] |
mightvaults.admin |
What went in and out of a vault, newest first. Hover an item to see the exact stack |
/mightvaults recent [page] |
mightvaults.admin |
Newest activity across every vault |
/mightvaults info <player> |
mightvaults.admin |
How many vaults a player has and where that number comes from |
/mightvaults clear <player> <number> confirm |
mightvaults.admin |
Delete every item in one vault. Requires confirm, and logs every removed stack |
/mightvaults stats |
mightvaults.admin |
Storage totals |
/mightvaults reload |
mightvaults.admin |
Re-read config.yml |
Aliases for the admin command: /mvaults, /pvadmin.
Permissions
| Node |
Meaning |
mightvaults.vaults.<number> |
Grants that vault and every lower-numbered one |
mightvaults.vaults.* |
Every vault number up to max-vaults |
mightvaults.admin |
Every admin command, plus access to every vault number |
mightvaults.bypass.cooldown |
Ignore the /pv cooldown |
mightvaults.vaults.5 gives vaults 1, 2, 3, 4 and 5. This is not just a plugin-side check:
at startup the plugin registers mightvaults.vaults.1 .. max-vaults with each node holding the
node below it as a child, so the inheritance is real inside Bukkit's own permission engine and is
visible to LuckPerms and friends.
Permissions are the only way to grant vaults. There is no per-player override, so the count is
always fully explained by the config plus the player's permissions.
With the shipped config, default-vaults is 0, so a player with no permissions has no vaults.
Configuration
config.yml is commented in full. The settings worth knowing about:
default-vaults: 0 - vaults granted with no permission at all.
max-vaults: 100 - ceiling, and how many permission nodes get registered.
rows: 6 - vault size (1-6). Raising it grows existing vaults; lowering it never shrinks a
vault that already holds items in the upper rows, so a config change cannot delete items.
sounds.* - the copper chest sounds, as plain registry keys. Any sound key works;
block.copper_chest.oxidized_open / _weathered_open also exist if you prefer those.
saving.mode: IMMEDIATE - see below.
security.* - the open-time gate and the item blacklist.
logging.* - audit detail and retention.
How duplication is prevented
Vault plugins dupe in a small number of well-known ways. Each one is closed here:
- Two copies of one vault. There is at most one
VaultSession per vault, and everyone
looking at it, owner or admin, shares the exact same Inventory object. Two inventories
holding the same items can never exist. By default allow-simultaneous-viewers: false goes
further and refuses the second viewer outright, which also keeps the audit log unambiguous.
- Racing the load. Concurrent open requests for the same vault are collapsed into a single
load; a vault that is mid-load or mid-save is locked and every click on it is cancelled.
- Opening a vault out of another inventory.
/pv is refused while another inventory is open
or while an item is on the cursor, the classic "open a GUI from a GUI" vector.
- Crash rollback. In the default
IMMEDIATE save mode the vault is written to H2 straight
after every change, and H2's write delay is set to 0, so a crash cannot restore a vault to a
state where its items also still exist in a player inventory. autosave-seconds is a backup.
- Reload overtaking a write. Every database operation runs on one FIFO thread, so a re-read
can never pass a pending write of the same vault. Vault rows also carry a
revision that is
used as a compare-and-set guard; a mismatch is logged loudly and the in-memory state (the
authority) is rewritten rather than discarded.
- Corrupt reads. A payload that fails to decode aborts the open. A vault is never presented
as empty and then saved back over good data. Corruption is recorded as
LOAD_FAILED.
- Oversized stacks. Stacks above their legal maximum are split when the vault loads, which
is where shift-click merge exploits land. If the split does not fit, the original stack is
restored untouched - the plugin never destroys items to satisfy a limit.
- Automation.
InventoryMoveItemEvent involving a vault is cancelled, so no hopper or
plugin can pipe items through one.
- Disconnect and shutdown. Quitting closes and saves the vault, and
onDisable closes every
open vault (returning cursor items) before queueing the final writes and draining the
database queue.
Deliberately not claimed: nothing here can stop a dupe that lives in the server, in another
plugin, or in a client exploit that never touches a vault inventory.
Auditing
Every open, close, deposit, withdrawal, blocked item, admin action and load failure goes into
mv_audit with a timestamp, the actor, the owner, the vault number, the quantity, and a
serialised copy of the item so /mightvaults logs can show the exact stack on hover.
Item movement is derived from a net before/after comparison of the vault rather than from
individual clicks, so shift-clicks, drags, hotbar swaps and stack merges are all reported
correctly, and simply rearranging a vault produces no log entries.
Storage and backups
Data lives in plugins/MightVaults/data/mightvaults.mv.db (tables mv_vaults, mv_players,
mv_audit, mv_meta). Stop the server before copying it.
H2 is intentionally not relocated in the shaded jar. H2's MVStore writes the fully qualified
class names of its own internal types into the database file, so under a relocation the file can
only ever be reopened by a jar using that exact shade prefix; no standard H2 tool could read it,
and renaming this plugin's packages would orphan every stored vault. Because the package stays
org.h2, any H2 2.5.x jar can open the file directly:
java -cp h2-2.5.250.jar org.h2.tools.Shell -url "jdbc:h2:file:/path/to/mightvaults" -user mightvaults
Limitations
- The database is embedded, so it belongs to exactly one server. Do not point two servers at the
same file; H2's file lock will refuse the second one. A shared network setup would need a real
database server instead.
- Folia is not supported (
folia-supported: false); the plugin assumes a single server thread.
storage.file is only applied at startup, not on /mightvaults reload.
- Item movement inside a vault is attributed per tick. If
allow-simultaneous-viewers is turned
on and two people click in the same vault during the same tick, that tick's changes are
attributed to one of them.
评论 0
登录后参与评分
还没有评论,来抢沙发吧