幻景同步

幻景同步

一个用于通过持久TCP连接在主Minecraft服务器与镜像Minecraft服务器之间增量同步维度的fabric minecraft模组。

管理

Mirage

Mirage

一个 Minecraft Fabric 模组,用于在主服务器与一个或多个镜像服务器之间进行增量式、实时的维度区域同步。

Minecraft Fabric Java License Build

中文说明


功能特性

增量同步 通过 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

安装

  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> 计算并向所有已连接的镜像广播某个维度的哈希列表
/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