# Minecraft模组服务器同步

**Repository Path**: swsk33/mc-server-sync

## Basic Information

- **Project Name**: Minecraft模组服务器同步
- **Description**: 基于Golang开发的轻量级Minecraft Java版模组服务器同步工具，支持同步模组服务器的模组等相关文件到玩家客户端，避免服务器模组变化时，玩家需要手动添加/移除模组。
- **Primary Language**: Go
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-01-14
- **Last Updated**: 2025-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Minecraft模组服务器同步

## 1，介绍

Minecraft是一款沙盒游戏，凭借其自由度高、内容丰富的特性，受到了许多玩家的青睐。搭建Minecraft服务器能够让多名玩家远程联机游玩游戏，比起单人模式增加了更多的乐趣。此外，Minecraft还支持添加模组，以丰富其游戏内容，搭建模组服务器（例如Forge、Fabric等等）可以使得多个与服务器有着同样模组玩家共同联机。

对于模组服务器的管理者来说，在需要增加/删除服务器模组时，**通常还需要通知所有玩家也在自己的游戏中删除或者增加模组，保证与服务器模组列表一致才能正常加入游戏**，对于经常需要改变模组的服务器管理者来说，模组列表的一致性无论是对服务器管理员还是玩家都造成了一定的困扰。

鉴于此，基于Golang和Gin框架，开发了一款轻量级的Minecraft Java版模组服务器同步工具，支持同步模组服务器的模组等相关文件到玩家客户端，避免服务器模组变化时，玩家需要手动添加/移除模组。该软件完全使用Golang开发，无任何依赖，内存占用低。

该模组同步工具仅支持Minecraft国际版的Java版本，不支持基岩版或者网易版，该文档中提到的全部Minecraft都指的是国际Java版。

## 2，程序工作流程

了解该程序的工作流程，有利于服务器管理者和玩家更好地使用该同步工具。

该同步工具是典型的C/S架构（客户端/服务端架构），由两个部分构成：

- **同步服务端**：同步服务端通常和Minecraft模组服务器共同部署在一起，其本质是一个简单的Web服务器，它将从模组服务器的`mods`文件夹下读取模组文件列表，同步客户端能够对服务端发起请求查询服务端的模组列表，进而执行模组的下载同步工作
- **同步客户端**：同步客户端通常和玩家的Minecraft游戏客户端放在一起，它将读取游戏模组目录（通常是`.minecraft/mods`或者`.minecraft/versions/xxx/mods`）以获取玩家游戏模组列表，在游戏每次启动之前，可以由玩家运行一次同步客户端，也可以配置让启动器自动运行同步客户端，客户端运行时会自动向同步服务端发起请求查询服务端模组列表，并与本地模组列表进行比对，若本地缺少某些模组，则会从服务端下载，反之本地多出的模组会被移除

大致的组成架构和同步流程如下：

