【MCDR】安装和使用 MCDR

信息

本内容转自在简幻欢上安装和使用 MCDR - NorthZero ，感谢 NorthZeroD 为简幻欢社区文档带来的教程。

介绍

MCDR 是什么

MCDReforged (MCDR, 下同) 是一个管理 Minecraft 服务器的工具，拥有自定义插件系统。完全无需修改 Minecraft 服务器本身。

游戏内计算器，玩家高亮，计分板操作，结构文件管理，备份/回档... 你可以用 MCDR 和其插件控制整个 Minecraft 服务器。

点击了解更多

参考文档

参考

快速上手 — MCDReforged 2.15.1 文档

环境调用方法 - 简幻欢社区文档

调用信息对应表 - 简幻欢社区文档

准备

实例选择

1. 选择镜像类型 基础镜像
2. 选择实例类别 自定义-需有开服经验
3. 选择实例服务端 AIO
4. 选择实例版本 v1
5. 选择实例规格 随意

💡图示

启动脚本

简幻欢使用/home/container目录下的start.sh脚本作为启动脚本。当你在实例终端处按下▶️启动按钮时，服务器将执行启动脚本，即start.sh中的所有命令。

ℹ️图示

以下是简幻欢初始提供的启动脚本，我们只保留第一行#!/bin/bash，删去其余内容(删去高亮行)：

#!/bin/bash

maxmem=$((SERVER_MEMORY - 1000))

echo "使用请看文档 /web/custom_image/aio_v1/quick_start"
echo "使用请看文档 /web/custom_image/aio_v1/quick_start"
echo "使用请看文档 /web/custom_image/aio_v1/quick_start"
sleep 5

关于 Shell 命令

安装 MCDR

使用 pip 安装

在start.sh中写入以下内容：

#!/bin/bash

mise use -g python@3.13.3

pip3 install mcdreforged

然后运行实例。输出：

mise hint use multiple versions simultaneously with mise use python@3.12 python@3.11
mise ~/.aio/mise/config.toml tools: python@3.13.3
...此处省略若干行...
Installing collected packages: wcwidth, parse, urllib3, typing-extensions, ruamel.yaml.clib, resolvelib, psutil, prompt-toolkit, pathspec, packaging, idna, colorlog, colorama, charset_normalizer, certifi, ruamel.yaml, requests, mcdreforged
Successfully installed certifi-2025.8.3 charset_normalizer-3.4.3 colorama-0.4.6 colorlog-6.9.0 idna-3.10 mcdreforged-2.15.1 packaging-25.0 parse-1.20.2 pathspec-0.12.1 prompt-toolkit-3.0.52 psutil-7.0.0 requests-2.32.5 resolvelib-1.2.0 ruamel.yaml-0.18.15 ruamel.yaml.clib-0.2.12 typing-extensions-4.15.0 urllib3-2.5.0 wcwidth-0.2.13
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable.It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
...此处省略若干行...

我们做了什么？

我们利用mise，全局使用了Python 3.13.3，然后使用pip3命令安装了mcdreforged。

ℹ️关于 WARNING

不必理会。如果你想深究，见：

Why do I still get a warning about "Running pip as the 'root' user" inside a Docker container?

验证安装

在start.sh中，注释掉之前安装所用的命令，增加mcdreforged命令：

#!/bin/bash

# mise use -g python@3.13.3

# pip3 install mcdreforged

mcdreforged

技巧

在vscode编辑器中，选中代码块，使用ctrl+/快捷切换注释。

然后运行实例。输出：

MCDReforged 2.15.1 is starting up
MCDReforged is open source, u can find it here: https://github.com/MCDReforged/MCDReforged
[MCDR] [17:24:23] [MainThread/ERROR]: Configuration file 'config.yml' is missing
[MCDR] [17:24:23] [MainThread/INFO]: Looks like MCDR is not initialized at current directory /home/container
[MCDR] [17:24:23] [MainThread/INFO]: Use command "mcdreforged init" to initialize MCDR first
[MCDR] [17:24:23] [MainThread/INFO]: See document https://docs.mcdreforged.com/en/latest/quick_start.html#start-up

这证明我们已经成功安装了 MCDR。

初始化 MCDR

在start.sh中，为mcdreforged命令增加init参数：

#!/bin/bash

# mise use -g python@3.13.3

# pip3 install mcdreforged

