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 文件。
相反,它采用三步流程:
- 检查(Check) — 查询 Modrinth 并检查配置的源。
- 暂存(Stage) — 下载或将替换文件准备到
.minecraft-server-updater/ 目录中。
- 应用(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 表示在你当前运行的版本上无需暂存任何内容,即使计划了升级也是如此。
阻止“全部暂存”的因素
组合式暂存遵循安全优先原则:
- 如果有可用的服务器 升级,但
Server safe to stage: false(服务器可暂存:否),则 停止暂存,直到服务器预检通过,否则不会暂存模组或自身。
- 当模组对组合计划安全时会被纳入暂存范围 —— 包括某些升级情况,即模组在当前版本上没有更新,但仍已准备好用于目标版本。
- 仅当安全且尚未作为所需服务器升级 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 模式。
当存在活动的启动失败记录、有待确认的被隔离无效计划,或尚未清除/强制重试的失败更新指纹时,自动化将被阻止。
? 快速开始
- 将匹配的 MSU jar 放入
mods/ 目录。Fabric: minecraft-server-updater+fabric-<msu>.jar。Forge: minecraft-server-updater+forge-<msu>.jar。不要在同一个服务器上混用这两个 jar。当前文件名不包含 Minecraft 版本号;支持的客户端版本列表请参阅 Modrinth 上的文件页面。
- 配置你的更新源。
- 运行一次检查。
- 暂存可用的更新。
- 从服务器根目录启动并使用对应加载器的包装器(在 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 管理的模组同步
- 自动化常规检查
- 如果应用的更新导致问题,可通过回滚支持恢复
Minecraft Server Updater
This mod is experimental!
Please assume that there may be issues!
Minecraft Server Updater (MSU) is a server-side Fabric and Forge utility for keeping a Minecraft server up to date with Modrinth-backed checks, safe staging, wrapper-based installs, automation, and rollback support.
Install the matching jar: minecraft-server-updater+fabric-… on Fabric, minecraft-server-updater+forge-… on Forge. They are separate files and are not interchangeable.
MSU is designed for server owners and admins who want update mods without having to constantly manually update them!
Core idea:
Check what is outdated, stage safe updates into a holding area, then let the wrapper apply them cleanly before the next server boot.
Highlights
- Safe update flow: check → stage → apply on restart
- Modrinth-backed mod resolution
- Supports mod lists, reference mod folders, and
.mrpack files
- Fabric Loader / launcher maintenance, or Forge loader / shim / args-file maintenance
- Optional Minecraft version upgrade checks
- Self-update support for MSU
- Automation modes for check, stage, or install workflows
- Rollback and boot verification
- Operator-only
/msu commands
- Readable status output with clear safe-to-stage reasons
✨ Feature set
Safe check → stage → apply workflow
MSU does not replace running mod jars while the Minecraft server is live.
Instead, it uses a three-step process:
- Check — query Modrinth and inspect the configured source.
- Stage — download or prepare replacement files into
.minecraft-server-updater/.
- Apply — on the next wrapper start, staged files are installed before Fabric or Forge starts.
This keeps update actions predictable and avoids modifying jars that the server is currently using.
Mod update checks
MSU checks whether configured mods have newer compatible builds for the Minecraft version the server is running right now.
Supported mod sources:
| Source type |
What it does |
mod-list |
Tracks one Modrinth project slug, id, or exact name per line in .minecraft-server-updater/mod-list. |
mods-folder |
Uses jars in a reference folder as the managed mod set. |
mrpack |
Uses a Modrinth pack file or URL as the managed source. |
Mod-list entries resolve only by direct Modrinth project id/slug or an exact search hit — MSU does not guess from ambiguous names.
Server maintenance
MSU can check and stage server-side maintenance for the current Minecraft version.
- Fabric: Fabric Loader and
fabric-server-launch.jar when enabled. Fabric API for the running version is handled by mod checks/staging. The vanilla server.jar only changes when Minecraft changes version.
- Forge: latest Forge for the running Minecraft version (installer-generated shim,
run.bat / run.sh, and libraries/…/win_args.txt or unix_args.txt). The vanilla jar lives under libraries/net/minecraft/server/<mc>/, not as a root server.jar.
Minecraft upgrades
When server-upgrade is enabled, MSU can check readiness for:
- Latest Minecraft release
- A specific target Minecraft version
Server upgrades are separate from routine mod checks. Mod checks always target the version the server is actually running. Server upgrade checks target the configured upgrade version and may include:
- Minecraft server jar (Fabric root
server.jar, or Forge’s library jar for that version)
- Fabric launcher / loader or Forge installer output for the target version
- Fabric API for the target version on Fabric (shown under server update candidates, not as a normal mod-list update)
- Optional mod preflight for the upgrade target when enabled
- A target-compatible MSU jar when Minecraft version changes (Fabric and Forge MSU files are published separately)
Self-update
MSU can check whether a newer MSU build is available on Modrinth and stage its own replacement for the next restart. Server upgrades to a new Minecraft version may require a target-compatible MSU build to be staged together. Use the Fabric file on Fabric and the Forge file on Forge.
Combined staging
/msu stage all can combine safe selected targets into one staged restart plan, allowing server maintenance, mod updates, self updates, and compatible Minecraft upgrades to apply on one restart with one backup.
If a server upgrade is configured but not safe to stage, combined staging stops there and does not stage other targets until server preflight is resolved.
? Understanding check output
MSU reports safety on separate lines so you can see whether staging is allowed and why not.
Safe-to-stage lines
| Line |
Meaning |
Server safe to stage: true |
Server maintenance or upgrade can be staged. |
Server safe to stage: false; … |
Server staging is blocked; the reason is on the same line (for example missing MSU or Fabric API on Modrinth for the target version, or mod preflight failure). |
Safe to stage mods: true/false |
Whether /msu stage mods is allowed for the running Minecraft version. |
Mods stage blocked: … |
Shown when mod staging is blocked (for example no updates available, unknown jars, policy blocks, or mrpack exact-pack issues). |
Mods ready for target: true/false |
Whether managed mods look ready for a configured server upgrade target (preflight only; not the same as “updates available today”). |
Two Minecraft versions in one check all
/msu check all can show both:
check server — uses the upgrade target (for example 26.2) when upgrade is enabled
check mods — uses the running version (for example 26.1.2)
That is intentional, but easy to misread. Example:
- Server section:
Fabric API [missing → 0.152.1+26.2] means the server upgrade will install Fabric API for the target version — not that your mod checker found a routine mod update.
- On Forge, the server section names Minecraft / Forge (for example
26.2 / 65.1.3) instead of Fabric Loader / Fabric API.
- Mod section:
0 updates available means nothing needs staging on the version you are running now, even if an upgrade is planned.
What blocks stage all
Combined staging follows safety in order:
- If a server upgrade is available but
Server safe to stage: false, stage all stops and does not stage mods or self until server preflight passes.
- Mods are included when safe for the combined plan — including some upgrade cases where mods have no updates on the running version but are still ready for the target.
- Self-update is staged only when safe and not already handled as part of a required server-upgrade MSU swap.
Use /msu status after staging to see the combined plan before restart.
? Supported update sources
MSU is built around a configured update source.
mod-list
Best for servers where you want to keep a chosen list of Modrinth projects up to date.
Default file: .minecraft-server-updater/mod-list (one project per line; not a JSON array).
Example:
fabric-api
lithium
c2me-fabric
On Forge, list Forge-loader Modrinth projects the same way (one slug, id, or exact title per line).
MSU resolves those projects through Modrinth and checks for compatible builds for the running Minecraft version.
mods-folder
Best for servers that keep a reference folder of known-good jars.
Default folder: .minecraft-server-updater/mods-folder.
MSU reads the reference jars, identifies Modrinth projects where possible, and manages updates from that set.
mrpack
Best for servers based on a Modrinth modpack.
MSU can manage projects from a .mrpack file or a Modrinth pack URL.
advanced.mrpackMode controls behavior:
| Mode |
Behaviour |
exact (default) |
Stage the exact pack files and hashes; strict Minecraft / loader checks. |
tracking |
Treat pack project ids as a managed list and resolve latest compatible builds. |
?️ Safety model
MSU is designed to avoid risky live replacement.
It does not hot-swap running jars
The server keeps using the currently loaded files until restart.
Staged updates are held separately
Downloads and replacement files are prepared in the MSU staging area first.
The wrapper applies updates before boot
When the server is started with the wrapper, MSU applies the staged plan before Fabric or Forge starts. Without --wrap (Fabric) or --wrap-forge (Forge), you can still check and stage, but nothing applies on restart.
Rollback support
When a staged plan is applied, MSU can record backup metadata. If boot verification fails, rollback support helps restore the previous working files.
Unknown/custom jars are handled carefully
Unknown jars can be reported and held by local filename policy, but MSU does not treat them as Modrinth-managed or compatibility-checked unless they can be resolved.
Server upgrade preflight
When enabled, MSU checks that managed mods (and required dependencies) look compatible with the target Minecraft version before allowing a server upgrade to stage. On Fabric, Fabric API for the target version is handled as part of the server upgrade path when needed.
Destructive unmanaged mod removal
When enabled for mod-list or mrpack sources, staging may list unmanaged .jar files that would be deleted on apply. Apply is blocked until advanced.allowRemoveUnmanagedMods is true and /msu stage confirm-destructive true has been run on the active staged plan.
Boot recovery and quarantine
After a failed boot, automation and manual staging are blocked until /msu boot clear-failure. If an invalid staged plan is quarantined at apply time, acknowledge it with /msu quarantine acknowledge before staging again.
⚙️ Commands
Default command root:
/msu
All /msu commands require operator/admin permission.
Command tree
/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>
Quick reference
| Command |
Purpose |
/msu status |
Show staged plan, runtime info, config, automation, rollback, unsafe-state warnings, and formatting state. |
/msu reload |
Reload config from disk and restart automation. |
/msu check mods |
Check configured mods for the running Minecraft version. |
/msu check server |
Check server maintenance and optional upgrade readiness. |
/msu check self |
Check for an MSU self-update. |
/msu check all |
Run all configured checks (server, mods, and self sections as applicable). |
/msu stage mods |
Stage mod updates for the running Minecraft version only. |
/msu stage server |
Stage safe server maintenance or upgrade work. |
/msu stage self |
Stage an MSU jar replacement. |
/msu stage all |
Stage all safe selected targets into one combined plan. |
/msu stage cancel |
Clear the staged plan. |
/msu stage confirm-destructive true / false |
Acknowledge or clear destructive unmanaged mod removal on the active staged plan. |
/msu rollback |
Restore the most recent apply backup. |
/msu rollback <id> |
Restore a named backup. |
/msu boot clear-failure |
Clear failed-boot record and boot failure streak (does not un-hold mods). |
/msu boot force-retry current |
Allow automation to retry the current failed-update fingerprint. |
/msu boot force-retry <fingerprintId> |
Allow automation to retry a specific failed-update fingerprint. |
/msu quarantine acknowledge |
Acknowledge a quarantined invalid staged plan so automation can continue. |
/msu quarantine delete confirm |
Delete acknowledged quarantined evidence files. |
/msu config reset |
Rewrite the config with documented defaults. |
/msu config reset <param> |
Reset a specific config section (for example source, release-channel). |
/msu config set … |
Change source, automation, interval, debug, server maintenance, upgrade, mrpack mode, release channel, held mods, or required mods. |
Long-running checks may print to the server log; in RCON you may see a background notice — read logs/latest.log for full output.
? Automation
MSU can run background checks on a timer.
Automation modes:
| Mode |
Behaviour |
disabled |
No background activity. |
check |
Report only; never stages files. |
stage |
Checks and stages safe updates; you restart when ready. |
install |
Checks, stages, then stops the server so the wrapper can apply updates on restart. |
Automation targets:
| Target |
Purpose |
mods |
Check or stage configured mod source updates (running MC version). |
server |
Check or stage Fabric or Forge server maintenance and optional Minecraft upgrades. |
self |
Check or stage MSU self-update. |
Example:
/msu config set automation stage server mods self
/msu config set interval 360
Use install only when the server is started through the wrapper (--wrap or --wrap-forge) and you are comfortable with MSU stopping the server for restart-based installation.
Automation is blocked while a failed boot record is active, a quarantined invalid plan is pending acknowledgement, or a failed-update fingerprint has not been cleared or force-retried.
? Quick start
- Put the matching MSU jar in
mods/. Fabric: minecraft-server-updater+fabric-<msu>.jar. Forge: minecraft-server-updater+forge-<msu>.jar. Do not mix both jars on one server. Current names do not embed the Minecraft version; list supported game versions on the Modrinth file.
- Configure your update source.
- Run a check.
- Stage available updates.
- Start from the server root with the wrapper for your loader (replace stock
run.bat / run.sh on Forge).
Fabric wrapper
Start from the directory that contains fabric-server-launch.jar. These scripts pick the first mods/minecraft-server-updater+fabric-*.jar (or 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
On Linux: chmod +x start.sh, then ./start.sh.
Forge wrapper
Forge does not use --wrap -- java -jar …. --wrap-forge finds the installed coordinate under libraries/net/minecraftforge/forge/<minecraft>-<forge>/ and launches the same way stock run.bat does:
java @user_jvm_args.txt @libraries/net/minecraftforge/forge/<mc>-<forge>/win_args.txt --nogui
Put RAM and other JVM flags in user_jvm_args.txt. Extra arguments after --wrap-forge (usually --nogui) are Minecraft program args. Do not java -jar forge-*-shim.jar yourself; leftover installer/shim jars in the server root are not what the wrapper runs.
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 "No Minecraft Server Updater jar found in mods/"
exit 1
After a Forge Minecraft/Forge bump, the wrapper resolves the new win_args.txt / unix_args.txt on the next start so launch does not stay pointed at the previous coordinate.
Example manual update flow
/msu check mods
/msu stage mods
/msu status
Then restart with the wrapper (start.bat, ./start.sh, or the java -jar mods/minecraft-server-updater+…jar … line above).
Example Minecraft upgrade flow
/msu config set server-upgrade latest
/msu check server
/msu stage all
/msu status
Read Server safe to stage before staging — if it is false, fix the stated reason (often publish/install a target-compatible MSU build on Modrinth) before stage all.
? Example configuration
Config file:
config/minecraft-server-updater.json
Example shape:
{
"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
}
}
Common config commands:
/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
If automation mode is check, stage, or install but targets is empty, automation runs with nothing to do until you add targets.
? Console formatting
MSU includes styled output support for its own server-log lines.
Advanced config:
"betterFabricConsoleFormatting": "auto"
Available values:
| Value |
Behaviour |
auto |
Default styled MSU output when console colour is allowed. |
on |
Force styled MSU output when colour is allowed. |
off |
Always use plain MSU server-log output. |
If Better Fabric Console is installed separately on Fabric, MSU avoids double-rendering and lets BFC handle Minecraft formatting. Forge uses MSU’s embedded converter. Wrapped servers keep colour when the wrapper sets -Dterminal.ansi=true.
❌ What MSU does not do
MSU is intentionally conservative.
It does not:
- Replace live jars while the server is running
- Treat unknown/custom jars as Modrinth-managed projects
- Apply staged updates without the wrapper (
--wrap or --wrap-forge)
- Magically verify compatibility for non-Modrinth files
- Use fuzzy Modrinth search to resolve configured project names
- Mix “routine mod updates on today’s version” with “server upgrade staging” in a single check — read server and mod sections separately
- Run a Fabric MSU jar on Forge, or a Forge MSU jar on Fabric
Recommended workflow
Routine mod updates (same Minecraft version):
/msu check mods
/msu stage mods
/msu status
Restart with the wrapper when ready.
Planned Minecraft upgrade:
/msu check server
/msu check mods
/msu stage all
/msu status
Confirm Server safe to stage: true and review the combined plan before restart.
Scheduled staging:
/msu config set automation stage mods
/msu config set interval 360
Unattended install workflows:
/msu config set automation install server mods self
Use install mode only when the server is started through the wrapper and you are happy for MSU to stop the server for restart-based installation.
Why use MSU?
MSU gives Fabric and Forge server owners a controlled update workflow:
- See what needs updating before anything changes
- Get clear reasons when staging is blocked
- Stage files safely without touching live jars
- Apply updates before boot through the wrapper
- Keep server files and Modrinth-managed mods in sync
- Automate routine checks
- Recover with rollback support if an applied update causes problems
评论 0
登录后参与评分
还没有评论,来抢沙发吧