PlugMaster

插件

· 作者 LucasTHCR

从 Modrinth 和 Hangar 保持你的插件更新,并在游戏中控制它们。更新经过验证并暂停至下次启动,不会在服务器运行时替换。

0 本站下载 0 关注 更新于 4 周前

最新 1.2.1 · 26.3 · Bukkit / BungeeCord

一键开服(送7天)

Built with Java 11 Available for Paper Available for Purpur Available for Spigot Available for Bukkit Available for Folia Available for BungeeCord Available for Waterfall Available for Velocity

Chat with us on Discord Available on Codeberg

告诉你哪些插件有新版本,安全地获取更新,并允许你在不重启服务器的情况下切换插件的启用与禁用。


文件夹里有四十个插件,你却不知道上周哪三个发布了修复补丁。于是你手动检查,或者干脆不检查,直到被玩家告知。这两种情况都不是好办法。

PlugMaster 替你读取文件夹。它会找出哪些 jar 包发布在 Modrinth 或 Hangar 上,将你本地的版本与线上进行对比,并告诉你有哪些变动。获取新文件是一个单独的步骤,由你主动发起,且永远不会自动替换正在运行的服务器中的插件。

后半部分是你凌晨两点遇到故障时才会用到的功能:/pm list、/pm info、/pm disable、/pm reload。关闭行为异常的插件,查看其依赖项,然后重新启用它,而无需踢出任何玩家。

将 jar 包放入文件夹并重启即可。除非你下达指令,否则它只会报告状态而不会执行其他操作。


要求

  • Bukkit, Spigot, Paper, Purpur 或 Folia,1.16.5 及以上版本
  • BungeeCord, Waterfall 或 Velocity(用于更新功能)
  • Java 11 或更高版本
  • 能够访问 api.modrinth.com 和 hangar.papermc.io 的出站 HTTPS 连接

无外部依赖,未使用阴影打包(shaded)。JSON 和 YAML 解析器已内置于项目中,因此单个 jar 包同时包含 plugin.yml、bungee.yml 和 velocity-plugin.json,并能在任意一种平台类型上直接运行,无需重定位。


它是如何识别你的插件的

两个数据源,按顺序查询。

Modrinth 依据文件本身的 SHA-1 哈希值进行匹配。 无需配置,也无需猜测:你拥有的确切字节要么存在于 Modrinth 上,要么不存在。每个已安装的插件都会通过一次批量请求进行查找,而不是为每个插件单独发起请求,因此即使文件夹中有六十个插件,也只需一次往返通信。

不过该端点不按发布渠道过滤,因此可能会向仅接受正式版的服务器返回测试版信息。在这种情况下,受影响的单个插件会进行单独查询,此时会尊重渠道设置。文件夹中的其余插件不受影响。

Hangar 没有哈希值可供参考,因此匹配分为两个阶段。首先检查 plugin.yml 中的 website 字段,当该字段指向 Hangar 项目时非常可靠。如果失败,则进行名称搜索,且只有在恰好有一个项目匹配时才接受结果。模糊匹配意味着无匹配,而非猜测。默认情况下,Hangar 项目的拥有者也必须与 plugin.yml 中的作者一致;如果这导致匹配率下降,你可以放宽此限制。

如果 Modrinth 宕机,本次查询将跳过 Hangar。 并非因为无法工作,而是因为所有插件都会被视为未匹配,而 Hangar 的匹配机制是每次搜索一个请求。仅仅因为第一个服务出现了一分钟的故障就向另一个服务发起六十次请求,这种权衡并不划算。本次查询会标记状态并在稍后重试。

在应用更新之前,被替换的 jar 包会被复制到 plugins/PlugMaster/backups/。如果新版本行为异常,可以通过 /pm update rollback <plugin> 回滚该副本,下次启动时将恢复上一版本。每个插件保留一份备份,始终保存最后一次更新前的版本。

任何未能匹配到的内容都会在 /pm update list 中列出,以便明确哪些仍需手动处理,而不是悄无声息地显示为已是最新。