mcdreforged init

然后运行实例。输出：

Initialized environment for MCDReforged in /home/container

这表明我们已经成功将 MCDR 初始化到目录/home/container，即start.sh所在位置。

在实例文件管理处，你能看到如下 MCDR 结构：

/home/container/
├── config/
├── logs/
├── plugins/
├── server/
├── config.yml
├── permission.yml
└── ...

ℹ️图示

做得好！我们已经成功安装并初始化了 MCDR🎉

安装 MC 服务端

要用 MCDR 管理 Minecraft 服务器，你首先需要准备并配置好一个 Minecraft 服务端。

例如，这是典型的原版 Minecraft 服务端目录结构：

./
├── libraries/
├── logs/
├── versions/
├── world/
├── banned-ips.json
├── banned-players.json
├── eula.txt
├── ops.json
├── minecraft_server.jar
├── server.properties
├── usercache.json
└── whitelist.json

已准备好服务端了？

直接将服务端所有文件上传到 MCDR 的server目录！

别忘了配置端口！

然后跳到配置 MCDR章节。

说明

篇幅有限，仅演示Leaf服务端的部署流程。

这些步骤同样适用于其他插件服务端，如Paper, Purpur。

上传核心

挑选你喜欢的服务端，从其官网下载服务端核心：

• Leaf 推荐__(为什么?)
• Purpur
• Paper
• Leaves

不知道怎么选？看这里...

将下载好的服务端核心上传到 MCDR 的server目录。

💡图示

启动命令

在start.sh中，将mcdreforged init命令注释掉，添加新的命令：

#!/bin/bash

# mise use -g python@3.13.3

# pip3 install mcdreforged

# mcdreforged init

cd server
${openjdk21} -Xms15G -Xmx15G -jar leaf-1.21.8-101.jar --nogui

注意

leaf-1.21.8-101.jar是笔者所用服务端核心的名称，应当换成你上传的核心名称。

-Xmx用来指定服务器最大内存，其后接内存大小(带单位)。建议设置为你的实例可用内存大小减 1G。

-Xms用来指定服务器最小内存，可与-Xmx设定的大小相同。

${openjdk21}是用来启动服务端的 java 程序，它被定义在环境变量中。可用值见调用信息对应表。

有关不同 MC 版本使用的 java 版本，见各 Minecraft 常见版本所需 Java 版本及其常见答疑（尽量长期维护）。

💡我们做了什么？

当我们启动实例，即运行start.sh时，我们的工作目录在/home/container中，也就是start.sh所处位置。

显然，我们的服务端核心文件不在这里，而是在/home/container/server目录中。因此，我们需要使用cd命令将工作目录切换到server目录。

接下来，我们调用环境变量openjdk21所指向的java程序，创建JVM(Java Virtual Machine，Java 虚拟机)，MC 服务端程序将在 JVM 上运行；

参数-Xms传递给JVM，指定堆内存的最小大小和初始大小为15G；

参数-Xmx传递给JVM，指定堆内存的最大大小为15G；

参数-jar传递给JVM，指定运行我们的服务端程序leaf-1.21.8-101.jar；

参数--nogui传递给MC服务端，指定启动服务端时不显示图形界面。

nogui与--nogui的作用相同，主要用于向后兼容非常旧的服务器版本，但更加推荐使用--nogui，因为它的格式与其他选项更一致。—— Minecraft Wiki

然后运行实例，输出：

Picked up _JAVA_OPTIONS: -Djava.util.prefs.userRoot=/home/container/.aio/.userPrefs -Djava.util.prefs.systemRoot=/home/container/.aio/.systemPrefs
Downloading mojang_1.21.8.jar
Applying patches
Starting org.bukkit.craftbukkit.Main
[21:50:29 INFO]: [bootstrap] Running Java 21 (OpenJDK 64-Bit Server VM 21.0.7+6-LTS; Azul Systems, Inc. Zulu21.42+19-CA) on Linux 6.1.0-21-amd64 (amd64)
[21:50:29 INFO]: [bootstrap] Loading Leaf 1.21.8-101-ver/1.21.8@6933848 (2025-09-06T06:38:44Z) for Minecraft 1.21.8
[21:50:30 INFO]: [LeafConfig] Loading config...
[21:50:30 INFO]: [LeafConfig] Successfully loaded config in 316ms.
[21:50:30 INFO]: [PluginInitializerManager] Initializing plugins...
[21:50:30 INFO]: [PluginInitializerManager] Initialized 0 plugins
[21:50:32 INFO]: [ReobfServer] Remapping server...
[21:50:39 WARN]: Failed to load eula.txt
[21:50:39 INFO]: You need to agree to the EULA in order to run the server. Go to eula.txt for more info.
[21:50:42 INFO]: [ReobfServer] Done remapping server in 10324ms.

