ClawModPacker 是一个专为 Minecraft Java 版服务器设计的 Mod 自动分发与同步工具。它由两部分组成：
| 组件 | 技术栈 | 运行环境 |
|---|---|---|
| 服务端 | Java 17+ | 运行在服务器上，监听独立 TCP 端口 |
| 客户端 | C# (.NET 8.0 WPF) | 玩家 Windows 电脑上运行 |
核心目标：让玩家加入服务器时，无需手动下载和放置 Mod 文件。客户端启动后自动连接服务端，比对 Mod 列表，下载缺失或更新的文件，确保玩家的 Mod 版本与服务端完全一致。
- ✅ 客户端启动时自动扫描本地 Mod 目录
- ✅ 自动比对服务端 Mod 列表，识别缺失/过期文件
- ✅ 逐文件分块下载，支持大文件传输
- ✅ 下载完成后自动校验完整性（SHA-256 整体哈希）
- ✅ 过期文件自动删除
- ✅ 自定义 TCP 协议（非 HTTP/FTP，降低被扫描风险）
- ✅ SSL/TLS 加密通信（TLS 1.3）
- ✅ 自定义 CA 证书，客户端验证服务端身份
- ✅ 白名单认证（基于 Minecraft 原版 whitelist.json）
- ✅ Protobuf 二进制序列化（非明文传输）
- ✅ 文件分块传输（96KB/块），避免大文件超时断连
- ✅ 每块 CRC32 校验，出错自动重传（最多 3 次）
- ✅ TCP Keepalive + NoDelay 优化
- ✅ 临时文件写入，校验通过后才生效
- ✅ 详细日志记录，便于排查问题
- ✅ 客户端图形界面（WPF），中文显示
- ✅ 用户名/UUID 自动记忆
- ✅ 进度条实时显示下载进度
- ✅ 一键选择 Mod 目录
- ✅ 数据库可手动重建
┌─────────────────────┐ ┌─────────────────────┐
│ 玩家电脑 (客户端) │ │ VPS (服务端) │
│ ModPackerClient.exe │ │ modpacker-server.jar│
│ │ │ │
│ ┌───────────────┐ │ SSL/TLS TCP │ ┌───────────────┐ │
│ │ WPF 界面 │ │ ──────────────▶ │ │ 认证模块 │ │
│ │ (中文) │ │ 自定义协议 │ │ (白名单校验) │ │
│ └───────┬───────┘ │ │ └───────┬───────┘ │
│ │ │ │ │ │
│ ┌───────┴───────┐ │ AUTH_REQUEST │ ┌───────▼───────┐ │
│ │ 同步引擎 │ │ ──────────────▶ │ │ 数据库模块 │ │
│ │ (分块下载) │ │ │ │ (mod_db.json) │ │
│ └───────┬───────┘ │ LIST_RESPONSE │ └───────┬───────┘ │
│ │ │ ◀────────────── │ │ │
│ │ │ │ ┌───────▼───────┐ │
│ │ │ FILE_REQUEST │ │ 文件分块模块 │ │
│ │ │ ──────────────▶ │ │ (96KB/块) │ │
│ │ │ │ └───────┬───────┘ │
│ │ │ FILE_CHUNK │ ┌───────▼───────┐ │
│ │ │ ◀────────────── │ │ CRC32 校验 │ │
│ │ │ │ └───────────────┘ │
│ │ │ │ │
│ │ │ │ mods/ 目录 │
└─────────────────────┘ └─────────────────────┘
┌──────────────────────────────────────────────────────────┐
│ 固定头部 (9 字节) │
├──────────┬──────────┬────────────────────────────────────┤
│ Magic │ Type │ Payload Length │
│ 4 bytes │ 1 byte │ 4 bytes │
│ 0x4D504B50 │ 0x01~0x07│ Big-Endian │
│ "MPKP" │ 消息类型 │ 负载字节数 │
├──────────┴──────────┴────────────────────────────────────┤
│ 可变长度负载 (Protobuf 序列化) │
└──────────────────────────────────────────────────────────┘
| 编号 | 名称 | 方向 | 说明 |
|---|---|---|---|
| 0x01 | AUTH_REQUEST | C→S | 客户端发送用户名 + UUID |
| 0x02 | AUTH_RESPONSE | S→C | 服务端返回认证结果 |
| 0x03 | LIST_REQUEST | C→S | 客户端请求 Mod 列表 |
| 0x04 | LIST_RESPONSE | S→C | 服务端返回文件列表（含分块信息） |
| 0x05 | FILE_REQUEST | C→S | 客户端请求指定文件的指定块 |
| 0x06 | FILE_CHUNK | S→C | 服务端返回文件块（含 CRC32） |
| 0x07 | ERROR_NOTIFICATION | 双向 | 错误通知 |
- JDK 17 或更高版本
- Maven 3.8 或更高版本
- Linux VPS（推荐）或 Windows Server
cd server
mvn clean package
# 产物：target/modpacker-server-1.0.1.jar./
├── modpacker-server-1.0.1.jar ← 服务端程序
├── config.json ← 配置文件
├── mods/ ← 放置所有 Mod 文件（.jar / .zip）
│ ├── mod1.jar
│ ├── mod2.jar
│ └── ...
├── certs/ ← SSL 证书目录
│ ├── ca.crt ← CA 证书（分发给客户端）
│ └── server.p12 ← 服务端密钥库
├── logs/ ← 日志目录（自动创建）
└── mod_db.json ← 数据库文件（自动生成）
# 使用项目提供的脚本
chmod +x gen_cert.sh
./gen_cert.sh ./
# 生成 ca.crt 和 server.p12将 ca.crt 安全分发给所有玩家，放入客户端 certs/ 目录。
{
"listenPort": 33770,
"whitelistPath": "./whitelist.json",
"modsDir": "./mods",
"dbPath": "./mod_db.json",
"logPath": "./logs/",
"certsDir": "./certs",
"keystoreFile": "server.p12",
"keystorePassword": "changeit",
"connectionTimeout": 300,
"chunkSize": 98304,
"maxConnections": 5
}| 参数 | 说明 | 默认值 |
|---|---|---|
| listenPort | 监听端口 | 33770 |
| whitelistPath | Minecraft 白名单文件路径 | ./whitelist.json |
| modsDir | Mod 文件目录 | ./mods |
| dbPath | 数据库文件路径 | ./mod_db.json |
| logPath | 日志目录 | ./logs/ |
| certsDir | 证书目录 | ./certs |
| keystoreFile | 服务端 PKCS12 密钥库 | server.p12 |
| keystorePassword | 密钥库密码 | changeit |
| connectionTimeout | 连接超时（秒） | 300 |
| chunkSize | 分块大小（字节） | 98304（96KB） |
| maxConnections | 最大并发连接数 | 5 |
确保 whitelist.json 是 Minecraft 原版格式：
[
{"name": "Steve", "uuid": "00000000-0000-0000-0000-000000000000"},
{"name": "Alex", "uuid": "11111111-1111-1111-1111-111111111111"}
]java -jar modpacker-server-1.0.1.jar ./config.json建议配合 systemd 或 screen 后台运行。
- Windows 10 / 11
- .NET 8.0 Runtime（如已打包为 self-contained 则不需要）
cd client
dotnet restore
dotnet build
dotnet run
# 或直接使用编译产物
# bin\Debug\net8.0-windows\ModPackerClient.exeModPackerClient/
├── ModPackerClient.exe ← 客户端主程序
├── Claw.ico ← 应用图标
├── config.json ← 配置文件（自动生成）
├── packets.proto ← Protobuf 定义
├── certs/ ← CA 证书目录
│ └── ca.crt ← 服务端提供的 CA 证书
└── local_db.json ← 本地数据库（自动生成）
- 放置 ca.crt：将服务端分发的
ca.crt放入certs/目录 - 启动客户端：双击
ModPackerClient.exe - 填写信息：
- 服务器地址和端口（由服务器管理员提供）
- 用户名（你的 Minecraft 游戏名）
- UUID（从游戏内 F3 调试屏幕获取，或使用在线工具查询）
- 选择 Mods 目录：点击「浏览...」选择你的 Minecraft
mods文件夹 - 点击「开始同步」：客户端将自动完成认证、比对、下载全过程
- 等待完成：进度条显示 100% 后，即可启动 Minecraft 进入服务器
{
"serverAddress": "your.server.address",
"serverPort": 33770,
"modsDir": "",
"certsDir": "./certs",
"caCertFile": "ca.crt",
"username": "Steve",
"uuid": "00000000-0000-0000-0000-000000000000"
}用户名和 UUID 在首次填写并成功同步后会自动保存，下次启动无需重新输入。
当前默认分块大小为 96KB（98304 字节）
如需修改，请更新服务端 config.json 的 chunkSize 字段，并重启服务端。
服务端默认允许 5 个并发连接。如果你的服务器带宽充足且玩家较多，可以适当提高 maxConnections。注意每个连接会占用一个线程。
服务端日志按日滚动，文件名格式：modpacker-YYYY-MM-DD.log。日志内容包括：
- 连接时间、客户端 IP
- 认证结果（成功/失败）
- 文件下载请求与发送记录
- 异常事件
- 传输加密：所有通信使用 TLS 1.3 加密，防止中间人窃听
- 身份认证：基于 Minecraft 白名单，只有白名单中的玩家才能下载
- 证书验证：客户端验证服务端证书由受信任的 CA 签发
- 自定义协议：非标准端口 + 非标准协议，降低被自动化扫描攻击的风险
ca.key应离线保管，不要在服务器上留存- 证书有效期建议 3650 天（10 年），到期前重新生成
- 更换证书后，需将所有客户端的
ca.crt同步更新
| 错误码 | 名称 | 方向 | 说明 |
|---|---|---|---|
| 0x01 | AUTH_FAILED | S→C | 认证失败（不在白名单中） |
| 0x02 | FILE_NOT_FOUND | S→C | 请求的文件不存在 |
| 0x03 | CHUNK_CHECKSUM_FAIL | C→S | 分块校验失败，请求重传 |
| 0x04 | INTERNAL_ERROR | S→C | 服务端内部错误 |
ClawModPacker/
├── LICENSE ← GPLv3 许可证
├── README.md ← 本文件
├── CONTRIBUTING.md ← 贡献指南
├── .gitignore ← Git 忽略规则
│
├── server/ ← 服务端 (Java)
│ ├── pom.xml ← Maven 构建配置
│ ├── gen_cert.sh ← 证书生成脚本
│ ├── config.json ← 服务端配置示例
│ └── src/main/
│ ├── proto/packets.proto ← Protobuf 消息定义
│ └── java/com/modpacker/server/
│ ├── ModPackServer.java ← 主入口
│ ├── Config.java ← 配置加载
│ ├── AuthManager.java ← 白名单认证
│ ├── DatabaseManager.java ← Mod 数据库管理
│ ├── FileUtils.java ← 哈希/CRC32 工具
│ ├── Packet.java ← 报文编解码
│ ├── NetworkManager.java ← TCP/SSL 网络管理
│ ├── SessionHandler.java ← 单连接会话处理
│ └── Logger.java ← 日志系统
│
└── client/ ← 客户端 (C#)
├── ModPackerClient.csproj ← .NET 项目文件
├── Claw.ico ← 应用图标
├── config.json ← 客户端配置示例
├── packets.proto ← Protobuf 消息定义
└── *.cs ← 源代码文件
├── Config.cs ← 配置管理
├── Packet.cs ← 报文编解码
├── DatabaseManager.cs ← 本地数据库
├── FileManager.cs ← 文件操作 + CRC32
├── NetworkManager.cs ← SSL/TCP 网络管理
├── SyncEngine.cs ← 分块下载引擎
├── MainViewModel.cs ← MVVM 视图模型
├── MainWindow.xaml ← WPF 界面
└── App.xaml ← 应用入口
A: 确保 certs/ca.crt 文件存在。该文件由服务端生成并分发给玩家。如果丢失，请联系服务器管理员重新获取。
A: 检查以下几点：
- 服务端
chunkSize是否为 98304（96KB） - 服务端和客户端是否都启用了
NoDelay（代码中已默认开启） - 网络带宽是否充足
- 服务端
maxConnections是否过小
A: 这通常是防火墙/NAT 超时导致的。确认：
- 服务端
connectionTimeout足够大（默认 300 秒） - 分块大小不是过大（推荐 96KB）
- TCP Keepalive 已启用（代码中已默认开启）
A: 可以。ClawModPacker 不关心 Mod 加载器类型，只要是 .jar 或 .zip 文件放在 mods/ 目录中即可同步。
A: 支持。服务端是标准 Java 程序，只要有 JDK 17+ 即可运行。证书生成脚本提供了 .sh（Linux/Mac）和 .bat（Windows）两个版本。
A: 目前客户端使用 WPF 框架，仅支持 Windows。未来可考虑使用 Avalonia UI 实现跨平台。
本项目在开发过程中使用了 AI 编程工具的辅助，具体说明如下：
- 主要工具：腾讯元宝 (Tencent Yuanbao)
- 模型：DeepSeek-V3
- 辅助范围：代码生成、架构设计建议、文档撰写、Bug 排查
- 所有架构决策：包括自定义协议设计、分块大小选择、安全方案等核心设计均由作者独立完成
- Prompt 工程：所有与 AI 交互的提示词、指令、需求描述均由作者编写
- 最终代码审查与修改：所有 AI 生成的代码均经过作者逐行审查、测试、调试和修改，确保其正确性和安全性
- 项目管理：版本规划、功能优先级、发布决策均由作者做出
作者已审查所有 AI 辅助生成的代码，确认拥有将其以 GPLv3 许可证开源的权利。本项目不包含任何未经授权使用的第三方专有代码。
本项目基于 GNU General Public License v3.0 开源。
简而言之：
- ✅ 你可以自由使用、修改、分发本项目
- ✅ 你可以将本项目用于商业用途
⚠️ 如果你分发修改版本，必须以 GPLv3 开源⚠️ 你必须保留原始版权声明- ❌ 本项目不提供任何担保，使用风险自负
欢迎任何形式的贡献！请阅读 CONTRIBUTING.md 了解详情。
- 作者：@LyumaCia
- 项目地址：https://github.com/LyumaCia/ClawModPacker
- 问题反馈：https://github.com/LyumaCia/ClawModPacker/issues
如果这个项目对你有帮助，请给一个 ⭐ Star 支持一下！