spritsail/minecraft 镜像文档

1. 镜像概述和主要用途

spritsail/minecraft 是一个轻量级 Docker 镜像，旨在简化 Minecraft: Java Edition 服务器的部署与管理。该镜像基于 Alpine Linux 构建，体积小巧且资源占用低，支持灵活配置服务器版本、玩家上限、游戏模式等核心参数，适用于个人、小型社区或开发测试场景快速搭建 Minecraft 服务器。

2. 核心功能和特性

2.1 核心功能

• 版本灵活：支持指定任意 Minecraft: Java Edition 服务器版本（如 1.20.1、1.19.4 等），自动从 Mojang 官方源下载对应服务端 JAR。
• 配置简化：通过环境变量或配置文件自定义服务器参数（如最大玩家数、难度、游戏模式等）。
• 数据持久化：支持挂载卷保存服务器配置、世界数据、插件及日志，确保数据不丢失。
• 合规启动：强制要求通过环境变量接受 Minecraft EULA（最终用户许可协议），避免手动操作。

2.2 特性

• 轻量级：基于 Alpine Linux，镜像体积小，启动速度快。
• 多架构支持：兼容 amd64、arm64 等主流架构。
• 自动依赖管理：内置 Java 运行时环境（JRE），无需额外安装。
• 日志集成：服务器日志默认输出至标准输出流，支持 Docker 日志驱动收集。

3. 使用场景和适用范围

3.1 适用场景

• 个人玩家搭建私有服务器，供好友联机。
• 小型社区（10-20 人）部署低延迟游戏服务器。
• 开发测试环境验证插件兼容性或新版本特性。
• 教学场景演示 Minecraft 服务器配置与管理。

3.2 不适用场景

• 大型社区服务器（建议搭配负载均衡或专用服务端优化工具）。
• 需要复杂插件生态（如 Mod 服）的场景（需额外配置 Forge/Fabric 环境）。

4. 使用方法和配置说明

4.1 基础环境要求

• Docker 19.03+ 或 Docker Compose 2.0+。
• 宿主机至少 2GB 内存（推荐 4GB+，视玩家数量调整）。
• 网络需开放 Minecraft 默认端口（25565/TCP）。

4.2 快速启动（docker run）

4.2.1 首次启动（接受 EULA）

Minecraft 服务器启动前需接受 Mojang EULA（[***]

docker run -d \
  --name minecraft-server \
  -p 25565:25565 \  # 端口映射（宿主机端口:容器端口）
  -e EULA=true \     # 必须接受 EULA 才能启动（强制）
  -e MINECRAFT_VERSION=1.20.1 \  # 指定服务器版本
  -e MAX_PLAYERS=10 \  # 最大玩家数
  -e MOTD="My Minecraft Server" \  # 服务器列表显示的消息
  -v ./minecraft-data:/data \  # 挂载数据卷（持久化配置、世界、日志等）
  spritsail/minecraft

4.2.2 常用环境变量

4.3 Docker Compose 配置

推荐使用 docker-compose.yml 管理服务，便于持久化配置和快速启停：

version: '3.8'
services:
  minecraft:
    image: spritsail/minecraft
    container_name: minecraft-server
    restart: unless-stopped  # 容器退出时自动重启（除非手动停止）
    ports:
      - "25565:25565"
    environment:
      - EULA=true
      - MINECRAFT_VERSION=1.20.1
      - MAX_PLAYERS=15
      - MOTD=§bMy §aMinecraft §cServer  # 带颜色的 MOTD
      - DIFFICULTY=normal
      - GAMEMODE=survival
    volumes:
      - ./minecraft-data:/data  # 数据卷挂载（当前目录下的 minecraft-data 目录）
    logging:
      driver: "json-file"
      options:
        max-size: "10m"  # 日志文件最大 10MB
        max-file: "3"    # 最多保留 3 个日志文件

启动命令：

docker-compose up -d  # 后台启动服务
docker-compose logs -f  # 查看实时日志
docker-compose down  # 停止并移除容器（数据卷保留）

4.4 数据持久化

容器内所有服务器数据（配置、世界、插件、日志等）均存储于 /data 目录，需通过卷挂载持久化至宿主机，避免容器重建后数据丢失。挂载路径示例：

• 宿主机路径：./minecraft-data（当前目录下）
• 容器路径：/data（固定，不可修改）

/data 目录结构说明：

/data
├── server.properties  # 核心配置文件（自动生成，可手动修改）
├── world/             # 世界数据（地图、建筑等）
├── logs/              # 服务器日志
├── plugins/           # 插件目录（需手动放入插件 JAR）
└── eula.txt           # EULA 接受记录（由环境变量 EULA=true 生成）

4.5 高级配置：修改 server.properties

server.properties 是 Minecraft 服务器核心配置文件，位于挂载卷的 /data/server.properties。镜像启动时会根据环境变量自动生成该文件，如需自定义更多参数（如种子、视图距离），可直接编辑此文件，重启容器后生效。

常用配置项（完整参数见 Minecraft Wiki）：

level-seed=123456  # 世界种子（如不指定则随机）
view-distance=10   # 视图距离（区块数，默认 10）
max-build-height=256  # 最大建造高度
online-mode=true   # 是否验证正版账号（默认 true，离线模式设为 false）

5. 使用场景和适用范围示例

5.1 个人服务器（1-5 人）

• 配置：2GB 内存，MAX_PLAYERS=5，DIFFICULTY=easy，关闭 PVP（PVP=false）。
• 部署：通过 docker-compose 启动，挂载本地目录持久化世界数据，定期备份 /data/world 目录。

5.2 小型社区服务器（10-20 人）

• 配置：4GB 内存，MAX_PLAYERS=20，启用白名单（WHITELIST=true），安装基础插件（如 EssentialsX）。
• 优化：通过 server.properties 调整 view-distance=8 降低资源占用，限制 entity-activation-range 减少实体加载压力。

6. 常见问题

6.1 如何更新服务器版本？

1. 停止容器：docker-compose down
2. 修改 docker-compose.yml 中 MINECRAFT_VERSION 为目标版本（如 1.20.2）
3. 重启容器：docker-compose up -d
   （镜像会自动下载新版本服务端 JAR，保留原世界数据和配置）

6.2 如何备份世界数据？

直接打包宿主机挂载的 /minecraft-data/world 目录：

tar -czf minecraft-world-backup-$(date +%F).tar.gz ./minecraft-data/world

6.3 客户端无法连接服务器？

• 检查宿主机防火墙是否开放 25565 端口。
• 确认端口映射正确（-p 宿主机端口:25565），客户端连接时使用「宿主机 IP:宿主机端口」。
• 查看容器日志：docker logs minecraft-server，排查启动错误（如 EULA 未接受、版本下载失败）。

7. 注意事项

• EULA 合规：必须设置 EULA=true，表示接受 Mojang EULA（详见 Mojang 官方协议）。
• 资源需求：服务器内存建议不低于 2GB，玩家数量增加时需相应提升内存（每增加 5 名玩家建议增加 1GB 内存）。
• 插件支持：需将插件 JAR 手动放入宿主机挂载的 /minecraft-data/plugins 目录，重启容器生效（仅支持 Spigot/Paper 等兼容插件，需对应服务器版本）。