MSU

模组

· 作者 ET_

本模组旨在自动化 Fabric 服务器上模组的更新流程

0 本站下载 0 关注 更新于 1 个月前

需要前置:Fabric API

最新 0.2.1-beta.3 · 26.3 · Fabric

一键开服(送7天)

Minecraft Server Updater

本模组为实验性内容!

请预见到可能会存在问题!

Minecraft Server Updater (MSU) 是一款适用于 Fabric 和 Forge 的服务端工具,用于通过 Modrinth 支持检查、安全暂存、基于包装器的安装、自动化以及回滚支持,保持 Minecraft 服务器处于最新状态。

安装匹配的 jar 文件:在 Fabric 上安装 minecraft-server-updater+fabric-…,在 Forge 上安装 minecraft-server-updater+forge-…。它们是独立的文件,不可互换使用。

MSU 专为希望无需频繁手动更新即可更新模组的服务器所有者和管理员设计!

核心理念: 检查哪些内容已过时,将安全的更新暂存到临时区域,然后在下次服务器启动前让包装器干净地应用这些更新。

亮点

  • 安全更新流程: 检查 → 暂存 → 重启时应用
  • 基于 Modrinth 的模组解析
  • 支持模组列表、参考模组文件夹和 .mrpack 文件
  • Fabric Loader / 启动器维护,或 Forge Loader / 垫片 / 参数文件维护
  • 可选的 Minecraft 版本升级检查
  • MSU 自我更新支持
  • 针对检查、暂存或安装工作流的自动化模式
  • 回滚与启动验证
  • 仅限操作员使用的 /msu 命令
  • 可读的状态输出,并明确说明允许暂存的原因
✨ 功能集

安全的检查 → 暂存 → 应用工作流

MSU 不会在 Minecraft 服务器运行时替换正在运行的模组 jar 文件。

相反,它采用三步流程:

  1. 检查(Check) — 查询 Modrinth 并检查配置的源。
  2. 暂存(Stage) — 下载或将替换文件准备到 .minecraft-server-updater/ 目录中。
  3. 应用(Apply) — 在下一次包装器启动时,暂存的文件会在 Fabric 或 Forge 启动之前被安装。

这使更新操作变得可预测,并避免修改服务器当前正在使用的 jar 文件。

模组更新检查

MSU 会检查已配置的模组是否拥有针对服务器当前运行的 Minecraft 版本的新版兼容构建。

支持的模组源:

源类型 功能
mod-list 在 .minecraft-server-updater/mod-list 中每行跟踪一个 Modrinth 项目简称、ID 或精确名称。
mods-folder 使用参考文件夹中的 jar 文件作为受管理的模组集合。
mrpack 使用 Modrinth 包文件或 URL 作为受管理的源。

模组列表条目仅通过直接的 Modrinth 项目 ID/简称或精确搜索结果进行解析 —— MSU 不会从模糊的名称中进行猜测。

服务器维护

MSU 可以检查并为当前 Minecraft 版本暂存服务端维护内容。

  • Fabric: 当启用时,包括 Fabric Loader 和 fabric-server-launch.jar。运行版本的 Fabric API 由模组检查/暂存处理。原版 server.jar 仅在 Minecraft 版本变更时才会更改。
  • Forge: 针对运行中 Minecraft 版本的最新版 Forge(由安装程序生成的垫片、run.bat / run.sh 以及 libraries/…/win_args.txt 或 unix_args.txt)。原版 jar 位于 libraries/net/minecraft/server/<mc>/ 下,而非作为根目录下的 server.jar。

Minecraft 升级

当启用 server-upgrade 时,MSU 可以检查以下内容的就绪状态:

  • 最新的 Minecraft 发布版本
  • 特定的目标 Minecraft 版本

服务器升级与常规的模组检查是分开的。 模组检查始终针对服务器实际运行的版本。服务器升级检查则针对配置好的升级版本,可能包括:

  • Minecraft 服务器 jar(Fabric 根目录下的 server.jar,或 Forge 针对该版本的库 jar)
  • 目标版本的 Fabric 启动器 / Loader 或 Forge 安装程序输出
  • 目标版本的 Fabric API(在 Fabric 上显示为服务器更新候选项,而非普通的模组列表更新)
  • 启用时针对升级目标的可选 模组预检(preflight)
  • 当 Minecraft 版本变更时所需的 目标兼容的 MSU jar(Fabric 和 Forge 的 MSU 文件分别发布)

