在itzg/docker-minecraft-server中部署本地CurseForge模组包的完整指南

背景介绍

itzg/docker-minecraft-server是一个广受欢迎的Minecraft服务器Docker镜像，它支持多种服务器类型和模组平台。其中，对CurseForge模组平台的支持尤为强大，但许多用户在尝试部署本地自定义模组包时遇到了困难。本文将详细介绍如何在Docker环境中正确配置本地CurseForge模组包。

准备工作

在开始之前，您需要准备以下内容：

1. 从CurseForge客户端导出的模组包ZIP文件
2. 确保已安装Docker和Docker Compose
3. 获取有效的CurseForge API密钥

常见错误分析

许多用户在尝试部署时会遇到以下两类错误：

1. "No mods found with slug"错误：这通常是因为错误地使用了CF_SERVER_MOD而不是CF_MODPACK_ZIP来指定本地模组包。

2. "Failed to setup API caching"错误：这是由于容器无法直接访问主机文件系统中的路径导致的。

正确配置方法

基础配置

以下是部署本地CurseForge模组包的正确Docker Compose配置示例：

services:
  mc:
    image: itzg/minecraft-server
    container_name: my-minecraft-server
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      MODPACK_PLATFORM: AUTO_CURSEFORGE
      CF_MODPACK_ZIP: /modpacks/my-modpack.zip
      CF_SLUG: "custom-pack"
      CF_API_KEY: "your-api-key-here"
      MEMORY: 4G
    volumes:
      - ./data:/data
      - ./modpacks:/modpacks:ro

关键配置说明

1. MODPACK_PLATFORM：必须设置为AUTO_CURSEFORGE以启用CurseForge模组平台支持。

2. CF_MODPACK_ZIP：指定容器内模组包ZIP文件的路径，注意这是容器内的路径而非主机路径。

3. volumes配置：必须将模组包所在目录挂载到容器中，上例中"./modpacks"主机目录被挂载为容器的"/modpacks"。

4. CF_SLUG：对于本地模组包，可以设置为任意标识符，但必须提供。

高级配置选项

1. 使用manifest.json：如果您想单独提供manifest文件而非整个ZIP包，可以使用CF_MODPACK_MANIFEST参数：

environment:
  CF_MODPACK_MANIFEST: /manifests/manifest.json
volumes:
  - ./manifests:/manifests:ro

2. 内存配置：根据模组包复杂度调整MEMORY参数，大型模组包建议至少4G内存。

最佳实践建议

1. 始终使用从CurseForge客户端导出的原始ZIP文件，不要手动打包。

2. 确保挂载的目录权限正确，容器以UID 1000运行。

3. 对于生产环境，建议将模组包和相关文件放在专用目录中管理。

4. 调试时可以先使用较小内存配置，确认运行正常后再增加内存分配。

总结

通过正确配置Docker Compose文件，特别是注意文件路径的挂载和参数的使用，可以顺利地在itzg/docker-minecraft-server中部署本地CurseForge模组包。理解容器与主机文件系统的交互方式是成功部署的关键。希望本指南能帮助您顺利搭建自己的Minecraft模组服务器。