oscarhult/papermc

PaperMC Docker镜像文档

1. 镜像概述与主要用途

该镜像基于Alpine 3操作系统，集成Java 21运行时环境与PaperMC服务端，压缩后体积约99MB。主要用途为快速部署高性能Minecraft服务器，适用于需要轻量级、易维护的Minecraft服务端场景。PaperMC是Minecraft: Java Edition的优化服务端实现，具备低延迟、高并发支持特性。

2. 核心功能与特性

• 轻量级基础：基于Alpine 3构建，压缩后体积仅约99MB，资源占用低
• Java环境集成：内置Java 21运行时，无需额外配置Java环境
• 高性能服务端：包含PaperMC，针对Minecraft服务端进行优化，支持高玩家并发
• 数据持久化：支持卷挂载，确保服务器数据（世界存档、配置文件等）持久化存储

3. 使用场景与适用范围

• 个人或小型社区的Minecraft游戏服务器快速部署
• 对服务器资源（磁盘空间、内存）有限制的场景
• 需要频繁迁移或重建服务器实例的环境
• 开发/测试Minecraft插件或服务器配置的沙箱环境

4. 使用方法

4.1 部署容器（docker run）

通过以下命令启动PaperMC容器，默认映射Minecraft标准端口并挂载数据卷：

bash
docker run \
  --interactive \  # 保持标准输入打开，支持控制台交互
  --detach \       # 后台运行容器
  --pull always \  # 总是拉取最新版本镜像
  --name papermc \ # 容器名称设为papermc
  --hostname papermc \ # 容器主机名设为papermc
  --restart unless-stopped \ # 容器退出时除非手动停止，否则自动重启
  --publish 25565:25565/tcp \ # 映射TCP端口（Minecraft客户端连接）
  --publish 25565:25565/udp \ # 映射UDP端口（支持部分网络功能）
  --env JAVA_TOOL_OPTIONS="-Xms8G -Xmx8G" \ # JVM参数（初始/最大堆内存各8G，可调整）
  --volume papermc:/papermc \ # 挂载卷papermc到容器内/papermc目录（数据持久化）
  oscarhult/papermc:latest   # 镜像名称（oscarhult/papermc，latest标签）

4.2 连接容器控制台（docker attach）

通过docker attach连接容器控制台，执行服务器命令（如/op <玩家名>、/stop等）：

bash
docker attach \
  --sig-proxy=false \  # 禁用信号代理（避免退出attach时终止容器）
  papermc  # 目标容器名称（需与部署时--name一致）

说明：退出控制台可使用Ctrl+P+Q组合键（不终止容器），若使用Ctrl+C需确保--sig-proxy=false已设置，否则可能终止服务器进程。

4.3 数据备份

通过以下命令备份容器数据卷（包含世界存档、配置文件等）到本地目录：

bash
docker run \
  --rm \  # 备份完成后自动删除临时容器
  --volumes-from papermc \  # 挂载papermc容器的数据卷
  --volume $(pwd):/backup \ # 将当前目录挂载到临时容器的/backup目录
  alpine:latest \  # 使用alpine镜像执行备份命令
  tar cvf /backup/papermc.tar /papermc  # 将/papermc目录打包为/papermc.tar并保存到/backup（即本地当前目录）

说明：备份文件将保存至本地当前目录，命名为papermc.tar。

5. 配置说明

5.1 环境变量

• JAVA_TOOL_OPTIONS：JVM运行参数，用于调整内存分配、垃圾回收策略等。示例中-Xms8G -Xmx8G表示初始堆内存8G、最大堆内存8G，可根据服务器硬件配置调整（如-Xms2G -Xmx4G）。

5.2 数据卷

• /papermc：容器内核心数据目录，包含Minecraft世界存档（world/）、服务端配置（server.properties）、插件（plugins/）等。通过--volume papermc:/papermc挂载命名卷后，数据将持久化存储，即使容器删除也不会丢失。

5.3 端口映射

• 25565/tcp：Minecraft客户端默认连接端口，需映射至宿主机端口以允许外部访问（若宿主机端口冲突，可修改宿主机端口部分，如25566:25565/tcp）。
• 25565/udp：支持UDP协议的功能（如部分语音聊天插件），建议同时映射以确保完整功能。

6. Dockerfile来源

• 镜像构建相关：https://github.com/oscarhult/papermc
• JRE 21基础镜像：https://github.com/oscarhult/jre21