lexfrei/papermc Docker 镜像 - 轩辕镜像

PaperMC Docker镜像

![Build Paper Docker Images]([] ![Docker Pulls]([] ![License]([] ![Docker Image Size]([] ![Wiki]([***]

一个轻量级、优化的Docker镜像，用于运行PaperMC Minecraft服务器。

关于PaperMC

重要提示：这是PaperMC的第三方Docker镜像和Helm图表打包。PaperMC本身由PaperMC团队开发和维护，而非本仓库维护者。

• 上游项目：PaperMC
• 官方文档：docs.papermc.io
• 官方***：***.gg/papermc

有关PaperMC服务器本身（游戏玩法、插件、服务器配置等）的问题、故障或支持，请参考上述官方PaperMC资源。

本仓库仅提供：

• PaperMC的Docker容器化
• 用于部署的Kubernetes Helm图表
• 镜像构建的CI/CD自动化

有关Docker镜像或Helm图表（容器构建、部署、图表配置）的问题，请使用本仓库的问题跟踪器。

兼容性

本服务器兼容：

• 仅Minecraft Java版客户端（不支持基岩版）
• PaperMC插件和Spigot/Bukkit插件
• 标准Minecraft协议和工具

特性

• 基于Red Hat UBI9 OpenJDK 25运行时，带有run-java.sh入口点
• 每日自动更新最新Paper构建
• 使用Aikar's flags优化
• 自动内存管理，带有-XX:MaxRAMPercentage=80%
• 简单的基于套接字的健康检查
• 插件安装支持
• 多架构支持（amd64、arm64）
• 最小化镜像大小，优化配置
• 注重安全性：以非root用户（UID 9001）运行

标签

• latest - 指向最新的Minecraft版本
• <version> - 特定的Minecraft版本（例如1.21.5），指向与其对应的构建标签相同的镜像
• <version>-<build> - 带有PaperMC构建号的特定Minecraft版本（例如1.21.5-20）

标签关系示例：

• latest → <最新版本> → <最新版本>-<构建号>（均指向相同镜像）
• <旧版本> → <旧版本>-<构建号>（均指向相同镜像）

要查找最新可用标签，请查看Docker Hub。

支持的版本

此镜像每天自动构建当前主要版本内的最新三个次要版本。例如：

• 最新次要版本（如1.21.5）
• 第二个最新次要版本（如1.21.4）
• 第三个最新次要版本（如1.21.3）

仅维护三个最新的次要版本，而非主要版本范围内的所有版本。随着新次要版本的发布，旧版本将从主动维护中移除。

版本更新策略

• 每日构建：容器每天使用每个支持的次要版本的最新PaperMC构建重新构建
• 次要版本跟踪：维护当前主要版本内的三个最新次要版本
• 构建跟踪：对于每个次要版本，跟踪并更新最新的PaperMC构建
• 标签同步：版本标签（如<version>）始终指向其对应的特定构建标签（如<version>-<build>）

建议：测试时使用latest标签，但生产环境中切换到特定的版本-构建标签（如<version>-<build>）以确保稳定性。

使用方法

Helm图表（Kubernetes）

提供了适用于Kubernetes部署的Helm图表，支持各种插件、入口和高级网络选项的轻松安装和配置。

安装

bash
# 从GitHub Container Registry安装图表
helm install papermc \
  oci://ghcr.io/lexfrei/papermc \
  --version 0.0.1

# 使用自定义值安装
helm install papermc \
  oci://ghcr.io/lexfrei/papermc \
  --version 0.0.1 \
  --values values.yaml

图表特性

• 灵活的服务配置，支持多个插件端口
• 可选的Ingress和HTTPRoute（Gateway API）支持
• 可配置的资源限制和请求
• 节点亲和性和容忍度
• 带有可自定义存储类的持久存储
• 存活和就绪探针

有关详细的图表文档和配置示例，请参见图表文档。

环境变量

注意：内存通过-XX:MaxRAMPercentage自动管理。JVM默认将使用容器内存的80%。使用Docker的--memory标志或Kubernetes资源限制设置容器内存限制。

内存配置

默认情况下，JVM使用容器内存的80%。要自定义：

bash
# 更改内存百分比（使用75%而非80%）
docker run -d \
  -e JAVA_MAX_MEM_RATIO=75 \
  --memory 4G \
  lexfrei/papermc:latest

# 禁用自动内存管理并设置显式堆大小
docker run -d \
  -e JAVA_MAX_MEM_RATIO=0 \
  -e JAVAFLAGS="-Xms2G -Xmx3G" \
  --memory 4G \
  lexfrei/papermc:latest

设置显式内存（-Xmx）时，为JVM元空间、本地内存和操作系统开销留出约1GB空间。

资源使用建议

PaperMC的内存需求因玩家数量、世界大小和已安装插件而异。以下是一些一般建议：

这些值是起点，应根据特定服务器性能进行调整。

Kubernetes用户：考虑使用垂直Pod自动扩缩器根据实际使用模式自动调整资源限制。这对于负载变化的Minecraft服务器特别有帮助。

Docker Run

bash
docker run -d \
  --name minecraft-server \
  -p 25565:25565/tcp \
  -p 25565:25565/udp \
  --memory 4G \
  -v /path/to/data:/data \
  lexfrei/papermc:latest

注意：对于生产环境，测试后将latest替换为特定的版本-构建标签。

Docker Compose

yaml
version: '3'

services:
  papermc:
    image: lexfrei/papermc:latest
    container_name: minecraft-server
    ports:
      - "25565:25565/tcp"
      - "25565:25565/udp"
    volumes:
      - ./data:/data
    deploy:
      resources:
        limits:
          memory: 4G
    restart: unless-stopped

注意：对于生产部署，使用特定的版本-构建标签而非latest。

Kubernetes

有关Kubernetes部署示例，请参见examples/kubernetes目录。

Kubernetes资源管理

在Kubernetes中运行时，考虑使用垂直Pod自动扩缩器（VPA）自动调整CPU和内存请求：

yaml
apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: minecraft-vpa
spec:
  targetRef:
    apiVersion: "apps/v1"
    kind: Deployment
    name: minecraft-server
  updatePolicy:
    updateMode: "Auto"
  resourcePolicy:
    containerPolicies:
      - containerName: "*"
        minAllowed:
          memory: "1Gi"
          cpu: "500m"
        maxAllowed:
          memory: "8Gi"
          cpu: "2"

VPA将随时间分析资源使用情况并自动调整资源请求，有助于优化资源分配，同时防止高峰期的OOM终止。

多服务器设置

使用此容器在同一主机上运行多个Minecraft服务器非常简单。每个容器需要自己的端口和数据卷：

yaml
version: '3'

services:
  survival:
    image: lexfrei/papermc:latest
    container_name: mc-survival
    ports:
      - "25565:25565/tcp"
      - "25565:25565/udp"
    volumes:
      - ./survival-data:/data
    deploy:
      resources:
        limits:
          memory: 4G
    restart: unless-stopped
    
  creative:
    image: lexfrei/papermc:latest
    container_name: mc-creative
    ports:
      - "25566:25565/tcp"  # 注意不同的主机端口
      - "25566:25565/udp"
    volumes:
      - ./creative-data:/data
    deploy:
      resources:
        limits:
          memory: 4G
    restart: unless-stopped

此示例在默认端口25565上运行生存服务器，在端口25566上运行创造服务器。

安装插件

要安装插件，只需将JAR文件放在/data/plugins目录中。PaperMC将自动从该目录加载插件。

为了更好地组织，还可以使用/data/plugins/update作为目录来存储PaperMC将自动更新的插件。

重要：容器以非root用户（UID 9001）运行。挂载卷时，确保/data目录具有适当的权限。

bash
docker run -d \
  --name minecraft-server \
  -p 25565:25565/tcp \
  -p 25565:25565/udp \
  --memory 4G \
  -v /path/to/data:/data \
  lexfrei/papermc:latest

通过此设置，可以通过将插件放在/path/to/data/plugins中来添加插件。

推荐插件

以下插件已知与此容器兼容良好：

• EssentialsX - 核心服务器命令和功能
• LuckPerms - 权限管理
• CoreProtect - 方块日志和回滚
• Dynmap - 实时基于Web的地图（默认暴露8123端口）
• WorldEdit - 游戏内世界编辑
• WorldGuard - 区域保护

这些仅是建议 - 所有标准Paper插件都应与此容器兼容。

服务器配置

server.properties

在数据目录中创建server.properties文件来自定义服务器设置。如果不存在该文件，首次运行时将创建默认文件。

示例配置：

properties
server-port=25565
motd=My PaperMC Server
max-players=20
view-distance=10
spawn-protection=0

使用RCON（可选）

如果需要使用RCON进行服务器管理，有两个选项：

1. 使用外部RCON客户端或边车容器
2. 使用您选择的RCON客户端连接到服务器

要启用RCON，将以下设置添加到server.properties：

properties
enable-rcon=true
rcon.password=your_secure_password
rcon.port=25575

运行容器时暴露RCON端口：

bash
docker run -d \
  --name minecraft-server \
  -p 25565:25565/tcp \
  -p 25565:25565/udp \
  -p 25575:25575/tcp \  # 暴露RCON端口
  --memory 4G \
  -v /path/to/data:/data \
  lexfrei/papermc:latest

日志配置

PaperMC服务器日志存储在/data/logs目录中，可以通过挂载此卷访问。您可以使用以下命令查看：

bash
# 查看容器日志
docker logs minecraft-server

# 从挂载的卷访问详细日志
cat /path/to/data/logs/latest.log

要自定义日志行为，可以在首次服务器运行后修改/data/log4j2.xml。例如，更改保留策略或日志级别。

DynMap配置

如果使用DynMap，请确保暴露8123端口：

bash
docker run -d \
  --name minecraft-server \
  -p 25565:25565/tcp \
  -p 25565:25565/udp \
  -p 8123:8123/tcp \  # 暴露DynMap Web界面
  --memory 4G \
  -v /path/to/data:/data \
  lexfrei/papermc:latest

容器生命周期

正确的关闭过程

Minecraft服务器需要正确的关闭过程来保存所有世界数据并防止损坏。此容器配置为正确处理Docker停止信号。

停止容器时：

bash
# 允许30秒进行干净关闭
docker stop --time=30 minecraft-server

这使服务器有时间在终止前正确保存所有区块和玩家数据。

启动时间

容器在其健康检查中包含合理的启动周期，以适应PaperMC初始化所需的时间。更大的世界和更多的插件将增加启动时间。

备份

建议定期备份服务器数据。最简单的方法是停止容器并复制数据目录：

bash
docker stop minecraft-server
cp -r /path/to/data /path/to/backup
docker start minecraft-server

对于自动备份，考虑使用专用备份解决方案，如Duplicati或Restic。

卷和持久性

此容器使用位于/data的单个卷，其中包含所有持久数据。以下是此卷中存储的内容：

挂载卷时，始终确保保留整个/data目录以维护所有服务器状态。

常见问题与故障排除

权限被拒绝错误

如果容器尝试访问挂载的卷时出现权限错误，可能是因为容器