![](https://swsk33-note.oss-cn-shanghai.aliyuncs.com/202521163234.png)

客户端从服务端同步的详细流程UML活动图如下：

![](https://swsk33-note.oss-cn-shanghai.aliyuncs.com/202521163217.png)

服务端和客户端都是一个单独的可执行文件，下面将会分别介绍两者的配置方法。

## 3，前置基础知识

在使用该同步工具之前，如果你对电脑、服务器的相关概念以及操作不太熟悉，那么建议先阅读一下这个部分，否则可能会对后续的使用造成困扰。如果你是电脑高手，或者经常折腾服务器，那么就可以跳过阅读这个部分。

### (1) Minecraft模组位置

我们可以先了解一下Minecraft游戏目录结构，通常如下：

```bash
.
├── .minecraft               # 游戏文件目录
│   ├── assets                 # 游戏资源文件
│   ├── launcher_profiles.json # 启动配置
│   ├── libraries              # 游戏运行库
│   └── versions               # 如果存在多个游戏版本，则不同版本的游戏数据会存放在该文件夹中
│       └── 1.21.4-Fabric        # 其中一个版本游戏数据
├── HMCL-3.6.11.exe          # 启动器
└── hmcl.json                # 启动器配置
```

在游戏的安装（解压缩）目录中，通常启动器（例如`HMCL`）程序和游戏文件夹`.minecraft`位于同级目录下，而对于**官方正版启动器**来说，游戏文件夹`.minecraft`通常位于`C:\Users\你的用户名\AppData\Roaming`目录下，总的来说，`.minecraft`是存放所有游戏必要运行文件和数据的文件夹，当然也包括模组，下面我们将`.minecraft`目录的**所在目录**表示为`${install_dir}`。

对于模组的存放位置，通常分为两种情况：

- 默认情况下，模组文件都位于`${install_dir}/.minecraft/mods`目录下
- 若开启了**版本隔离**，则模组文件位于`${install_dir}/.minecraft/versions/你的版本号/mods`目录下

在默认情况下，一个游戏目录通常只会包含一个版本的Minecraft游戏，此时所有游戏数据包括存档、模组都位于`${install_dir}/.minecraft`目录下。

不过，一个游戏目录也可以包含多个版本的Minecraft，玩家可以在启动时选择不同的版本的游戏启动，要实现此效果则需要开启**版本隔离**功能，该功能绝大多数第三方启动器都支持，当开启了版本隔离后，每个版本的游戏文件、数据、模组等都会被组织存放在`${install_dir}/.minecraft/versions`目录下的一个单独的文件夹中，也就是说，我们可以查看`${install_dir}/.minecraft/versions`目录下的文件夹来判断这个游戏目录包含哪些版本。

以HMCL启动器为例，进入设置-全局游戏设置-版本隔离-勾选各版本独立，就开启了版本隔离功能：

![image-20250123195644102](https://swsk33-note.oss-cn-shanghai.aliyuncs.com/image-20250123195644102.png)

总的来说，版本隔离的开启与否，会影响我们游戏模组位置，在后续同步客户端配置模组文件夹时，需要根据自己是否开启了版本隔离来进行配置。

### (2) 模组类型

一般来说，Minecraft模组分为下列类型：

- **双端模组**：大多数模组都是双端模组，即**需要游戏端和服务端同时安装**，玩家才能正常进入服务器并游玩，任何在游戏中增加了实体、物品、方块或者改变了游戏规则的模组都是双端模组，例如工业2、暮色森林、更多武器、砍树等
- **仅客户端模组**：这类模组通常是辅助型模组，即**仅需要游戏端安装，服务端不需要或者不能安装的模组**，这类模组用于丰富或者强化游戏的辅助性功能，例如小地图、物品信息显示、`Iris`高清修复等

该同步工具能够按需配置，实现仅同步双端模组，还是同时同步双端和客户端模组，后续章节会讲到相关配置。

### (3) 运行路径

任何计算机程序在运行时都会有一个**运行路径**，在程序以相对路径读取或者写入文件时，就是以运行路径为参照的。运行路径又称作**工作目录**、**当前路径**等。

比如`rm`命令可以删除文件，当我们传递一个相对路径的文件给`rm`时，例如：

```bash
rm a.txt
```

那么`rm`命令就会寻找其运行路径下的`a.txt`文件并删除它。

那么通常在程序运行时，运行路径具体是什么呢？这就得分情况讨论了。

在Windows操作系统下，我们很少使用命令行去启动程序，而是使用鼠标双击可执行文件运行，这时运行路径就是**可执行文件所在的目录**。

如果我们使用终端例如`cmd`，或者在Linux上的`bash`调用程序/命令时，运行路径就取决于我们**终端当前的运行路径**了！通常运行路径会显示在终端前面，当我们打开`cmd`时：

![image-20250123200603165](https://swsk33-note.oss-cn-shanghai.aliyuncs.com/image-20250123200603165.png)

可见`cmd`默认的运行路径就是我们的用户目录，这一点和Linux的绝大多数终端一样，使用`cd`命令就可以切换运行路径。

总的来说，需要大家明白**运行路径**的概念，也就是每个程序运行时的参照路径，程序参照运行路径来读取或者写入给定的相对路径的文件，对于我们后续配置模组同步客户端程序时也是一样，若你配置了相对路径，则同步客户端程序也是在运行路径下其查找模组文件夹、配置文件的。

> 可以通过这篇博客更深入地了解一下命令行、运行路径等概念：[传送门](https://juejin.cn/post/7103518875316125733)

## 4，下载说明

在项目仓库主页右侧**发行版/Releases**处即可下载模组同步客户端和服务端程序，其中**包含多个系统平台版本的客户端和服务端**供大家选择。

如果你是服务器管理者，通常下载**模组同步服务端**即可，并将其部署到你的Minecraft模组服务器。下载页面中，模组同步服务端程序包通常文件名如下：

```bash
# 格式：
# mc-sync-server-适用系统-系统架构-版本号.tar.xz（或者.7z）
mc-sync-server-linux-amd64-1.0.0.tar.xz
```

如果你是玩家，或者整合包制作者，通常下载**模组同步客户端**即可，并将其放置到你的Minecraft游戏目录中，然后完成配置。下载页面中，模组同步客户端程序包通常文件名如下：

```bash
# 格式：
# mc-sync-client-适用系统-系统架构-版本号.tar.xz（或者.7z）
mc-sync-client-windows-amd64-1.0.0.7z
```

总的来说，下载的文件名体现了其适用的平台：

- 带有`server`字样则是服务端，反之`client`字样则是客户端
- 适用的操作系统目前包括`windows`和`linux`
- 系统架构通常是`i386`即`32`位操作系统，或者`amd64`即`64`位操作系统

请根据自己的服务器或者电脑系统选择合适的版本下载，在绝大多数情况下，玩家使用的是`64`位Windows操作系统，而服务器一般是`64`位Linux操作系统。

## 5，使用说明

请单独参考服务端和客户端使用说明。

- **客户端**：[传送门](./docs/客户端配置使用说明.md)
- **服务端**：[传送门](./docs/服务端配置使用说明.md)