为什么更新以“暂存”而非“安装”的方式处理

没有任何插件可以安全地替换正在运行的服务器下的 jar 文件。类加载器仍然持有旧的类,监听器已针对来自旧类的对象进行了注册,调度任务正在进行中,其他插件也可能持有自己的引用。任何声称相反情况的人都在拿你的服务可用性赌博。

因此,下载的文件会进入 Bukkit 的更新文件夹,即 bukkit.yml 中配置为 update-folder 的那个文件夹,服务器将在下次启动时安装它。现在下载,下次重启后生效。BungeeCord 和 Velocity 没有这样的文件夹,因此 PlugMaster 保留自己的文件夹,并在代理关闭时应用停放的(parked)文件,效果是一样的。

如果你的 update-folder 设置为空值,服务器会返回插件文件夹本身,在那里写入会覆盖当前正在运行的 jar 文件。PlugMaster 注意到这一点并回退到 plugins/update/。


在停放任何东西之前检查什么

一个下载要经过四道关卡才能被视为可信,并且必须全部通过。

  • 传输期间的大小。 限制是在字节到达时执行的,而不是在文件已经在磁盘上时才测量。损坏或恶意的端点会在达到 max-download-megabytes 时被切断,而不是先填满磁盘。还会预先检查 Content-Length 头信息,但头信息允许说谎,所以两者都会检查。
  • 它必须是一个 zip 文件。 任何小于 1 KB 或缺少 PK 魔术字节的文件都是错误页面,而不是 jar 文件。HTTP 200 状态码返回 Cloudflare 中间页是真实发生的情况。
  • 校验和。 Modrinth 为每个文件发布 SHA-1,Hangar 使用 SHA-256。无论来源提供的是哪种,都会与到达的字节进行验证,不匹配则丢弃。
  • 内部的插件是正确的插件。 下载的 jar 中的 plugin.yml 必须命名它旨在替换的插件。这是捕获名称搜索偏离正轨的关键,也是为什么没有哈希值的来源无法将外部 jar 停放在你插件文件名下的原因。

任何失败的都会被删除,而不是停放,并且你会被告知它在哪一项检查中失败。

已经停放的更新会通过哈希首先识别,否则通过其自身 plugin.yml 中的版本识别。因此,当 1.2 出现时,位于更新文件夹中的 1.1 不会阻止它,而且你手动放入的较新 jar 不会被较旧的 jar 覆盖。


运行时控制

/pm enable 和 /pm disable 仅使用公共 Bukkit API。禁用还会告诉你哪些已加载的插件将目标列为依赖项,这样你可以在它们开始报错之前发现,而不是之后。

/pm unload 和 /pm reload 是一对脆弱的操作,并且对此很诚实。没有公共 API 可以从服务器中移除插件,因此这深入到了私有字段 SimplePluginManager 和 SimpleCommandMap。清理的内容包括:事件处理器、调度任务、注册的服务、插件的命令及其别名、管理器自身注册表中的条目,最后是它的类加载器,被关闭以便实际释放 jar 文件并使类可以被收集。

顺序很重要。所有向外访问的内容首先被注销,然后才从注册表中移除插件,这样中途失败就不会导致一个已从管理器中移除但仍响应事件的插件残留。

这些内部结构取决于服务器。Bukkit、Spigot 和 Paper 直到 1.20.4 版本将其插件保存在 SimplePluginManager 中。Paper 1.20.5 及更高版本运行自己的插件系统,并将该类留作转发一切的空壳,因此真正的注册表位于 PaperPluginInstanceManager 中,拥有自己的依赖关系图和类加载器注册表,两者都需要清理。PlugMaster 携带这两种路径并选择实际持有插件的那一种。

如果它找不到任何一种,它会拒绝并说明原因,而在插件被触及之前。在查找无法卸载的过程中,没有任何东西会被禁用。

