minecraft-server-admin

Minecraft 服务器管理技能

范围与路由边界

路由边界

• Use when：任务涉及 Minecraft 服务器的基础设施或实时运维（部署选择、调优、备份、代理、安全、事件响应）。
• Do not use when：任务是编写插件代码（minecraft-plugin-dev）或编写模组／加载器（minecraft-modding、minecraft-multiloader）。
• Do not use when：任务涉及 WorldEdit 命令工作流（minecraft-worldedit-ops）或 EssentialsX 工作流／策略设计（minecraft-essentials-ops）。
• Do not use when：任务是编写数据包／资源包（minecraft-datapack、minecraft-resource-pack）。

参考资料

• 如果任务涉及事件、上线窗口、代理更改或恢复演练，并且需要在操作前获取简明检查清单，请阅读 references/deployment-checklists.md。

---

部署决策矩阵

选择部署方案时使用此表。对于现有服务器，应先检查其技术栈和版本，除非用户要求迁移，否则应保留现状。

部署配置	推荐技术栈	适用场景	注意事项
小型 Paper SMP	仅使用 Paper	同时在线玩家不超过约 30 人、需要广泛的插件兼容性、希望降低运维负担	不要过早过度调优；更改许多默认值前先进行性能分析
大型公共 Paper 服务器	Paper + Spark + 更严格的插件／变更管控	公共服务器、玩家频繁加入、插件数量适中、需要保证运行时间	插件泛滥是 TPS 风险的首要来源
Velocity 支持的网络	Velocity + 多个 Paper 后端	大厅／小游戏／阵营玩法分布在多台服务器上，需要共享入口	转发／身份验证不匹配可能导致玩家无法加入
玩法内容丰富的 Purpur 服务器	Purpur（可选用 Velocity 作为前置代理）	希望在配置中调整玩法参数，而无需编写自定义插件	额外的开关会增加配置错误风险
高并发 Folia 服务器	Folia + 仅限兼容 Folia 的插件	并发量非常高，且目标是使用区域线程	许多插件并不兼容 Folia
Fabric／NeoForge 模组服务器	Fabric 或 NeoForge 服务器构建版本	需要加载器模组、自定义内容或整合包行为	Bukkit／Paper 插件不适用

部署类型路由

• 小型 SMP 和大多数公共插件服务器：优先采用 Paper 基线方案。
• 只有在明确需要 Purpur 的玩法控制选项时才使用 Purpur。
• 只有在验证插件兼容区域线程后才使用 Folia。
• 当单个进程无法满足需求，或需要划分不同后端角色时使用 Velocity。
• 当需求由模组驱动而非插件驱动时使用 Fabric／NeoForge。

Java 版本

• Paper 和 Purpur：Minecraft 26.1+ 需要 Java 25；Minecraft 1.21.x 使用 Java 21。更改版本前，请确认具体的 Paper／Purpur 构建版本和已安装的插件。
• 当前的 Velocity 4.x 需要 Java 25。对于旧版代理，应保留对应代理版本所需的 Java 版本，而不是默认采用当前版本。

---

操作手册：性能调优

步骤 1：建立基线

编辑前先收集基线数据。Linux 主机示例：

free -h
top -b -n 1 | head -n 25

Windows PowerShell 主机示例：

Get-CimInstance Win32_OperatingSystem | Select-Object FreePhysicalMemory,TotalVisibleMemorySize
Get-Process java | Sort-Object CPU -Descending | Select-Object -First 5 Id,CPU,WorkingSet,Path

在服务器控制台中：

tps
mspt
spark healthreport

记录：

• 玩家峰值人数
• 空闲和活动高峰时的 MSPT
• Spark 报告中 CPU 占用最高的插件

步骤 2：分析实际瓶颈

使用 Spark，而不是凭猜测：

spark profiler --timeout 180
spark tps
spark tickmonitor --threshold-tick 50

50 ms 阈值会报告超过一个正常 20 TPS 游戏刻的刻数；只有在事件阈值有意设置为其他值时才调整此阈值。

然后确定问题是否来自：

• 插件任务负载
• 实体数量／刷怪场压力
• 区块生成／磁盘 I/O
• 垃圾回收暂停

步骤 3：应用针对性修复

不要一次性调整所有内容。每次处理一组。

1. 区块与模拟负载：

• 首先降低 view-distance 和 simulation-distance
• 对以生存玩法为主的地图预生成世界

1. 实体负载：

• 在 Paper 世界配置中调整消失范围和生物生成行为
• 在适当情况下限制问题实体的数量

1. 插件负载：

• 根据 Spark 跟踪结果禁用或替换主要问题插件
• 在插件设置允许的情况下，降低异步任务频率

步骤 4：使用稳定的启动标志

对于当前版本的 Paper/Purpur 上的 Java 25，先采用简单且经过测量的基准配置：

java -Xms4G -Xmx4G -jar server.jar --nogui

仅当性能分析和玩家负载证明有必要时才增加堆内存。只有在针对确切的 JDK 和 Paper 版本验证后，才添加垃圾收集器标志。