看到这两句：

Failed to load eula.txt
You need to agree to the EULA in order to run the server. Go to eula.txt for more info.

这表明我们的服务端安装很成功。

接下来照其所言，你需要同意并签署Minecraft 最终用户许可协议才能运行此服务器。

签署 EULA

提醒

确保您已认真阅读并充分理解Minecraft 最终用户许可协议。

签署 EULA 后，您将负法律责任，且应同时遵守简幻欢的服务协议。

在服务端核心目录，即server目录中，找到eula.txt。

编辑其内容，将eula字段的值改为true：

#By changing the setting below to TRUE you are indicating your agreement to our EULA (https://aka.ms/MinecraftEULA).
#Sat Sep 06 21:50:39 CST 2025
eula=true

配置端口

在服务端核心目录，即server目录中，找到server.properties。

编辑其内容，将query.port和server-port字段的值改为你的实例端口号：

#Minecraft server properties
#Sun Sep 07 02:31:21 CST 2025
...此处省略若干行...
query.port=20814
...此处省略若干行...
server-port=20814
...此处省略若干行...

💡实例端口号是什么？

好样的！MC 服务端已经安装成功🎉

配置 MCDR

MCDR 的配置文件是 config.yml。它位于 MCDR 的工作目录中。

本教程中，config.yml与start.sh在同个目录，即/home/container中。

💡图示

在启动时，MCDR 将尝试加载配置文件，并将缺失的选项(如果有)添加到你的配置文件末尾。如果配置文件不存在，MCDR 则将生成默认配置文件并退出。

配置文件使用 YAML 格式。

当 MCDR 运行时，你可以使用 !!MCDR reload config 命令(或其缩写 !!MCDR r cfg)来重载配置文件。

说明

本教程仅介绍必要配置。完整配置说明见配置 — MCDReforged 2.15.1 文档。

language

MCDR 用于输出信息的语言。

更多...

将language字段的值更改为zh_cn以使用简体中文作为 MCDR 的输出信息的语言。

# The language that MCDR will use to display information
# Examples: "en_us", "zh_cn", "zh_tw"
language: zh_cn

start_command

启动服务端的控制台命令。它可以是一个字符串，或一个字符串列表。

更多...

将start_command字段的值更改为启动命令章节中所使用的命令。

# The command to start the server, it can be a string or a list of string
# (shell mode) If it's a string, the command will be executed as a shell command in a shell environment
# (exec mode) If it's a list of strings, the command will be executed directly
# Example command for starting a Minecraft server:
#   'java -Xms1G -Xmx2G -jar minecraft_server.jar nogui'                        (shell mode)
#   ['java', '-Xms1G', '-Xmx2G', '-jar', 'minecraft_server.jar', 'nogui']       (exec mode)
start_command: ${openjdk21} -Xms15G -Xmx15G -jar leaf-1.21.8-101.jar --nogui

handler

不同服务端有着截然不同的输出和命令。服务端处理器是用于在各种服务端之间进行处理的模块，也是 MCDR 控制服务端的接入点。

处理器确定解析服务端标准输出文本的特定方法，并使用正确的命令控制服务端。

更多...

将handler字段的值更改为符合你服务端种类的处理器。

本教程中，使用Leaf服务端，是 Paper 下游分支，故使用bukkit_handler。

# The handler to the specific way to parse the standard output text of the server and the correct command for server control
#   vanilla_handler    , for Vanilla / Carpet / Fabric server
#   beta18_handler     , for Vanilla server in legacy versions, e.g. < 1.7, or even beta1.8
#   bukkit_handler     , for Bukkit / Spigot server with Minecraft version below 1.14, and Paper / Mohist / Folia server in all version
#   bukkit14_handler   , for Bukkit / Spigot server with Minecraft version 1.14 and above
#   forge_handler      , for Forge server
#   cat_server_handler , for CatServer server
#   arclight_handler   , for Arclight server
#   bungeecord_handler , for Bungeecord server
#   waterfall_handler  , for Waterfall server
#   velocity_handler   , for Velocity server
handler: bukkit_handler

