
幻景同步
一个用于通过持久TCP连接在主Minecraft服务器与镜像Minecraft服务器之间增量同步维度的fabric minecraft模组。
查看大图![]()
Mirage
一个 Minecraft Fabric 模组,用于在主服务器与一个或多个镜像服务器之间进行增量式、实时的维度区域同步。
功能特性
| 增量同步 | 通过 SHA-256 增量比较,仅传输发生更改的 .mca 区域文件 |
| Netty TCP | 持久长连接,镜像端支持自动重连 |
| 原子文件替换 | 先写入临时文件再移动,确保同步过程中文件零损坏 |
| 区块级精度 | 通过 /mirage sync chunk / /mirage pull chunk 同步单个区块 |
| 多维度 | 支持任何已注册的 Minecraft 维度(主世界、下界、末地、自定义维度) |
| 在线同步 | 仅在目标镜像服务器上临时踢出玩家;主服务器保持在线 |
| 自动同步 | 镜像端可选的定时后台同步(间隔可配置) |
| 冷却保护 | 内置同步间冷却,防止服务器上意外出现惊群效应 |
架构
flowchart LR
subgraph Main["主服务器"]
MS[ServerLevel world]
RH[RegionHasher SHA-256]
SS[MirageSyncServer<br/>Netty TCP :25566]
SM[MainServerTask broadcasts hashes]
end
subgraph Mirror["镜像服务器"]
MR[ServerLevel world]
DC[DeltaComparator diff]
FT[FileTransferManager atomic move]
SC[MirageSyncClient TCP client]
MA[MirrorApplyTask applies changes]
end
MS -->|"flush save"| RH
RH -->|"hash map"| SS
SS -.->|"HASH_LIST_RESP"| SC
SC -->|"FILE_SYNC_START"| DC
DC -->|"file list"| SS
SS -.->|"FILE_CHUNK"| SC
SC -->|"write temp mca"| FT
FT -->|"atomic move"| MR
MA -->|"kick players"| MR
MA -->|"clear cache"| MR
同步序列(镜像端发起的拉取):
sequenceDiagram
participant M as 镜像服务器
participant S as 主服务器
M->>S: HANDSHAKE (authToken)
S-->>M: OK
M->>S: HASH_LIST_REQ
S->>S: 刷新世界,保存区块
S->>S: 计算所有 .mca 文件的 SHA-256
S-->>M: HASH_LIST_RESP (维度 + 哈希映射)
M->>M: 与本地哈希进行差异比较
alt 无差异
M-->>S: SYNC_DONE (无更改)
else 文件存在差异
M->>S: FILE_SYNC_START (更改文件列表)
loop 每个文件
S-->>M: FILE_CHUNK (512 KB 分片,base64)
end
S-->>M: SYNC_DONE
end
M->>M: 踢出该维度内所有玩家
M->>M: 强制保存 + 禁用保存
M->>M: 强制卸载所有区块 + 清除区域缓存
M->>M: 原子移动临时文件 → 区域目录
M->>M: 再次清除区域缓存
M->>M: 重新启用世界保存
M->>M: 同步完成
环境要求
| 组件 | 版本 |
|---|---|
| Minecraft | 1.21.11 |
| Fabric Loader | ≥ 0.18.4 |
| Fabric API | 0.141.3+1.21.11 |
| Java | ≥ 21 |
安装
构建模组
./gradlew build输出的 jar 位于
build/libs/mirage-<version>.jar。在主服务器和镜像服务器上安装
- 将 jar 放入各服务器的
mods/文件夹。 - 两台服务器必须运行相同的 Minecraft 版本(1.21.11)。
- 将 jar 放入各服务器的
首次启动
- 启动一次服务器。
config/mirage.json会自动生成。 - 停止服务器并编辑配置(见下文)。
- 重启服务器。
- 启动一次服务器。
配置
配置文件:config/mirage.json,首次启动时创建。
主服务器
{
"mode": "main",
"syncCooldownSeconds": 30,
"mainServer": {
"port": 25566,
"authToken": "replace-with-a-secure-random-string"
}
}
镜像服务器
{
"mode": "mirror",
"syncCooldownSeconds": 30,
"mirrorServer": {
"mainIp": "main-server-ip-or-hostname",
"mainPort": 25566,
"authToken": "replace-with-a-secure-random-string",
"targetDimensions": [
"minecraft:overworld"
],
"autoSyncEnabled": false,
"autoSyncIntervalMinutes": 30
}
}
配置字段
| 字段 | 默认值 | 描述 |
|---|---|---|
mode |
main |
服务器角色:main 或 mirror |
syncCooldownSeconds |
30 |
两次同步操作之间的最小秒数 |
mainServer.port |
25566 |
同步监听的 TCP 端口(仅主服务器) |
mainServer.authToken |
change-me |
必须与镜像端令牌完全一致 |
mirrorServer.mainIp |
127.0.0.1 |
主服务器 IP 或主机名 |
mirrorServer.mainPort |
25566 |
主服务器同步端口 |
mirrorServer.authToken |
change-me |
必须与主服务器令牌完全一致 |
mirrorServer.targetDimensions |
[minecraft:overworld] |
拉取时要同步的维度 |
mirrorServer.autoSyncEnabled |
false |
启用自动定时同步 |
mirrorServer.autoSyncIntervalMinutes |
30 |
自动同步间隔(分钟) |
警告:
authToken在两台服务器上必须完全相同——否则连接会被拒绝。使用前请将默认值change-me改为安全的随机字符串。注意:对网络设置(
port、mainIp、mainPort)的更改需要重启服务器。
命令
所有管理员级命令需要权限等级 OPERATORS。
主服务器命令
| 命令 | 描述 |
|---|---|
/mirage sync <dimension> |
计算并向所有已连接的镜像广播某个维度的哈希列表 |
/mirage sync all |
广播所有已注册维度的哈希列表 |
/mirage sync chunk <dimension> <x> <z> |
按方块坐标广播单个区块 |
/mirage status |
显示模式、已连接镜像数量、同步状态 |
/mirage reload |
从磁盘重新加载 config/mirage.json |
镜像服务器命令
| 命令 | 描述 |
|---|---|
/mirage pull <dimension> |
从主服务器拉取一个维度 |
/mirage pull all |
拉取 targetDimensions 中列出的所有维度 |
/mirage pull chunk <dimension> <x> <z> |
按方块坐标拉取单个区块 |
/mirage status |
显示模式、连接状态、同步状态 |
/mirage reload |
从磁盘重新加载 config/mirage.json |
注意:同步期间,镜像服务器上目标维度内的玩家将被踢出。
项目结构
src/main/java/xyz/tofumc/
├── Mirage.java # 模组入口点、生命周期
└── mirage/
├── command/
│ └── MirageCommand.java # /mirage 命令树 (brigadier)
├── config/
│ ├── ConfigManager.java # JSON 配置读写
│ └── MirageConfig.java # 带默认值的配置 POJO
├── hash/
│ ├── RegionHasher.java # 计算维度内所有 .mca 文件的 SHA-256
│ ├── DeltaComparator.java # 哈希差异 → 需下载/删除的文件
│ └── FileTransferManager.java # 分块写入 + 原子移动
├── network/
│ ├── protocol/
│ │ ├── MessageType.java # 枚举:HANDSHAKE、HASH_LIST_REQ、...
│ │ ├── MirageProtocol.java # 二进制编码/解码 (ByteBuf codec)
│ │ ├── MessagePayloads.java # 基于 record 的负载定义
│ │ └── MirageFrameDecoder.java # 4 字节大端序长度分帧
│ ├── server/
│ │ ├── MirageSyncServer.java # Netty NIO 服务器,广播辅助
│ │ └── ServerHandler.java # 服务端通道入站处理器
│ └── client/
│ ├── MirageSyncClient.java # Netty TCP 客户端,自动重连
│ └── ClientHandler.java # 客户端通道入站处理器
├── sync/
│ ├── SyncState.java # 同步进行中标志 + 冷却计时器
│ ├── MainServerTask.java # 哈希计算 + 广播
│ ├── MirrorApplyTask.java # 接收 + 应用文件 / 内存区块补丁
│ └── ScheduledSyncTask.java # 自动同步调度(镜像端)
├── util/
│ ├── HashUtil.java # SHA-256 摘要封装
│ ├── DimensionPathUtil.java # 维度 ID → region/目录路径
│ ├── RegionFileUtil.java # .mca 文件名、区块偏移、NBT 读写
│ └── SyncLogger.java # 带命名空间的日志辅助
└── world/
├── WorldSafetyManager.java # 踢出玩家、强制保存、保存开/关
└── ChunkUnloader.java # 卸载区块 + 清除区域缓存
构建与发布
本地构建
./gradlew build
产物:build/libs/mirage-<version>.jar
版本从 gradle.properties 读取(mod_version,当前为 1.2.0)。
CI/CD
| 工作流 | 触发条件 | 操作 |
|---|---|---|
build.yml |
推送到任意分支 / PR | ./gradlew build → 上传产物 |
release.yml |
推送标签 v* |
在 gradle.properties 中更新 mod_version → ./gradlew build → 发布 GitHub Release |
贡献
欢迎提交错误报告和功能请求。提交拉取请求前请先开一个 issue。
开发环境搭建
git clone https://github.com/MRNOBODY-ZST/Mirage.git
cd Mirage
./gradlew build # 验证能否编译
常见问题
问:我可以运行多个镜像服务器吗? 可以。主服务器是一个 TCP 服务器——任意数量的镜像都可以同时连接。每个镜像独立运行。
问:这个模组是 BungeeCord/Velocity 代理吗?
不是。Mirage 只同步世界区域文件(.mca)。它不代理玩家连接或聊天。它是一个世界同步工具,不是代理。
问:同步期间玩家会怎样? 在镜像服务器上,同步维度内的玩家会被踢出并收到一条消息,之后可立即重连(世界已完全保存且一致)。主服务器继续正常运行——玩家不受影响。
问:如果同步中断(例如网络断开)怎么办?
文件传输采用临时文件后移动的原子操作。如果传输中途中断,镜像的世界仍保持之前的一致状态。不会发生损坏。重新连接后再次运行 /mirage pull <dimension> 即可。
问:需要单独安装 Fabric API 吗?
Fabric API 在 fabric.mod.json 中声明为依赖,版本为 *,即必须安装。请将其与 Mirage 一起放入 mods/ 文件夹。
许可证
MIT 许可证——见 LICENSE。
Mirage — TofuMC · Minecraft 1.21.11 · Fabric
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。