Minecraft PaperMC 服务器部署指南 / 02 - 安装与首次启动

02 - 安装与首次启动

2.1 Java 环境配置

PaperMC 依赖 Java 运行时。不同 Minecraft 版本对 Java 版本有不同要求。

2.1.1 Java 版本对照表

Minecraft 版本	PaperMC 支持的最低 Java 版本	推荐 Java 版本
1.17 - 1.17.1	Java 16	Java 17
1.18 - 1.20.4	Java 17	Java 21
1.20.5+	Java 21	Java 21

注意：2026 年最新版本（1.21.x）强制要求 Java 21。低于此版本将无法启动。

2.1.2 Linux 安装 Java 21

Ubuntu / Debian：

# 方式一：使用 APT 安装 OpenJDK
sudo apt update
sudo apt install -y openjdk-21-jdk

# 验证安装
java -version
# 输出示例：
# openjdk version "21.0.4" 2024-07-16 LTS

# 方式二：使用 Adoptium（Eclipse Temurin）
sudo apt install -y wget apt-transport-https gnupg
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo gpg --dearmor -o /usr/share/keyrings/adoptium.gpg
echo "deb [signed-by=/usr/share/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
sudo apt update
sudo apt install -y temurin-21-jdk

CentOS / RHEL / Fedora：

# Fedora
sudo dnf install -y java-21-openjdk-devel

# CentOS / RHEL
sudo yum install -y java-21-openjdk-devel

# 验证
java -version

2.1.3 Windows 安装 Java 21

# 方式一：使用 winget
winget install EclipseAdoptium.Temurin.21.JDK

# 方式二：使用 Chocolatey
choco install temurin21

# 方式三：手动下载
# 访问 https://adoptium.net/ 下载安装包

# 验证（重启终端后）
java -version

2.1.4 管理多个 Java 版本

如果系统中有多个 Java 版本，需要设置默认版本：

# Linux - 使用 update-alternatives
sudo update-alternatives --config java

# 输出示例：
# Selection    Path                                     Priority   Status
# ------------------------------------------------------------
#  0           /usr/lib/jvm/java-17-openjdk/bin/java     1711      auto mode
#  1           /usr/lib/jvm/java-21-openjdk/bin/java     2111      auto mode
# *2           /usr/lib/jvm/java-21-openjdk/bin/java     2111      manual mode

# 选择 Java 21 对应的编号

# 设置 JAVA_HOME（写入 ~/.bashrc 或 /etc/environment）
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

2.2 创建服务器目录

# 创建专用目录
sudo mkdir -p /opt/minecraft/paper
sudo chown $USER:$USER /opt/minecraft/paper
cd /opt/minecraft/paper

建议：将服务器放在独立目录中，不要放在 home 目录的深层路径，方便管理和备份。

2.2.1 目录结构规划

/opt/minecraft/paper/
├── paper.jar              # PaperMC 服务端 JAR
├── server.properties      # 服务器核心配置
├── eula.txt               # EULA 同意文件
├── banned-players.json    # 封禁列表
├── banned-ips.json        # IP 封禁列表
├── ops.json               # 管理员列表
├── whitelist.json         # 白名单
├── config/                # Paper 配置目录
│   ├── paper-global.yml
│   └── paper-world-defaults.yml
├── plugins/               # 插件目录
├── world/                 # 主世界
├── world_nether/          # 下界
├── world_the_end/         # 末地
├── logs/                  # 日志目录
└── backups/               # 备份目录

2.3 下载 PaperMC

2.3.1 获取下载链接

PaperMC 使用 API 提供下载，需要指定版本和构建号：

# 查看最新版本信息
curl -s https://api.papermc.io/v2/projects/paper | python3 -m json.tool

