MSU

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

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

相反，它使用三步流程：

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

这确保了更新操作的可预测性，并避免修改服务器正在使用的 jar 文件。

模组更新检查

MSU 会检查已配置的模组是否有适用于服务器当前运行的 Minecraft 版本的更新版本。

支持的模组源：

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

服务器维护

MSU 可以检查并暂存当前 Minecraft 版本的服务端维护更新，启用时还包括 Fabric Loader 和启动器同步。

Minecraft 升级

当启用了 server-upgrade 时，MSU 可以检查是否准备好升级到：

• 最新的 Minecraft 发行版
• 一个特定的目标 Minecraft 版本

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

• Minecraft 服务端 jar 文件
• 目标版本的 Fabric 启动器 / Loader
• 目标版本的 Fabric API（在服务端更新候选项中显示，不作为常规模组列表更新）
• 启用时针对升级目标的可选模组预检

自更新

MSU 可以检查 Modrinth 上是否有更新的 MSU 版本，并为其自身的替换文件进行暂存，以便在下一次重启时应用。升级到新的 Minecraft 版本可能需要一起暂存一个兼容目标版本的 MSU 版本。

组合式暂存

/msu stage all 可以将所有安全的选定目标组合成一个重启计划，使得服务端维护、模组更新、自更新以及兼容的 Minecraft 升级可以在一次重启中完成，并创建一次备份。

如果配置了服务器升级但不适合暂存，组合式暂存将在此处停止，并且在服务器预检问题解决之前，不会暂存其他目标。

MSU 会在单独的行中报告安全状态，以便您了解是否允许暂存以及不允许的原因。

可安全暂存的行

在一次 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——并非您的模组检查器发现了常规模组更新。
• 模组部分：0 updates available 意味着在您当前运行的版本上无需暂存任何内容，即使有计划进行升级。

什么会阻止 stage all

组合式暂存按顺序遵循安全规则：

1. 如果服务器升级可用但 Server safe to stage: false，则 stage all 停止，并且在服务器预检通过之前，不会暂存模组或自身。
2. 当对组合计划安全时，包含模组——包括某些升级情况，其中模组在运行版本上没有更新，但已为目标版本做好准备。
3. 只有在安全且尚未作为必需服务器升级所需的 MSU 替换的一部分处理时，才会暂存自更新。

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

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

mod-list

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

默认文件：.minecraft-server-updater/mod-list（每行一个项目；不是 JSON 数组）。

示例：

fabric-api
lithium
c2me-fabric

MSU 通过 Modrinth 解析这些项目，并检查是否有适用于正在运行的 Minecraft 版本的兼容版本。

mods-folder

最适合存放一个已知良好 jar 文件参考文件夹的服务器。

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

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

mrpack

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

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

advanced.mrpackMode 控制行为：

MSU 旨在避免有风险的实时替换。

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

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

暂存的更新被单独保存

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

包装器在启动前应用更新

当使用包装器启动服务器时，MSU 会在 Fabric 启动前应用暂存计划。如果不使用 --wrap，您仍然可以检查和暂存，但重启时不会应用任何内容。

回滚支持

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

未知/自定义 jar 文件被谨慎处理

未知的 jar 文件可以通过本地文件名策略进行报告和保留，但除非它们能被解析，否则 MSU 不会将其视为由 Modrinth 管理或进行了兼容性检查。

服务器升级预检

启用时，MSU 会在允许暂存服务器升级之前，检查管理的模组（以及必需的依赖项）看起来与目标 Minecraft 版本兼容。当需要时，目标版本的 Fabric API 会作为服务器升级路径的一部分进行处理。

默认命令根：

/msu

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

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

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

自动化模式：

自动化目标：

示例：

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

仅当服务器通过包装器启动，并且您愿意让 MSU 停止服务器以进行基于重启的安装时，才使用 install 模式。

1. 将 MSU jar 文件放入您的服务器 mods/ 文件夹。Modrinth 发行版使用带版本号的名称，例如 minecraft-server-updater+fabric-26.1.2-0.2.0-beta.4.jar——当 Minecraft 或 MSU 版本更改时，文件名会变化。
2. 配置您的更新源。
3. 运行一次检查。
4. 暂存可用的更新。
5. 从服务器根目录（即 fabric-server-launch.jar 所在的位置）使用下面的包装器命令启动服务器。

包装器启动脚本

这些是小型启动器脚本，用于替换服务器根目录中的现有启动脚本。它会选择第一个 mods/minecraft-server-updater+fabric-*.jar（或 mods/minecraft-server-updater.jar）并在所有平台上运行相同的包装器命令。

start.bat (Windows):

@echo off

:: 在这里设置内存要求：
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 在 mods\ 目录中未找到 Minecraft Server Updater jar 文件
pause
exit /b 1
:after

start.sh (Linux):

#!/usr/bin/env sh

# 在这里设置内存要求：
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 "在 mods/ 目录中未找到 Minecraft Server Updater jar 文件"
exit 1

在 Linux 上：chmod +x start.sh，然后 ./start.sh。

手动更新流程示例

/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

在暂存之前阅读 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 debug on

如果自动化模式为 check、stage 或 install，但 targets 为空，则自动化运行时将无事可做，直到您添加目标。

MSU 为其自身的服务器日志行包含格式化输出支持。

高级配置：

"betterFabricConsoleFormatting": "auto"

可用值：

如果单独安装了 Better Fabric Console，MSU 会避免双重渲染，让 BFC 处理 Minecraft 格式。

MSU 有意保持保守。

它不会：

• 在服务器运行时替换正在运行的 jar 文件
• 将未知/自定义的 jar 文件视为 Modrinth 管理的项目
• 在没有包装器的情况下应用暂存的更新
• 神奇地验证非 Modrinth 文件的兼容性
• 使用模糊的 Modrinth 搜索来解析配置的项目名称
• 在一次检查中混用“当今版本的常规模组更新”与“服务器升级暂存”——请分别阅读服务器和模组部分