自我更新

MSU 可以检查 Modrinth 上是否有更新的 MSU 构建可用,并为下一次重启暂存其自身的替换文件。升级到新的 Minecraft 版本的服务器可能需要同时暂存目标兼容的 MSU 构建。请在 Fabric 上使用 Fabric 文件,在 Forge 上使用 Forge 文件。

组合暂存

/msu stage all 可以将安全选定的目标组合成一个暂存的重启计划,允许服务器维护、模组更新、自我更新和兼容的 Minecraft 升级在一次重启中一次性应用,并仅进行一次备份。

如果配置了服务器升级但暂存不安全,组合暂存将在此停止,直到解决服务器预检问题后,才会暂存其他目标。

? 理解检查输出

MSU 在不同的行上报告安全性信息,以便您查看是否允许暂存以及为何不允许。

允许暂存的行

行 含义
Server safe to stage: true 服务器维护或升级可以暂存。
Server safe to stage: false; … 服务器暂存被阻止;原因在同一行显示(例如目标版本在 Modrinth 上缺少 MSU 或 Fabric API,或模组预检失败)。
Safe to stage mods: true/false 是否允许对当前运行的 Minecraft 版本执行 /msu stage mods。
Mods stage blocked: … 当模组暂存被阻止时显示(例如 no updates available、未知 jar、策略阻止或 mrpack 精确包问题)。
Mods ready for target: true/false 受管理的模组是否看起来已准备好用于配置的服务器升级目标(仅预检;不同于“今日有可用更新”)。

单次 check all 中包含两个 Minecraft 版本

/msu check all 可以显示以下内容:

  • check server — 当启用升级时,使用升级目标(例如 26.2)
  • check mods — 使用当前运行的版本(例如 26.1.2)

这是有意为之,但容易被误读。示例:

  • 服务器部分:Fabric API [missing → 0.152.1+26.2] 表示将执行 服务器升级,为目标版本安装 Fabric API —— 这并不意味着你的模组检查器发现了常规的模组更新。
  • 在 Forge 上,服务器部分名称显示为 Minecraft / Forge(例如 26.2 / 65.1.3),而不是 Fabric Loader / Fabric API。
  • 模组部分:0 updates available 表示在你当前运行的版本上无需暂存任何内容,即使计划了升级也是如此。

阻止“全部暂存”的因素

组合式暂存遵循安全优先原则:

  1. 如果有可用的服务器 升级,但 Server safe to stage: false(服务器可暂存:否),则 停止暂存,直到服务器预检通过,否则不会暂存模组或自身。
  2. 当模组对组合计划安全时会被纳入暂存范围 —— 包括某些升级情况,即模组在当前版本上没有更新,但仍已准备好用于目标版本。
  3. 仅当安全且尚未作为所需服务器升级 MSU 交换的一部分处理时,才会暂存自身更新。

暂存后使用 /msu status 可在重启前查看组合计划。

? 支持的更新源

MSU 围绕配置的更新源构建。

mod-list

最适合希望保持选定 Modrinth 项目列表更新的服务器。

默认文件:.minecraft-server-updater/mod-list(每行一个项目;不是 JSON 数组)。

示例:

fabric-api
lithium
c2me-fabric

在 Forge 上,以相同方式列出 Forge-loader 的 Modrinth 项目(每行一个缩写、ID 或确切标题)。

MSU 通过 Modrinth 解析这些项目,并为 运行中 的 Minecraft 版本检查兼容构建。

mods-folder

最适合保留已知良好 jar 包参考文件夹的服务器。

默认文件夹:.minecraft-server-updater/mods-folder。

MSU 读取参考 jar 包,尽可能识别 Modrinth 项目,并从该集合中管理更新。

mrpack

最适合基于 Modrinth 整合包的服务器。

MSU 可以管理来自 .mrpack 文件或 Modrinth 整合包 URL 的项目。

advanced.mrpackMode 控制行为:

模式 行为
exact(默认) 暂存确切的整合包文件和哈希值;严格的 Minecraft / 加载器检查。
tracking 将整合包项目 ID 视为受管理的列表,并解析最新的兼容构建。
?️ 安全模型

MSU 旨在避免冒险的热替换操作。

它不会热替换正在运行的 jar 包

服务器将继续使用当前加载的文件,直到重启。

暂存的更新单独存放

下载和替换文件首先准备在 MSU 暂存区域中。

包装器在启动前应用更新