即使在工作时,重载也只是尽力而为。将自身引用传递给其他内容的插件可能会在清理后留下痕迹。对于刚刚更新的插件,重启仍然是干净的路径。这是为了凌晨 2 点重启成本高昂的情况。


安装你尚未拥有的插件

默认关闭。downloader.enabled: true 开启它,并且 plugmaster.download 独立于其他所有内容对其进行门控。

/pm search worldedit          列出匹配的插件及其 ID
/pm download worldedit        获取最新适配版本到 plugins/
/pm load worldedit.jar        启动它,或者留给下次重启

搜索仅提供符合要求的插件:Modrinth 会询问带有此服务器运行的加载器标签的插件,并且在 strict-game-version 开启时,还询问服务器的自身版本。下载过程与更新相同的四道检查,如果发现 jar 包含你已经有的插件,则会额外拒绝。

它只停留在下载阶段。新的 jar 文件位于 plugins/ 中,在你加载它或重启之前不会做任何事情,因为一个启动了你未请求的东西的插件并不是你在凌晨 2 点想要的。

仅限 Modrinth。Hangar 没有可比的对等搜索和获取路径,猜测一个意味着猜测一个名称指的是哪个项目。

指标

PlugMaster 向 bStats 报告匿名计数:服务器软件和版本、Java 版本、玩家数量,以及 PlugMaster 自身的哪些开关处于开启状态。没有名称,没有地址,关于你运行哪些插件的信息一概没有。

在 plugins/bStats/config.yml 中使用 enabled: false 关闭它——这将一次性覆盖服务器上的所有 bStats 插件。仅限 Bukkit 系列;代理端不报告任何内容。

命令

一切都是 /pm,完整名称为 /plugmaster。

命令 功能
/pm list 列出所有已加载的插件,绿色表示已启用,红色表示已禁用
/pm info <plugin> 显示版本、作者、描述、网站、依赖项、软依赖项以及注册的命令
/pm enable <plugin> 启用一个已加载但被禁用的插件
/pm disable <plugin> 禁用该插件,并列出任何依赖于它的插件名称
/pm load <file.jar> 从 plugins 文件夹加载一个 jar 文件
/pm unload <plugin> 从内存中移除一个插件(包括类加载器)
/pm reload <plugin> 卸载并重新加载同一个文件
/pm update check 询问 Modrinth 和 Hangar 有哪些更新可用
/pm update install [plugin] 下载并暂存。不传参数或传入 all 则处理所有待处理的更新
/pm update list 列出无法匹配到任何已知插件的条目
/pm update rollback <plugin> 回滚至上一次更新前安装的版本
/pm update reload-config 重新读取 config.yml,重建 HTTP 客户端并重新调度定时器

带有空格的插件名称可以正常工作;子命令之后的所有内容会被重新拼接在一起。

更新检查在独立的守护线程上运行,绝不会占用服务器调度器,因此缓慢的 API 不会导致游戏刻(tick)卡顿。这也是该插件能在 Folia 上运行而无需接触调度器 API 的原因。

BungeeCord、Waterfall 和 Velocity 仅支持 /pm update ... 系列命令的一半功能。它们的插件管理器构建方式不同——Velocity 通过 Guice 在启动时一次性连接其插件,根本不支持运行时卸载——而在代理服务器上动态开关单个插件并不常见,因此额外引入反射的成本过高,不予采用。

权限

默认情况下,所有操作均需要 OP(管理员)权限。

节点 授予权限
plugmaster.* 以下所有权限
plugmaster.update.admin 所有 /pm update ... 子命令,以及登录通知
plugmaster.control.info /pm list 和 /pm info
plugmaster.control.enable /pm enable
plugmaster.control.disable /pm disable
plugmaster.control.load /pm load
plugmaster.control.unload /pm unload
plugmaster.control.reload /pm reload

拥有 plugmaster.update.admin 权限的管理员在登录时会看到待处理的更新列表;如果在检查发现更新时他们已经在线,则会立即收到通知。控制台日志可能会丢失这些信息,但加入时的消息不会。


