![]()
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 广播哈希值]
end
subgraph Mirror["镜像服务器"]
MR[ServerLevel world]
DC[DeltaComparator 差异比较]
FT[FileTransferManager 原子移动]
SC[MirageSyncClient TCP 客户端]
MA[MirrorApplyTask 应用更改]
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: flush world, save chunks
S->>S: compute SHA-256 for all .mca files
S-->>M: HASH_LIST_RESP (dimension + hash map)
M->>M: diff with local hashes
alt no differences
M-->>S: SYNC_DONE (no changes)
else files differ
M->>S: FILE_SYNC_START (list of changed files)
loop each file
S-->>M: FILE_CHUNK (512 KB segments, base64)
end
S-->>M: SYNC_DONE
end
M->>M: kick all players in dimension
M->>M: force-save + disable saving
M->>M: force-unload all chunks + clear region cache
M->>M: atomic-move temp files → region dir
M->>M: clear region cache again
M->>M: re-enable world saving
M->>M: sync complete
运行环境要求
| 组件 | 版本 |
|---|---|
| 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> |
计算并向所有已连接的镜像服务器广播指定维度(dimension)的哈希列表 |
/mirage sync all |
广播所有已注册维度的哈希列表 |
/mirage sync chunk <dimension> <x> <z> |
按方块坐标广播单个区块(chunk) |
/mirage status |
显示模式、已连接镜像数量及同步状态 |
/mirage reload |
从磁盘重新加载 config/mirage.json |
Mirror server commands
| 指令 | 说明 |
|---|---|
/mirage pull <dimension> |
从主服务器拉取一个维度 |
/mirage pull all |
拉取 targetDimensions 中列出的所有维度 |
/mirage pull chunk <dimension> <x> <z> |
按方块坐标拉取单个区块 |
/mirage status |
显示模式、连接状态及同步状态 |
/mirage reload |
从磁盘重新加载 config/mirage.json |
注意:在同步期间,镜像服务器上目标维度中的玩家会被踢出。
Project Structure
src/main/java/xyz/tofumc/
├── Mirage.java # Mod entrypoint, lifecycle
└── mirage/
├── command/
│ └── MirageCommand.java # /mirage command tree (brigadier)
├── config/
│ ├── ConfigManager.java # JSON config read/write
│ └── MirageConfig.java # Config POJO with defaults
├── hash/
│ ├── RegionHasher.java # SHA-256 all .mca files in a dimension
│ ├── DeltaComparator.java # Hash diff → files to download/delete
│ └── FileTransferManager.java # Chunked write + atomic move
├── network/
│ ├── protocol/
│ │ ├── MessageType.java # Enum: HANDSHAKE, HASH_LIST_REQ, ...
│ │ ├── MirageProtocol.java # Binary encode/decode (ByteBuf codec)
│ │ ├── MessagePayloads.java # Record-based payload definitions
│ │ └── MirageFrameDecoder.java # 4-byte big-endian length framing
│ ├── server/
│ │ ├── MirageSyncServer.java # Netty NIO server, broadcast helper
│ │ └── ServerHandler.java # Server-side channel inbound handler
│ └── client/
│ ├── MirageSyncClient.java # Netty TCP client, auto-reconnect
│ └── ClientHandler.java # Client-side channel inbound handler
├── sync/
│ ├── SyncState.java # Sync-in-progress flag + cooldown timer
│ ├── MainServerTask.java # Hash computation + broadcast
│ ├── MirrorApplyTask.java # Receive + apply files / in-memory chunk patch
│ └── ScheduledSyncTask.java # Auto-sync scheduling (mirror side)
├── util/
│ ├── HashUtil.java # SHA-256 digest wrapper
│ ├── DimensionPathUtil.java # Dimension ID → region/directory path
│ ├── RegionFileUtil.java # .mca filename, chunk offset, NBT I/O
│ └── SyncLogger.java # namespaced log helper
└── world/
├── WorldSafetyManager.java # kick players, force-save, save on/off
└── ChunkUnloader.java # unload chunks + clear region cache
Build & Release
Build locally
./gradlew build
Artifact: build/libs/mirage-<version>.jar
The version is read from gradle.properties (mod_version, currently 1.2.0).
CI/CD
| Workflow | Trigger | Action |
|---|---|---|
build.yml |
Push to any branch / PR | ./gradlew build → upload artifact |
release.yml |
Push tag v* |
Bump mod_version in gradle.properties → ./gradlew build → publish GitHub Release |
Contributing
Bug reports and feature requests are welcome. Please open an issue before submitting a pull request.
Development setup
git clone https://github.com/MRNOBODY-ZST/Mirage.git
cd Mirage
./gradlew build # verify it compiles
FAQ
Q: Can I run multiple mirrors? Yes. The main server is a TCP server — any number of mirrors can connect simultaneously. Each mirror operates independently.
Q: Does this mod act as a BungeeCord/Velocity proxy?
No. Mirage only synchronizes world region files (.mca). It does not proxy player connections or chat. It is a world synchronization tool, not a proxy.
Q: What happens to players during sync? On the mirror server, players in the syncing dimension are kicked with a message and may reconnect immediately (the world is fully saved and consistent). The main server continues to operate normally — players are not affected.
Q: What if the sync is interrupted (e.g. network cut)?
File transfer uses atomic temp-file-then-move. If interrupted mid-transfer, the mirror's world remains in its previous consistent state. No corruption occurs. Simply run /mirage pull <dimension> again after reconnecting.
Q: Does Fabric API need to be installed separately?
Fabric API is declared as a dependency in fabric.mod.json with * version, meaning it is required. Install it alongside Mirage in the mods/ folder.
License
MIT License — see LICENSE.
Mirage — TofuMC · Minecraft 1.21.11 · Fabric
你是这个资源的作者?登录后可认领此资源。
相似资源
缓冲的原始输入和线程化的事件轮询
显示你正在注视的方块的信息。(适用于 Minecraft 1.16+ 的 Hwyla/Waila 分支)
原版世界生成优化模组
使用 JavaScript 编辑配方、添加自定义物品、编写世界事件!
查看物品与配方
在游戏画面角落显示附近世界地形、玩家、生物和实体的地图。可创建路径点,帮助你找到标记过的位置。
评论 0
登录后参与评分
还没有评论,来抢沙发吧