当使用包装器启动服务器时,MSU 会在 Fabric 或 Forge 启动之前应用暂存计划。如果没有 --wrap(Fabric)或 --wrap-forge(Forge),你仍然可以检查和暂存,但在重启时不会应用任何更改。

回滚支持

当应用暂存计划时,MSU 可以记录备份元数据。如果启动验证失败,回滚支持有助于恢复之前的工作文件。

谨慎处理未知/自定义 jar 包

未知 jar 包可以根据本地文件名策略进行报告和挂起,但如果无法解析,MSU 不会将它们视为由 Modrinth 管理或经过兼容性检查。

服务器升级预检

启用后,MSU 会检查受管理的模组(及必需的依赖项)是否与 目标 Minecraft 版本兼容,然后才允许暂存服务器升级。在 Fabric 上,必要时目标版本的 Fabric API 被视为服务器升级路径的一部分进行处理。

破坏性未管理模组移除

当为 mod-list 或 mrpack 源启用时,暂存可能会列出将在应用时被删除的未管理 .jar 文件。只有当 advanced.allowRemoveUnmanagedMods 为 true 并且 已在当前暂存计划上运行 /msu stage confirm-destructive true 时,才会允许应用。

启动恢复与隔离

启动失败后,自动和手动暂存将被阻止,直到执行 /msu boot clear-failure。如果在应用时将无效的暂存计划隔离,请在再次暂存前使用 /msu quarantine acknowledge 确认。

⚙️ 命令

默认命令根路径:

/msu

所有 /msu 命令都需要操作员/管理员权限。

命令树

/msu
├── status
├── reload
├── check
│   ├── mods | server | self | all
├── stage
│   ├── mods | server | self | all
│   ├── confirm-destructive true | false
│   └── cancel
├── rollback [backupId]
├── boot
│   ├── clear-failure
│   └── force-retry
│       ├── current
│       └── <fingerprintId>
├── quarantine
│   ├── acknowledge
│   └── delete confirm
└── config
    ├── reset [param]
    └── set
        ├── source <type> [path]
        ├── automation <mode> [targets]
        ├── interval <minutes>
        ├── debug <on|off>
        ├── server-maintenance <on|off>
        ├── server-upgrade <token>
        ├── mrpack-mode <exact|tracking>
        ├── release-channel <channel> [mod]
        ├── held <on|off> <mod>
        └── required <on|off> <mod>

快速参考

命令 用途
/msu status 显示暂存的计划、运行时信息、配置、自动化设置、回滚状态、不安全状态警告以及格式化状态。
/msu reload 从磁盘重新加载配置并重启自动化任务。
/msu check mods 检查针对当前运行的 Minecraft 版本的已配置模组。
/msu check server 检查服务器维护情况以及可选的升级准备状态。
/msu check self 检查 MSU 自身更新。
/msu check all 运行所有已配置的检查项(根据情况包括服务器、模组和自身部分)。
/msu stage mods 仅为当前运行的 Minecraft 版本暂存模组更新。
/msu stage server 暂存安全的服务器维护或升级工作。
/msu stage self 暂存 MSU jar 替换操作。
/msu stage all 将所有安全选定的目标合并为一个综合计划进行暂存。
/msu stage cancel 清除已暂存的计划。
/msu stage confirm-destructive true / false 确认或清除活动暂存计划中破坏性的未管理模组移除操作。
/msu rollback 恢复最近一次应用备份。
/msu rollback <id> 恢复指定名称的备份。
/msu boot clear-failure 清除启动失败记录及连续启动失败计数(不会解除模组的暂停状态)。
/msu boot force-retry current 允许自动化任务重试当前失败的更新指纹。
/msu boot force-retry <fingerprintId> 允许自动化任务重试特定的失败更新指纹。
/msu quarantine acknowledge 确认被隔离的无效暂存计划,以便自动化任务继续执行。
/msu quarantine delete confirm 删除已确认的被隔离证据文件。
/msu config reset 使用文档记录的默认值重写配置。
/msu config reset <param> 重置特定的配置部分(例如 source、release-channel)。
/msu config set … 更改源、自动化、间隔、调试、服务器维护、升级、mrpack 模式、发布渠道、暂停模组或必需模组。

长时间运行的检查可能会输出到服务器日志;在 RCON 中你可能会看到后台通知——请阅读 logs/latest.log 以获取完整输出。

? 自动化

MSU 可以按定时器在后台运行检查任务。