步骤 5：验证改进效果

每次变更后：

spark tps
spark healthreport

只有在具有代表性的负载下，MSPT/刻稳定性有所改善时，才保留变更。

---

操作手册：插件运维

安全的插件变更工作流

1. 建立插件清单：

• 插件名称和版本
• 必需的依赖项
• 最低服务端版本

1. 在预发布环境中更新：

• 先在预发布环境中应用插件更新
• 运行冒烟测试：加入游戏、传送、经济系统、权限、存档

1. 生产环境发布窗口：

• 通知维护窗口
• 正常停止服务端
• 快照保存插件 jar 和配置
• 部署更新批次

1. 发布后验证：

• 留意启动日志中的 API 警告
• 运行命令和权限检查
• 持续跟踪 15-30 分钟的 TPS/MSPT

回滚检查清单

• 保留先前插件目录的快照。
• 如果发生严重回归：
  • 停止服务端
  • 恢复先前的插件 jar/配置
  • 启动并确认登录和世界完整性
• 记录导致故障的插件/版本组合，以便后续拦截。

---

操作手册：代理与转发（Velocity）

Velocity 基准配置

velocity.toml 必要配置：

bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

后端服务端要求

后端的 server.properties：

online-mode=false

Paper 后端转发支持（config/paper-global.yml）：

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "paste-the-shared-forwarding-secret-here"

使用存储在 Velocity 的 forwarding.secret 文件中的相同密钥值；后端配置需要的是密钥字符串本身，而不是文件路径。

除非你正在处理特定的旧版客户端或事件应急方案，否则请将 enforce-secure-profile 保持为服务端默认值。它并非 Velocity 基准配置的一部分。另请确认 spigot.yml 中的 settings.bungeecord: false；不要同时启用 BungeeCord 转发和 Velocity 现代转发。

验证操作手册

1. 确认客户端可以访问代理端口。
2. 确认后端已通过防火墙禁止直接访问互联网。
3. 通过代理加入游戏并验证：

• UUID 一致性
• 皮肤/档案转发
• 插件权限行为

常见代理故障

• “玩家信息转发无效”：
  • Velocity 与后端之间的转发模式或共享密钥不匹配。
• 随机身份验证/会话失败：
  • online-mode 设置不一致，或后端直接暴露在公网。

---

操作手册：备份与恢复

备份策略模板

资产	频率	保留期限	备注
每个已配置的世界文件夹	每小时增量备份 + 每日完整备份	保留 7 份每日备份、4 份每周备份	包含自定义世界和外部存储的世界
plugins/、config/ 和服务端根目录状态	每日	保留 14 份每日备份	运行恢复所必需
代理配置/密钥	每日	保留 30 份每日备份	加密后存储在主机之外
容器/编排文件	变更时 + 每周	保留 8 周	尽可能使用 Git 跟踪

示例备份脚本（Paper/Purpur）

对于生产服务器，在复制正在运行的世界文件夹之前，应暂停世界写入。 以下示例假设处于维护窗口，且服务器已正常停止。如果改用基于 RCON 的在线备份，请选择不会在命令参数中暴露密码的客户端／密钥机制。安全的实现必须先运行 save-off，然后运行 save-all，再复制数据，并确保即使复制失败也会执行 save-on 清理。不要将单独的刷新或 save-all 视为在线备份协议。Folia 禁用了 save-all；在此情况下，请正常停止服务器或使用经过验证的平台快照。信任任何备份之前，请先测试恢复流程。

对于 Fabric 或 NeoForge 恢复，还需清点 mods/，并记录准确的加载器启动状态：Minecraft 和加载器版本、Java 版本、启动命令及参数、启动器或安装程序制品，以及该部署使用的任何版本或库清单。将这些匹配的组件与配置的世界文件夹一并恢复；此 Paper/Purpur 示例不会替你捕获这些内容。

检查 level-name 和任何多世界插件配置后，将完整的世界文件夹列表作为参数提供，路径相对于 SERVER_ROOT。单独备份存储在该根目录之外的世界；不要根据 world* 推断备份范围。

#!/usr/bin/env bash
set -euo pipefail

if [[ "${SERVER_STOPPED_CONFIRMED:-}" != "1" ]]; then
  echo "Set SERVER_STOPPED_CONFIRMED=1 only after stopping the server cleanly." >&2
  exit 1
fi

DATE="$(date +%Y-%m-%d_%H-%M-%S)"
BACKUP_ROOT="/backups/minecraft"
SERVER_ROOT="/srv/minecraft"
DEST="${BACKUP_ROOT}/${DATE}"

if [[ "$#" -eq 0 ]]; then
  echo "Usage: backup.sh <world-folder> [additional-world-folders...]" >&2
  exit 1
fi
for world_dir in "$@"; do
  if [[ ! -d "$SERVER_ROOT/$world_dir" ]]; then
    echo "Missing configured world folder: $world_dir" >&2
    exit 1
  fi
done

mkdir -p "$DEST"

tar -czf "${DEST}/worlds.tar.gz" -C "$SERVER_ROOT" -- "$@"

