Mirage Sync

模组

· 作者 MRNOBODY-ZST

一个 Fabric Minecraft 模组,用于通过持久化 TCP 连接在主服务器和镜像服务器之间实现增量维度同步。

0 本站下载 0 关注 更新于 6 个月前

最新 1.2.0 · 1.21.11 · Fabric

一键开服(送7天)

Mirage

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

安装步骤

  1. 构建模组

    ./gradlew build
    

    输出的 jar 包位于 build/libs/mirage-<version>.jar。

  2. 在主服务器和镜像服务器上安装

    • 将 jar 包放入每个服务器的 mods/ 文件夹中。
    • 两台服务器必须运行相同的 Minecraft 版本(1.21.11)。
  3. 首次启动

    • 启动服务器一次。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

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源