自动化模式:

模式 行为
disabled 无后台活动。
check 仅报告;从不暂存文件。
stage 检查并暂存安全更新;你准备好后再重启服务器。
install 检查、暂存,然后停止服务器,以便包装器在重启时应用更新。

自动化目标:

目标 用途
mods 检查或暂存已配置模组源的更新(针对当前运行的 MC 版本)。
server 检查或暂存 Fabric 或 Forge 服务器的维护及可选的 Minecraft 升级。
self 检查或暂存 MSU 自身更新。

示例:

/msu config set automation stage server mods self
/msu config set interval 360

仅在通过包装器启动服务器(--wrap 或 --wrap-forge)且你接受 MSU 为了基于重启的安装而停止服务器的情况下,才使用 install 模式。

当存在活动的启动失败记录、有待确认的被隔离无效计划,或尚未清除/强制重试的失败更新指纹时,自动化将被阻止。

? 快速开始
  1. 将匹配的 MSU jar 放入 mods/ 目录。Fabric: minecraft-server-updater+fabric-<msu>.jar。Forge: minecraft-server-updater+forge-<msu>.jar。不要在同一个服务器上混用这两个 jar。当前文件名不包含 Minecraft 版本号;支持的客户端版本列表请参阅 Modrinth 上的文件页面。
  2. 配置你的更新源。
  3. 运行一次检查。
  4. 暂存可用的更新。
  5. 从服务器根目录启动并使用对应加载器的包装器(在 Forge 上替换原有的 run.bat / run.sh)。

Fabric 包装器

从包含 fabric-server-launch.jar 的目录启动。这些脚本会选取第一个 mods/minecraft-server-updater+fabric-*.jar(或 mods/minecraft-server-updater.jar)。

start.bat (Windows):

@echo off

REM set ram requirements here:
set MC_XMX=2G
set MC_XMS=2G

cd /d "%~dp0"
for %%F in ("mods\minecraft-server-updater+fabric-*.jar" "mods\minecraft-server-updater.jar") do (
  java -jar "%%F" --wrap -- java -Xmx%MC_XMX% -Xms%MC_XMS% -jar fabric-server-launch.jar --nogui
  goto :after
)
echo No Minecraft Server Updater jar found in mods\
pause
exit /b 1
:after

start.sh (Linux):

#!/usr/bin/env sh

# set ram requirements here
MC_XMX="${MC_XMX:-2G}"
MC_XMS="${MC_XMS:-2G}"

cd "$(dirname "$0")" || exit 1
for jar in mods/minecraft-server-updater+fabric-*.jar mods/minecraft-server-updater.jar; do
  if [ -f "$jar" ]; then
    exec java -jar "$jar" --wrap -- java -Xmx"$MC_XMX" -Xms"$MC_XMS" -jar fabric-server-launch.jar --nogui
  fi
done
echo "No Minecraft Server Updater jar found in mods/"
exit 1

在 Linux 上:执行 chmod +x start.sh,然后运行 ./start.sh。

Forge 包装器

Forge 不使用 --wrap -- java -jar …。--wrap-forge 会在 libraries/net/minecraftforge/forge/<minecraft>-<forge>/ 下查找已安装的坐标,并以与原版 run.bat 相同的方式启动:

java @user_jvm_args.txt @libraries/net/minecraftforge/forge/<mc>-<forge>/win_args.txt --nogui

请将 RAM 和其他 JVM 参数放在 user_jvm_args.txt 中。--wrap-forge 之后的额外参数(通常是 --nogui)是 Minecraft 程序参数。不要自行执行 java -jar forge-*-shim.jar;服务器根目录下残留的安装程序/shim jar 并非包装器所运行的内容。

start.bat (Windows):

@echo off
cd /d "%~dp0"
for %%F in ("mods\minecraft-server-updater+forge-*.jar" "mods\minecraft-server-updater.jar") do (
  java -jar "%%F" --wrap-forge --nogui
  goto :after
)
echo No Minecraft Server Updater jar found in mods\
pause
exit /b 1
:after

start.sh (Linux):

#!/usr/bin/env sh
cd "$(dirname "$0")" || exit 1
for jar in mods/minecraft-server-updater+forge-*.jar mods/minecraft-server-updater.jar; do
  if [ -f "$jar" ]; then
    exec java -jar "$jar" --wrap-forge --nogui
  fi
done
echo "在 mods/ 中未找到 Minecraft Server Updater jar 文件"
exit 1

