DeerFolia · 安装与首次启动

准备运行环境

确认所选发行文件要求的 Java 运行时。在实际运行服务器的机器上执行：

java -version

在实际启动环境中再次检查运行时。面板、Docker 容器和 systemd 服务可能使用另一套 Java。不能确定时，在启动脚本中执行 java -version。

同时确认：

• 服务器硬盘有足够空间保存世界、备份和日志；
• 服务器运行用户对工作目录有读写权限；
• 防火墙、端口映射和面板启动命令已经准备好；
• 主要插件明确支持 Folia 或 DeerFolia。

下载核心

从 GitHub Releases 下载与服务器匹配的发行文件。以 release 标题和文件名为准。不要把旧 jar 重命名成其他发行文件。

将 jar 放进一个独立的服务器目录，例如：

deerfolia-server/
├── DeerFolia-<release>.jar
└── start.sh

DeerFolia 是完整服务端核心。不要将 jar 放进 plugins/，也不要同时放入 Paper、Purpur 或 Folia 的另一个启动 jar。

首次启动

在服务器目录执行启动命令。将 <release> 替换为已下载的文件名。下面的内存参数只是示例，请根据玩家数量、视距、世界数量和机器内存调整：

java -Xms4G -Xmx8G -jar DeerFolia-<release>.jar --nogui

第一次启动通常会生成 eula.txt 并停止。阅读并接受 Minecraft EULA。将 eula=false 改为 eula=true。再次执行启动命令。

不要直接复制一套来源不明的启动参数。先用最小参数确认核心能启动，再逐步加入 GC、调试或面板参数，这样出现问题时更容易定位。

首次启动后检查

服务器正常完成启动后，确认以下内容：

1. 日志没有 Java 版本、补丁应用或配置解析异常；
2. config/deer-folia.yml 已生成；
3. 如果 deer-folia.yml 中启用了 kaiiju-entity-throttling，config/kaiiju-entity-throttling.yml 也已生成；
4. 能进入服务器并完成一次移动、区块加载、传送和退出；
5. 主要插件没有被核心拒绝，也没有持续输出线程上下文错误；
6. 测试一台实体密集机器和一名挂机玩家，再决定是否修改默认优化。

如果配置文件没有生成，先不要手动创建一份空文件。查看启动日志是否在生成文件之前就停止，并先解决启动阶段的错误。

从其他核心迁移

从 Paper、Purpur 或 Folia 迁移时，建议使用以下顺序：

1. 停止旧服务器并等待世界保存完成；
2. 复制整个服务器目录，保留旧 jar 作为回滚版本；
3. 在复制目录中替换启动命令引用的核心 jar；
4. 第一次启动时只保留已经确认支持 Folia 的插件；
5. 验证玩家登录、区块加载、传送、红石、村民、刷怪和备份任务；
6. 确认无误后再让面板或 systemd 指向新目录。

插件配置通常可以继续使用，但不能假设插件的线程安全性、调度器调用和数据库访问都已经适配 Folia。遇到插件异常时，先在没有该插件的测试目录中复现。

升级 DeerFolia

升级前备份世界、配置、插件数据和当前 jar。停服后替换 jar，再启动并观察完整日志。DeerFolia 的配置管理器会在缺少已知键时补回默认值，但这不是迁移工具；升级前后仍应逐项比较配置差异。

如果新版本带来明显行为变化：

• 先在测试副本中使用新 jar；
• 一次只修改一个优化组；
• 记录修改前后的 TPS、CPU、内存和异常日志；
• 发现问题时恢复整个配置文件，而不是删除不清楚作用的键。

从源码构建

需要参与开发或无法使用发行文件时，可以从源码构建：

git clone https://github.com/LunaDeerMC/DeerFolia.git
cd DeerFolia
./gradlew applyAllPatches
./gradlew createPaperclipJar

完成后，核心文件位于 DeerFolia-server/build/libs/。请使用项目构建要求的 Java 运行时。除非需要验证补丁或参与开发，否则优先使用发行文件。