Minecraft Mod Sync

Minecraft 私服 mod 校验与 WebRTC P2P 传输工具。客户端由玩家发起校验请求；服务端伴生程序扫描服务器 mods 目录并提供清单；客户端确认后，通过 WebRTC DataChannel 拉取缺失或冲突的 mod。

许可证

本项目采用 MIT License。第三方依赖仍遵循各自许可证，见 THIRD_PARTY_NOTICES.md。

功能

• 客户端输入服务器地址，默认连接 ws://<host>:24454/signal。
• 支持 FRP 通信地址覆盖：服务端仍监听本地 24454，客户端可填写 frps_host:remote_port 通过 FRP 完成校验、manifest 交换和 FRP 中继传输。
• 支持 Fabric、Forge、NeoForge jar 元数据解析。
• 校验 mod id + version + sha256，报告缺失、版本冲突、同版本 hash 冲突、本地多余 mod。
• 共享 Token + nonce HMAC 鉴权，不直接回传明文 Token。
• WebRTC DataChannel 分块传输；IPv6 candidate 优先，5 秒后放行 IPv4 candidate；可配置 TURN 兜底。
• 版本冲突文件不会删除，会移动到 .mod-sync-backup/YYYYMMDD-HHMMSS/。

开发运行

npm install
npm start

服务端开发运行：

Copy-Item config/server.example.json config/server.local.json
# 编辑 config/server.local.json 的 modsDir 和 sharedToken
npm run server

打包

Windows 客户端：

npm run build:client:win

产物目录：dist/client/

• Minecraft Mod Sync-0.1.1-x64-setup.exe
• Minecraft Mod Sync-0.1.1-x64-portable.exe
• 打包资源会附带 LICENSE 和 THIRD_PARTY_NOTICES.md。

Windows 服务端 GUI：

npm run build:server-gui:win

产物目录：dist/server-gui/

• Minecraft Mod Sync Server-0.1.1-x64-setup.exe
• Minecraft Mod Sync Server-0.1.1-x64-portable.exe

Linux/Windows 命令行服务端：

npm run build:server

单独构建：

npm run build:server:win
npm run build:server:linux

产物目录：dist/server/

• minecraft-mod-sync-server-win-x64.exe
• minecraft-mod-sync-server-cli-win-x64.exe
• minecraft-mod-sync-server-linux-x64
• config/server.example.json
• README-server.txt
• LICENSE
• THIRD_PARTY_NOTICES.md

全部构建：

npm run build:all

服务端部署

Windows GUI：

运行 minecraft-mod-sync-server-win-x64.exe，或者运行 Minecraft Mod Sync Server-0.1.1-x64-setup.exe 安装版，在界面里选择服务端 mods 目录、设置 Token，然后点击启动。

Windows CLI：

Copy-Item config/server.example.json config/server.local.json
# 编辑 config/server.local.json
.\minecraft-mod-sync-server-cli-win-x64.exe

Linux：

cp config/server.example.json config/server.local.json
# edit config/server.local.json
chmod +x ./minecraft-mod-sync-server-linux-x64
./minecraft-mod-sync-server-linux-x64

Linux 无桌面交互初始化：

chmod +x minecraft-mod-sync-server-linux-x64 linux-headless-setup.sh linux-set-token.sh
./linux-headless-setup.sh
./linux-set-token.sh
./start-server.sh

linux-headless-setup.sh 会在终端提示修改监听地址和端口，更新 config/server.local.json，并生成 start-server.sh。首次正式使用前还需要确认 modsDir，并用 linux-set-token.sh 设置 sharedToken。

后续单独修改 sharedToken：

./linux-set-token.sh

修改后需要重启服务端。

如果要指定其它配置文件：

./minecraft-mod-sync-server-linux-x64 --config /path/to/server.json

服务端配置

{
  "modsDir": "D:/minecraft/server/mods",
  "listenHost": "",
  "listenPort": 24454,
  "sharedToken": "replace-with-a-private-token",
  "iceServers": [
    {
      "urls": [
        "stun:stun.l.google.com:19302",
        "stun:global.stun.twilio.com:3478"
      ]
    },
    {
      "urls": ["turn:turn.example.com:3478"],
      "username": "turn-user",
      "credential": "turn-password"
    }
  ]
}

至少需要修改：

• modsDir: 服务端 mods 目录。
• sharedToken: 玩家连接时输入的共享密钥，不能使用示例值。
• listenHost: 留空默认监听 IPv4 和 IPv6 双栈；只监听 IPv4 可填 0.0.0.0，只监听 IPv6 可填 ::。
• listenPort: 默认 24454，需要在防火墙或安全组开放。
• iceServers: 默认公开 STUN；复杂 NAT 下建议追加 TURN。

FRP 通信

服务端伴生程序可以继续使用默认监听端口 24454，FRP 只需要把公网远程端口映射到服务端本地 24454。

示例 frpc.ini：

[mod-sync]
type = tcp
local_ip = 127.0.0.1
local_port = 24454
remote_port = 30000

客户端填写：

• 服务器地址: 可以填原服务器地址，用于记录实际服务器。
• FRP 通信地址: 填 frps_host:30000，例如 frp.example.com:30000。
• 下载来源: 选择 仅 FRP/端口映射中继 时，mod 文件会通过这条 FRP WebSocket 连接传输。

只要填写了 FRP 通信地址，校验、鉴权、manifest 拉取和上传确认都会走 FRP 地址，不再默认连接 24454。

测试

npm test

测试覆盖 jar 元数据解析、manifest diff、地址解析、配置加载、文件安装备份。