在进行 Forge Minecraft / Forge 版本升级后,包装器会在下次启动时解析新的 win_args.txt / unix_args.txt,因此启动配置不会继续指向旧的坐标。

手动更新流程示例

/msu check mods
/msu stage mods
/msu status

然后使用包装器重新启动(start.bat、./start.sh 或上面的 java -jar mods/minecraft-server-updater+…jar … 命令)。

Minecraft 升级流程示例

/msu config set server-upgrade latest
/msu check server
/msu stage all
/msu status

在执行 stage all 之前,请阅读 Server safe to stage(服务器是否可安全暂存)——如果为 false,请先修复所述原因(通常是在 Modrinth 上发布/安装一个与目标兼容的 MSU 构建),然后再执行 stage all。

? 配置示例

配置文件:

config/minecraft-server-updater.json

示例结构:

{
  "debug": false,
  "mods": {
    "sourceType": "mod-list",
    "sourcePath": ".minecraft-server-updater/mod-list",
    "releaseChannel": "any"
  },
  "server": {
    "maintenance": true,
    "upgrade": "off"
  },
  "selfUpdate": {
    "enabled": true
  },
  "automation": {
    "mode": "disabled",
    "intervalMinutes": 360,
    "targets": []
  },
  "advanced": {
    "unknownModPolicy": "error",
    "modUpgradePolicy": "warn",
    "readinessMode": "all",
    "mrpackMode": "exact",
    "preflightBeforeServerUpgrade": true
  }
}

常用配置命令:

/msu config set source mod-list
/msu config set source mods-folder
/msu config set source mrpack modpack.mrpack
/msu config set server-maintenance on
/msu config set server-upgrade latest
/msu config set automation stage server mods self
/msu config set mrpack-mode exact
/msu config set debug on

如果自动化模式设置为 check、stage 或 install,但 targets 为空,则自动化将无事可做,直到你添加目标为止。

? 控制台格式化

MSU 支持为其自身的服务器日志行提供样式输出。

高级配置:

"betterFabricConsoleFormatting": "auto"

可用值:

值 行为
auto 当允许控制台颜色时,默认使用带样式的 MSU 输出。
on 当允许颜色时,强制使用带样式的 MSU 输出。
off 始终使用纯文本的 MSU 服务器日志输出。

如果在 Fabric 上单独安装了 Better Fabric Console,MSU 会避免双重渲染,并让 BFC 处理 Minecraft 格式化。Forge 使用 MSU 内置的转换器。当包装器设置 -Dterminal.ansi=true 时,包装过的服务器会保留颜色。

❌ MSU 不执行的操作

MSU 故意保持保守策略。

它不:

  • 在服务器运行时替换正在使用的 jar 文件
  • 将未知/自定义 jar 视为由 Modrinth 管理的项目
  • 在不使用包装器(--wrap 或 --wrap-forge)的情况下应用暂存的更新
  • 对非 Modrinth 文件进行魔法般的兼容性验证
  • 使用模糊的 Modrinth 搜索来解析配置的项目名称
  • 在单次检查中将“当前版本的常规模组更新”与“服务器升级暂存”混合在一起——请分别查看服务器和模组部分
  • 在 Forge 上运行 Fabric MSU jar,或在 Fabric 上运行 Forge MSU jar

推荐的工作流程

常规模组更新(同一 Minecraft 版本):

/msu check mods
/msu stage mods
/msu status

准备好后使用包装器重启。

计划的 Minecraft 升级:

/msu check server
/msu check mods
/msu stage all
/msu status

确认 Server safe to stage: true(服务器可安全暂存:是)并在重启前审查综合计划。

定时暂存:

/msu config set automation stage mods
/msu config set interval 360

无人值守安装工作流:

/msu config set automation install server mods self

仅在通过包装器启动服务器,且你希望 MSU 为了基于重启的安装而停止服务器时,才使用安装模式。

为什么使用 MSU?

MSU 为 Fabric 和 Forge 服务器所有者提供了一个受控的更新工作流:

  • 在任何更改发生之前,了解需要更新的内容
  • 当暂存被阻止时,获得清晰的拒绝原因
  • 安全地暂存文件,而不触碰正在运行的 jar
  • 通过包装器在启动前应用更新
  • 保持服务器文件与 Modrinth 管理的模组同步
  • 自动化常规检查
  • 如果应用的更新导致问题,可通过回滚支持恢复

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源