附：内置的处理器及适用的服务端：

处理器	兼容的服务端类型
vanilla_handler	用于 原版 / Carpet / Fabric 服务端。只要服务端足够原版就行
beta18_handler	用于低版本的原版服务端，如 MC < 1.7 的低版本，甚至到 beta1.8 版本。只在 1.6.4 和 beta 1.8.1 版本中进行了测试
bukkit_handler	用于 1.14 版本以下的 Bukkit / Spigot 服务端，以及所有版本的 Paper / Mohistmc 服务端
bukkit14_handler	用于 1.14 或以上版本的 Bukkit / Spigot 服务端
forge_handler	用于 Forge 服务端
cat_server_handler	适用于 CatServer 服务端
arclight_handler	适用于 Arclight 服务端
bungeecord_handler	用于 BungeeCord 服务端。请在启动命令的 -jar 参数之前添加 -Djline.terminal=jline.UnsupportedTerminal 参数以支持 MCDR。详见 此处
waterfall_handler	用于 WaterFall 服务端
velocity_handler	用于 Velocity 服务端
basic_handler	不进行任何分析并返回原始文本的处理器。除非你想使用 MCDR 启动非 Minecraft 相关的服务端，否则无需使用

恭喜！你完成了 MCDR 的配置🎉

启动 MCDR

命令

在start.sh中，将之前安装 MC 服务端的启动命令注释掉，添加新的命令：

#!/bin/bash

# mise use -g python@3.13.3

# pip3 install mcdreforged

# mcdreforged init

# cd server
# ${openjdk21} -Xms15G -Xmx15G -jar leaf-1.21.8-101.jar --nogui

mcdreforged

然后运行实例，输出：

MCDReforged 2.15.1 is starting up
MCDReforged is open source, u can find it here: https://github.com/MCDReforged/MCDReforged
[MCDR] [02:31:11] [MainThread/INFO]: 语言已设置为 zh_cn
[MCDR] [02:31:11] [MainThread/INFO]: 编码 / 解码方式已设置为 utf8 / utf8
[MCDR] [02:31:11] [MainThread/INFO]: 解析处理器已设置为 bukkit_handler
[MCDR] [02:31:11] [MainThread/INFO]: 插件文件夹列表:
[MCDR] [02:31:11] [MainThread/INFO]: - plugins
[MCDR] [02:31:11] [MainThread/INFO]: MCDReforged 2.15.1 正在启动
[MCDR] [02:31:11] [MainThread/INFO]: MCDReforged 正于 Python 3.13.3 环境中运行
[MCDR] [02:31:11] [TaskExecutor/INFO]: 刷新所有插件中
[MCDR] [02:31:11] [TaskExecutor/INFO]: 没有插件变更; 已加载插件数: 2
[MCDR] [02:31:11] [MainThread/INFO]: 正在启动服务端，启动参数为 '${openjdk21} -Xms15G -Xmx15G -jar leaf-1.21.8-101.jar --nogui'
[MCDR] [02:31:11] [MainThread/INFO]: 服务端正在以 PID 32 运行中
[Server] Picked up _JAVA_OPTIONS: -Djava.util.prefs.userRoot=/home/container/.aio/.userPrefs -Djava.util.prefs.systemRoot=/home/container/.aio/.systemPrefs
[MCDR] [02:31:12] [CheckUpdate/INFO]: MCDR 已为最新版
[Server] Starting org.bukkit.craftbukkit.Main
...此处省略若干行...
[Server] [02:31:30 INFO]: Done preparing level "world" (3.065s)
[Server] [02:31:30 INFO]: Running delayed init tasks
[Server] [02:31:30 INFO]: Done (17.474s)! For help, type "help"

看到这一句：

Done (17.474s)! For help, type "help"

这表明你的服务器顺利开起来了！

验证 MCDR

在 MC 多人游戏板块，使用play.simpfun.cn:你的实例端口号作为地址加入服务器。

💡图示

进入游戏后，在聊天栏输入命令并回车：

!!MCDR

输出以下内容：

大功告成！你成功部署了基于 MCDR 的 Minecraft 服务器！恭喜恭喜！🎉🎉(^o^)/欢迎大家的评论和 issues 哦 ♥️