📦 Pumpkin Minecraft 服务端详细部署教程

Pumpkin 是一个使用 Rust 语言从头构建的 Minecraft 服务端，专注于高性能、高效率和可定制性。它支持最新的 Java 版 Minecraft 协议，并同时兼容 Bedrock 版（开发中）。请注意：Pumpkin 目前处于积极开发中的预发布状态，尚未准备好用于正式生产环境，更适合测试、实验和小型私人服务器。

⚙️ 部署前准备

  1. 基础环境：
    • 部署服务端：一台具备公网 IP 的服务器（或本地电脑），操作系统不限（Windows/Linux/macOS 均可）。
    • 运行客户端：一台安装有 Minecraft Java 版 的电脑，版本需与服务端支持的版本一致（Pumpkin 通常追踪最新版本）。
  2. 网络要求：确保服务端的防火墙或安全组放行了默认端口 25565（或你自定义的端口）。
  3. Rust 工具链（仅源码编译需要）：若选择从源码编译，需安装 Rust。可访问 rustup.rs 安装。
  4. Docker 环境（仅容器部署需要）：若选择 Docker 部署，需提前安装 Docker。

🚀 部署方式一：从预编译二进制文件运行（最简单）

这是最快速的入门方式，适合不想安装 Rust 编译环境的用户。

  1. 下载文件：访问 Pumpkin 项目的 预发布下载页面，为你的操作系统（Windows、Linux、macOS）下载最新的预编译二进制文件（例如 pumpkin-server 或 pumpkin-server.exe）。
  2. 准备世界文件夹（可选）：如果你想使用现有的 Minecraft 世界，将其文件夹复制到与服务器二进制文件相同的目录下，并重命名为 world。如果不提供，Pumpkin 启动时会自动生成一个全新世界。
  3. 运行服务器：在终端或命令行中，导航到二进制文件所在目录，赋予执行权限（Linux/macOS 需 chmod +x），然后直接运行该文件。
  4. 连接游戏：在 Minecraft Java 版客户端中，添加服务器，地址填写 你的服务器IP:25565（本地游玩可填 localhost:25565）。

🦀 部署方式二：从源码编译运行（推荐开发者/DIY 用户）

此方法可从 GitHub 获取最新代码并编译。

  1. 克隆仓库：

    1
    2
    git clone https://github.com/Pumpkin-MC/Pumpkin.git
    cd Pumpkin

  2. （可选）放置世界文件：如有需要，将你的世界文件夹放入 Pumpkin/ 目录下并命名为 world。

  3. 编译并运行：

    1
    cargo run --release

    注意：首次编译因优化和依赖下载，可能需要较长时间。

  4. （可选）极致性能优化：若想最大化利用 CPU 性能，可使用以下命令（会编译针对你 CPU 的特定指令集）：

    1
    RUSTFLAGS='-C target-cpu=native' cargo run --release

  5. 连接游戏：方法同方式一。

🐳 部署方式三：Docker 部署（适合容器化环境）

重要提示：Pumpkin 的 Docker 支持目前仍处于实验性阶段。

  1. 拉取并运行镜像：在终端中执行以下命令，根据需要替换参数：

    1
    2
    3
    4
    docker run --rm \
        -p <你指定的端口>:25565 \
        -v <本地数据存储路径>:/pumpkin \
        -it ghcr.io/pumpkin-mc/pumpkin:master
    • <你指定的端口>：例如 25565，这是游戏连接的端口。
    • <本地数据存储路径>：例如 ./data，用于持久化保存服务器配置和世界数据，防止容器删除后丢失。

  2. 示例命令：在 25565 端口运行，并将数据保存在当前目录下的 data 文件夹中：

    1
    docker run --rm -p 25565:25565 -v ./data:/pumpkin -it ghcr.io/pumpkin-mc/pumpkin:master

  3. 连接游戏：方法同方式一。

☁️ 部署方式四：一键云部署（适合不想管理服务器）

对于希望快速体验、不想自己搭建环境的用户，可以使用 Railway 平台的一键部署模板。

  1. 访问 Railway 上 Pumpkin 的 部署模板页面。
  2. 点击 “Deploy Now” 按钮，并授权 Railway 连接你的 GitHub 账号。
  3. 平台会自动开始部署。完成后，Railway 会为你生成一个可直接连接的服务器地址。
  4. 在 Minecraft 客户端中使用该地址即可加入游戏。此方式自动处理了服务器配置和重启，非常便捷。

🔧 核心配置与问题排查

  • 配置文件：Pumpkin 使用 TOML 格式的配置文件（通常为 config.toml），位于运行目录下，可修改端口、世界设置等。
  • 世界文件夹要求：一个有效的 Minecraft 世界文件夹必须包含 region/ 子目录（存储区块数据）和 level.dat 文件。如果启动时遇到 “World region folder does not exist” 错误，请检查你的 world 文件夹结构是否正确。
  • 本地连接问题：如果在服务器本机通过 localhost 无法连接，可尝试在客户端添加服务器时，地址栏输入 localhost:25565。
  • 查看详细日志：若启动失败，可通过 RUST_BACKTRACE=1 环境变量运行，以获取更详细的错误堆栈信息，便于排查。

📚 扩展与社区

  • 插件开发：Pumpkin 支持使用 Rust 编写插件。插件作为动态库（cdylib）加载，开发者需在 Cargo.toml 中引用 pumpkin、pumpkin-util 等 crate 进行开发。
  • 测试服务器：社区维护了一个公开测试服务器，地址为 pumpkin.kralverde.dev，运行最新开发版代码，可供参考其表现。
  • 官方文档与社区：更详细的技术文档可访问 Pumpkin 官方文档。如有问题或想参与开发，可加入其 Discord 服务器 进行交流。