配置

以下列表仅展示布局结构。同一份文件若将每个选项都附带文档说明,则包含在 jar 包内,你也可以直接在 Codeberg 上的 config.yml 阅读。

点击展开 config.yml 布局(29 行)
check-on-startup: true

check-interval-hours: 12

auto-download: false

channel: release

strict-game-version: true

notify-admins-on-join: true

ignore:
  - PlugMaster

modrinth:
  enabled: true
  bulk-check: true

hangar:
  enabled: true
  require-author-match: true

timeout-seconds: 20

max-download-megabytes: 200

首次检查会在服务器启动后 30 秒执行,以避免与服务器启动期间的其他任务竞争资源。

auto-download 默认关闭是出于有意设计。保持关闭状态时,PlugMaster 仅进行报告,每一次下载都是你主动请求的结果。只有在你信任其匹配逻辑后,才应开启此功能。


测试情况

平台无关的核心部分包含 72 项测试:针对真实 HTTP 服务器的下载、中途强制执行大小限制,以及对错误页面、校验和不符及外部 jar 文件的拒绝处理。

随后在真实服务器上运行了各项命令——Paper 1.21.11 和 Paper 1.20.6,无头模式,依次驱动 list、info、unload、load、reload(两次)以及从控制台执行 update check。两者均未抛出异常,且重新加载后的插件每次都能正确重新执行其自身的启动流程。

下载器也以相同方式进行了测试:在关闭状态下被拒绝,通过 /pm update reload-config 启用后,进行搜索,将真实插件下载到 plugins/ 目录并通过 /pm load 启动。

Velocity 3.5.0 也在实际代理服务器上经历了相同流程:一个由 velocity-plugin.json 识别的真实 Velocity 插件在 Modrinth 上被匹配,更新被下载、暂存,并在代理关闭时真正替换生效;此外还测试了对未安装插件的搜索与下载。

已知限制

在使用前值得了解。

  • BungeeCord 和 Waterfall 尚未在实际代理环境中验证。 更新相关的共享代码已由 Bukkit 和 Velocity 侧进行测试,但 BungeeCord 的入口点本身未经证实。
  • Hangar 的字段名是重构出来的,并未针对实时响应进行验证。 downloads、fileInfo.sha256Hash 和 namespace.owner 来自次要来源。代码设计上采取了防御性策略,缺失字段会导致验证失败而非整个运行失败,但请将 Hangar 的匹配视为两个数据源中可靠性较低的一个。
  • 卸载和重载操作触及服务器内部机制,而非官方 API,适用于两种类型的服务器。未来版本可能会将其迁移至更安全的接口;届时 PlugMaster 将选择拒绝执行,而不是半卸载某个插件。
  • 在 Paper 上,命令映射表可能保留旧条目。 Paper 使用其自身的命令系统作为后端,某些版本中会拒绝删除操作。卸载过程仍会完成——旧命令仅在下次重启前继续响应,PlugMaster 会告知你这一情况。
  • 未在任一服务上发布的插件无法被匹配。 这不是 bug,这正是 /pm update list 命令存在的原因。

Bug 报告非常有用。通常 /pm update check 的输出和你的服务器版本信息就足够了。


支持

由 LucasTHCR 制作并维护。

问题反馈、Bug 报告和功能建议请前往 dc.gg/paperstream。源代码托管于 Codeberg。


许可证

Copyright (C) 2026 LucasTHCR

PlugMaster 是自由软件:你可以根据自由软件基金会发布的 GNU 通用公共许可证第 3 版 的条款对其进行再分发和/或修改。

本程序的发布是希望它能有所帮助,但不提供任何担保;甚至不包括对适销性或特定用途适用性的隐含担保。详情请参阅 GNU 通用公共许可证。

简要说明:你可以使用、研究、修改并传播它。任何基于它进行分发的内容也必须采用 GPLv3 许可,并且必须附带其源代码。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源