# 查看指定版本的最新构建
MINECRAFT_VERSION="1.21.4"
curl -s "https://api.papermc.io/v2/projects/paper/versions/${MINECRAFT_VERSION}/builds" \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
builds = data['builds']
latest = builds[-1]
print(f\"Build: {latest['build']}\")
print(f\"Download: {latest['downloads']['application']['name']}\")
"

2.3.2 一键下载脚本

#!/bin/bash
# download-paper.sh - 下载最新版 PaperMC

MINECRAFT_VERSION="${1:-1.21.4}"
OUTPUT_DIR="${2:-.}"

echo "正在获取 PaperMC ${MINECRAFT_VERSION} 最新构建信息..."

# 获取最新构建号
BUILD=$(curl -s "https://api.papermc.io/v2/projects/paper/versions/${MINECRAFT_VERSION}/builds" \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['builds'][-1]['build'])")

if [ -z "$BUILD" ]; then
    echo "错误：无法获取构建信息，请检查版本号是否正确"
    exit 1
fi

# 下载
JAR_NAME="paper-${MINECRAFT_VERSION}-${BUILD}.jar"
DOWNLOAD_URL="https://api.papermc.io/v2/projects/paper/versions/${MINECRAFT_VERSION}/builds/${BUILD}/downloads/${JAR_NAME}"

echo "正在下载 PaperMC ${MINECRAFT_VERSION} build ${BUILD}..."
curl -o "${OUTPUT_DIR}/paper.jar" "$DOWNLOAD_URL"

echo "下载完成：${OUTPUT_DIR}/paper.jar"
echo "文件大小：$(du -h ${OUTPUT_DIR}/paper.jar | cut -f1)"

# 使用方式
chmod +x download-paper.sh
./download-paper.sh 1.21.4 /opt/minecraft/paper

2.3.3 手动下载

如果命令行不方便，也可以直接访问浏览器下载：

打开 https://papermc.io/downloads/paper
选择 Minecraft 版本
点击最新的 Build 号旁边的 Download 按钮
将下载的 JAR 重命名为 paper.jar
移动到服务器目录

2.4 首次启动

2.4.1 最小启动命令

cd /opt/minecraft/paper

# 最基本的启动命令
java -jar paper.jar

首次启动会立即退出，因为需要先同意 EULA。输出中会看到：

[00:00:00] [ServerMain/INFO]: You need to agree to the EULA in order to run the server.
           Go to eula.txt for more info.

2.4.2 签署 EULA

# 编辑 eula.txt
cat eula.txt

# 将 eula=false 改为 eula=true
sed -i 's/eula=false/eula=true/' eula.txt

# eula.txt
# 请阅读 https://aka.ms/MinecraftEULA 后再同意
eula=true

注意：签署 EULA 意味着你同意 Minecraft 最终用户许可协议。核心要求是不得将 Minecraft 服务器作为付费盈利工具（如付费进入、付费获得游戏优势等）。装饰性物品的捐赠是被允许的。

2.4.3 正式启动命令（带优化参数）

java \
  -Xms4G \
  -Xmx4G \
  -XX:+UseG1GC \
  -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 \
  -XX:+UnlockExperimentalVMOptions \
  -XX:+DisableExplicitGC \
  -XX:+AlwaysPreTouch \
  -XX:G1NewSizePercent=30 \
  -XX:G1MaxNewSizePercent=40 \
  -XX:G1HeapRegionSize=8M \
  -XX:G1ReservePercent=20 \
  -XX:G1HeapWastePercent=5 \
  -XX:G1MixedGCCountTarget=4 \
  -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:G1MixedGCLiveThresholdPercent=90 \
  -XX:G1RSetUpdatingPauseTimePercent=5 \
  -XX:SurvivorRatio=32 \
  -XX:+PerfDisableSharedMem \
  -XX:MaxTenuringThreshold=1 \
  -Dusing.aikars.flags=https://mcflags.emc.gs \
  -Daikars.new.flags=true \
  -jar paper.jar \
  --nogui

说明：以上是 Aikar 推荐的 JVM 参数，这是 Minecraft 社区公认的最优 GC 配置。参数解释见第 07 章。

2.4.4 使用启动脚本

创建一个可复用的启动脚本：

#!/bin/bash
# start.sh - PaperMC 启动脚本

# ============ 配置 ============
SERVER_DIR="/opt/minecraft/paper"
JAR_NAME="paper.jar"
MEMORY="4G"          # 分配内存，建议不超过物理内存的 80%
GUI="--nogui"         # 是否启用 GUI（服务器通常关闭）

# ============ 启动 ============
cd "$SERVER_DIR" || exit 1

echo "=============================="
echo "  PaperMC 服务器启动中..."
echo "  内存分配: ${MEMORY}"
echo "  时间: $(date '+%Y-%m-%d %H:%M:%S')"
echo "=============================="

java \
  -Xms${MEMORY} \
  -Xmx${MEMORY} \
  -XX:+UseG1GC \
  -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 \
  -XX:+UnlockExperimentalVMOptions \
  -XX:+DisableExplicitGC \
  -XX:+AlwaysPreTouch \
  -XX:G1NewSizePercent=30 \
  -XX:G1MaxNewSizePercent=40 \
  -XX:G1HeapRegionSize=8M \
  -XX:G1ReservePercent=20 \
  -XX:G1HeapWastePercent=5 \
  -XX:G1MixedGCCountTarget=4 \
  -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:G1MixedGCLiveThresholdPercent=90 \
  -XX:G1RSetUpdatingPauseTimePercent=5 \
  -XX:SurvivorRatio=32 \
  -XX:+PerfDisableSharedMem \
  -XX:MaxTenuringThreshold=1 \
  -Dusing.aikars.flags=https://mcflags.emc.gs \
  -Daikars.new.flags=true \
  -jar ${JAR_NAME} \
  ${GUI}

chmod +x start.sh
./start.sh

2.5 使用 Screen / Tmux 管理

直接在终端运行服务器会在断开 SSH 时终止。需要使用终端复用器。

2.5.1 使用 Screen

# 安装 Screen
sudo apt install -y screen    # Debian/Ubuntu
sudo yum install -y screen    # CentOS/RHEL

# 创建会话
screen -S minecraft

# 在 Screen 会话中启动服务器
cd /opt/minecraft/paper
./start.sh

# 分离会话（不关闭服务器）
# 按 Ctrl+A，然后按 D

# 重新连接会话
screen -r minecraft

# 查看所有会话
screen -ls

2.5.2 使用 Tmux

# 安装 Tmux
sudo apt install -y tmux

# 创建会话
tmux new -s minecraft

# 在会话中启动服务器
cd /opt/minecraft/paper
./start.sh

# 分离会话：按 Ctrl+B，然后按 D

# 重新连接
tmux attach -t minecraft

# 查看所有会话
tmux ls

2.6 首次启动后的配置

服务器首次成功启动后会生成大量文件。以下是首次启动后应立即修改的内容：

2.6.1 server.properties 关键项

# 服务器端口
server-port=25565

# 最大玩家数
max-players=20

# 白名单（建议开启）
white-list=false

# 启用命令方块（按需）
enable-command-block=false

# 视距（影响性能，后续调优重点）
view-distance=10

# 模拟距离（影响性能）
simulation-distance=10

# 服务器简介
motd=\u00a7a欢迎来到我的 PaperMC 服务器！

2.6.2 立即执行的控制台命令

# 设置管理员（替换为你的游戏 ID）
op YourPlayerName

# 关闭服务器
stop

2.7 Systemd 服务配置（Linux 生产环境）

让服务器随系统启动并自动重启：

# /etc/systemd/system/minecraft.service

[Unit]
Description=Minecraft PaperMC Server
After=network.target
Wants=network-online.target

[Service]
User=minecraft
Group=minecraft
WorkingDirectory=/opt/minecraft/paper
Type=simple

# 启动命令
ExecStart=/usr/bin/java \
    -Xms4G -Xmx4G \
    -XX:+UseG1GC \
    -XX:+ParallelRefProcEnabled \
    -XX:MaxGCPauseMillis=200 \
    -XX:+UnlockExperimentalVMOptions \
    -XX:+DisableExplicitGC \
    -XX:+AlwaysPreTouch \
    -XX:G1NewSizePercent=30 \
    -XX:G1MaxNewSizePercent=40 \
    -XX:G1HeapRegionSize=8M \
    -XX:G1ReservePercent=20 \
    -XX:G1HeapWastePercent=5 \
    -XX:G1MixedGCCountTarget=4 \
    -XX:InitiatingHeapOccupancyPercent=15 \
    -XX:G1MixedGCLiveThresholdPercent=90 \
    -XX:G1RSetUpdatingPauseTimePercent=5 \
    -XX:SurvivorRatio=32 \
    -XX:+PerfDisableSharedMem \
    -XX:MaxTenuringThreshold=1 \
    -Dusing.aikars.flags=https://mcflags.emc.gs \
    -Daikars.new.flags=true \
    -jar paper.jar --nogui

ExecStop=/usr/bin/screen -p 0 -S minecraft -X eval 'stuff "stop"\015'

# 自动重启
Restart=on-failure
RestartSec=10

# 安全加固
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/opt/minecraft/paper

[Install]
WantedBy=multi-user.target

# 创建专用用户
sudo useradd -r -m -d /opt/minecraft -s /bin/bash minecraft
sudo chown -R minecraft:minecraft /opt/minecraft/paper

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable minecraft
sudo systemctl start minecraft

# 查看状态
sudo systemctl status minecraft

# 查看日志
sudo journalctl -u minecraft -f

2.8 常见问题

Q1：启动报错 `UnsupportedClassVersionError`

java.lang.UnsupportedClassVersionError: org/bukkit/craftbukkit/Main
has been compiled by a more recent version of the Java Runtime

原因：Java 版本过低。解决：安装 Java 21，确认 java -version 输出正确。

Q2：启动报错 `OutOfMemoryError`

java.lang.OutOfMemoryError: Java heap space

原因：分配的内存不足。解决：增大 -Xmx 参数值，但不超过物理内存的 80%。

Q3：端口被占用

[ServerThread/WARN]: **** FAILED TO BIND TO PORT!
java.net.BindException: Address already in use

解决：

# 查找占用端口的进程
sudo lsof -i :25565
sudo ss -tlnp | grep 25565

# 终止占用进程或修改 server.properties 中的端口

Q4：防火墙阻止连接

# Ubuntu/Debian (UFW)
sudo ufw allow 25565/tcp

# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=25565/tcp
sudo firewall-cmd --reload

# iptables
sudo iptables -A INPUT -p tcp --dport 25565 -j ACCEPT

2.9 本章小结

步骤	操作	关键命令
1	安装 Java 21	`apt install openjdk-21-jdk`
2	创建服务器目录	`mkdir -p /opt/minecraft/paper`
3	下载 PaperMC	`curl -o paper.jar <url>`
4	首次启动	`java -jar paper.jar`
5	签署 EULA	`eula.txt` 中设置 `eula=true`
6	配置启动脚本	Aikar’s Flags
7	设置 Screen/Tmux	`screen -S minecraft`
8	配置 Systemd	`minecraft.service`