state_items=()
for item in \
  plugins config server.properties bukkit.yml spigot.yml paper-global.yml \
  paper-world-defaults.yml permissions.yml ops.json whitelist.json \
  banned-players.json banned-ips.json; do
  [[ -e "$SERVER_ROOT/$item" ]] && state_items+=("$item")
done

if [[ "${#state_items[@]}" -gt 0 ]]; then
  tar -czf "${DEST}/server-state.tar.gz" -C "$SERVER_ROOT" "${state_items[@]}"
fi

恢复演练（必须测试）

1. 停止服务器。
2. 将选定的备份恢复到暂存目录。
3. 验证所有权／权限。
4. 在维护模式下启动服务器。
5. 验证：

• 世界出生点已加载
• 玩家数据可读取
• 关键插件已初始化

1. 重新向玩家开放。

定义目标：

• RPO（可接受的数据丢失时长）
• RTO（可接受的恢复时长）

---

操作手册：在线故障排查

事件分诊流程

1. 对事件分类：

• 启动时崩溃
• 严重卡顿／TPS 骤降
• 加入／身份验证失败
• 内存／磁盘压力

1. 先收集证据。Linux 主机示例：

df -h
free -h

Windows PowerShell 主机示例：

Get-PSDrive -PSProvider FileSystem
Get-CimInstance Win32_OperatingSystem | Select-Object FreePhysicalMemory,TotalVisibleMemorySize

从服务器／代理控制台执行：

spark tps
spark healthreport

1. 稳定局面：

• 停止有风险的发布变更
• 首先禁用最新的可疑插件
• 减少对玩家的影响（维护模式、临时队列、限制世界）

1. 恢复并记录：

• 应用回滚或热修复
• 记录根本原因和永久性预防措施

快速症状对照表

症状	首要检查项	典型根本原因
插件更新后启动崩溃	最新日志、插件依赖链	插件不兼容／API 不匹配
仅在高峰时段 MSPT 偏高	Spark 分析器、实体／区块统计信息	刷怪场、繁重的定时任务、区块 I/O
玩家无法通过代理加入	转发模式 + 密钥 + 后端暴露情况	Velocity／后端配置不匹配
周期性严重卡顿	GC 暂停 + 自动保存 + 备份重叠	内存压力、备份 I/O 争用

---

运维配置参考

server.properties 中影响较大的键

max-players=100
view-distance=10
simulation-distance=8
sync-chunk-writes=true
max-tick-time=60000
enable-rcon=false

bukkit.yml 和 spigot.yml

版本相关的默认值和副作用请以 Spigot/Bukkit 文档为准。 谨慎调整，并在每次变更后重新测量。

Paper 配置文件

• config/paper-global.yml
• config/paper-world-defaults.yml

只有在分析确认存在可处理的瓶颈后，才调整这些配置。

---

部署模式

Docker Compose（Paper）

services:
  paper:
    image: itzg/minecraft-server:java25
    container_name: mc-paper
    environment:
      EULA: "TRUE"
      TYPE: "PAPER"
      VERSION: "26.3"
      MEMORY: "10G"
    ports:
      - "25565:25565"
    volumes:
      - ./data:/data
    restart: unless-stopped

此 Docker 示例适用于当前版本的 Paper 26.3 和 Java 25。更改现有服务器的 Minecraft 或 Java 主版本前，请重新检查插件兼容性，并创建可恢复的备份。

Pterodactyl/Wings 说明

• 确保启动命令和内存分配与经过测试的 JVM 标志保持一致。
• 将面板和 Wings 版本固定为受支持的组合。
• 投入生产前，验证备份挂载和恢复工作流。

---

安全加固清单

• 除非代理转发要求后端使用 online-mode=false，否则请保持 online-mode=true。
• 使用 Velocity 时，切勿直接暴露后端 Paper 端口。
• 通过防火墙／IP 允许列表限制 RCON 和面板／管理界面。
• 轮换密钥（forwarding.secret、面板凭据、备份凭据）。
• 仅使用可信的插件来源；安装前验证校验和／发布来源。
• 维护异地主机上的加密备份。
• 及时修补 Java 运行时和主机操作系统。

---

参考资料

Paper（主要资料）

• https://docs.papermc.io/paper/
• https://docs.papermc.io/paper/getting-started/
• https://docs.papermc.io/paper/admin
• https://docs.papermc.io/paper/profiling/

Spigot/Bukkit（主要配置参考）

• https://www.spigotmc.org/wiki/spigot-configuration/
• https://www.spigotmc.org/wiki/bukkit-configuration/
• https://www.spigotmc.org/wiki/start-up-parameters/

代理和生态系统文档

• https://docs.papermc.io/velocity/
• https://docs.papermc.io/velocity/getting-started/
• https://docs.papermc.io/folia/faq/
• https://spark.lucko.me/docs
• https://spark.lucko.me/docs/Command-Usage
• https://github.com/itzg/docker-mc-backup
• https://geysermc.org/wiki/geyser/
• https://pterodactyl.io/project/introduction.html