zstdnet-minekuai

🚀 ZstdNet — 为 Minecraft 联机提供透明的 ZSTD 压缩

一句话说明： ZstdNet 运行一个透明代理,用 ZSTD 实时压缩客户端 ↔ 服务端之间的流量。在高重复率的服务器上,它能把公网带宽降到原来的约 1/20,而玩家几乎完全无感。

(中文说明见下方 「中文介绍」。)

---

⚡ 太长不看

🗜️ 将联机带宽压缩到约 5–20%,削减 80%+ 的公网流量。 开启自动接管后,玩家继续输入相同的 IP 和端口——无需学习任何新东西。未安装模组的原版玩家仍然可以正常连接,不受影响。

---

🎯 谁最受益

场景	为什么受益
⚙️ 机械动力(Create)类服务器	大量重复的动能数据——压缩率极高
📦 大型整合包服务器	登录时的 registry / tag / recipe 突发数据可被训练好的字典进一步压扁
🌐 FRP / 内网穿透 / 隧道主机	直接节省公网流量并规避隧道限速
🏠 单机开房联机	给朋友一个更省带宽的入口

---

📊 效果到底有多夸张

以下是一台大型整合包服务器 齿轮盛宴("Gear Feast") 上的真实服务端样本。在同一时间段内,原始流量已达 189 GB,而压缩后实际只传输了 10 GB:

Raw: 189.06 GB (3.6MB/s) | Zstd: 10.28 GB (252.7KB/s) | Ratio: 5.44% | Conns: 8
Raw: 189.06 GB (5.0MB/s) | Zstd: 10.28 GB (234.3KB/s) | Ratio: 5.44% | Conns: 8
Raw: 189.07 GB (4.8MB/s) | Zstd: 10.28 GB (303.7KB/s) | Ratio: 5.44% | Conns: 8

💡 Ratio = 5.44% 意味着只有原始流量的大约 1/20 真正经过公网。带宽账单、FRP 流量和隧道限速都会随之下降。

---

✨ 核心特性

• 🔁 自动接管,玩家零学习成本 —— 默认 auto_takeover=true 时,模组会接管原公网端口,并悄悄把后端 MC 服务端转移到本地端口;玩家继续连接同一地址即可。
• 🖥️ 覆盖客户端 / 专用服务端 / 单机开房 —— 专用服务端、插件版以及单机世界"对局域网开放"的房主都可以使用。
• 📈 内置实时 HUD —— 在游戏内一眼看清 ZSTD 是否生效,以及实时速率、累计流量、压缩率和连接数。
• 🏓 原版状态查询透传 —— 服务器列表可正常 ping,并显示玩家数 / MOTD。
• 🔊 同端口 UDP 透传 —— 兼容依赖 Minecraft 同端口 UDP 的模组,如 Sable / Create: Aeronautics。
• 🎙️ 语音模组零配置兼容 —— 自动探测后端 Simple Voice Chat / Plasmo Voice 的独立 UDP 端口并一并接管;玩家加入时自动开启监听,房主无需填写任何内容(模组服务端和插件端均可)。在默认的 tunnel 模式下,语音复用单一入口端口,因此 FRP / 内网穿透只需转发一个端口。

---

🚀 核心亮点:区块引用缓存(CRC,默认开启)

对于反复重发相同区块的服务器(在区块间来回走动、跨维度往返、重连后重新加载——在机械动力和大型整合包中极为常见),ZSTD 的滑动窗口只能折叠"近期"的重复内容。ZstdNet 增加了一个区块引用缓存,叠加在 ZSTD 之上:

• 会话内 REF —— 当同一区块在本会话中再次发送时,只发送一个 8 字节引用令牌;客户端则重放本地缓存的字节。
• 跨会话 WARM_REF —— 已完整发送的区块会被持久化到磁盘;重连后仍持有的区块以 16 字节令牌发送,跨游戏会话节省流量。
• 字节级 PATCH —— 当区块只有轻微变化时,针对持有的基线发送增量,而不是整个方块。

CRC 和 ZSTD 是相乘关系,而非二选一:CRC 减少重复区块的数量,ZSTD 压缩剩余内容的字节。它默认开启(chunk_cache=auto),但只有在连接协商支持后才会接触字节——不支持 / 未升级的客户端会逐字节透传,任何运行时异常都会 fail-closed(重连,绝不发送错误数据包)。

---

🧩 进阶压缩(全部为可选,默认关闭)

• 🧩 长距离匹配(LDM) —— 对于"同一大型结构在几分钟内反复出现"的服务器,可进一步压缩比例。
• 📖 一键自动字典 —— 在服务端设置 dictionary_auto=true:它会自动采样实时流量 → 后台训练 → 热启用并向玩家推送字典,无需重启、无需手动分发。在登录注册表 / 标签 / 配方突发数据以及大量小数据包上收益最大。
• 🧬 实体数据包流变换 —— 针对重实体场景(机械动力装置、刷怪塔、袭击),在压缩前对实体移动 / 元数据进行可逆解交错,以提升这些场景的压缩率。

✅ 这些选项默认关闭,需主动开启。默认配置与历史行为逐字节一致,并与未升级客户端保持线缆兼容——如果一端未启用,该连接会静默回退为普通透传。

---

🔐 内置正版(Mojang)验证——无需额外模组

ZstdNet 可在登录期间自行验证正版账号(access token 从不离开客户端),因此你可以在离线后端上保留真实的正版 UUID/皮肤,同时压缩始终开启——无需再安装 TrueUUID。配置项 premium_verification 默认 auto(跟随 server.properties 的 online-mode)。在 1.18.2 ~ 26.1 的 Fabric / Forge / NeoForge 上均可用。(Bukkit/Spigot 插件版不支持此功能——在那里请保持后端 online-mode=false。)

---

📦 支持的版本与平台

推荐客户端和服务端都安装。

加载器	版本
🟧 Forge	1.18.2 / 1.19.2 / 1.20.1
🟨 NeoForge	1.20.1 / 1.21.1 / 26.1
🟦 Fabric	1.20.1 / 1.21.1 / 26.1
🟩 插件版 / 混合端	Bukkit / Spigot / Paper / Purpur,以及 Arclight / Mohist / CatServer(一个 jar 跨越 1.20.1 与最新的 1.21.x)

(26.1 构建覆盖整个 26.1.x 系列,需要 Java 25;1.18.2 仅限 Forge。)

🔌 插件版(无模组加载器): 将 zstdnet-bukkit 的 jar 放入 plugins/。压缩需要两端配合——想要压缩的玩家仍需安装 ZstdNet 客户端模组;未安装的原版玩家可正常连接,不受影响。

---

⚙️ 必要设置(专用服务端)

在专用服务端上使用内置 ZstdNet 服务端入口之前,请至少在后端 server.properties 中设置:

online-mode=false

想在离线转发的同时保留正版身份?请使用上面的内置正版验证(模组版),或在插件版上搭配 TrueUUID。

---

🎮 常用命令

命令	作用
/zstdhud	查看 / 切换游戏内 HUD(on / off / toggle)
/zstdport	在单机 / 局域网开房时查看或修改端口(show / game / zstd / voice / zstdvoice)

运行时配置位于 Minecraft 的 config/ 中:客户端 zstdnet-client.toml,服务端 zstdnet-server.properties(自动维护、支持热重载)。

---

🆕 本构建相比原版的增补

本构建是 xuenai · 麦块联机(MineKuai) 对原作 wish131400/zstdnet(MIT)的深度分叉。原版已具备 ZSTD 代理、自动接管、同端口 UDP 透传、HUD 和多加载器支持,但仅覆盖 1.20.1 / 1.21.1。在此基础上,本构建新增:

• 🌍 远更广泛的版本与平台 —— 新增 Forge 1.18.2 / 1.19.2 和 Minecraft 26.1(26.1.1 / 26.1.2),以及插件版 / 混合端构建(Bukkit / Spigot / Paper / Purpur,Arclight / Mohist),一个 jar 跨越 1.20.1 与 1.21.x,含 Folia 支持。
• 🗜️ 更强的压缩 —— 长距离匹配,以及带零配置自动分发的训练字典(dictionary_auto=true)。
• 🧩 区块引用缓存(默认开启)和 🧬 实体数据包流变换(可选)——两者均经过协商、线缆兼容且 fail-closed。
• 🎙️ 零配置语音模组兼容 —— 自动探测后端 Simple Voice Chat / Plasmo Voice 的 UDP 端口(tunnel / bridge 传输模式)。
• 🔐 内置正版验证 —— 在离线后端上保留正版 UUID,无需额外模组。

CRC 默认开启;LDM / 字典 / 实体变换默认关闭,需主动开启,均与未升级客户端线缆兼容。

---

🙏 致谢与许可

基于 wish 的 wish131400/zstdnet(MIT)构建——该上游版权与许可声明保留在每一个 jar 内。由 xuenai · 麦块联机 / MineKuai (minekuai.com) 维护与扩展。

本构建自身的源代码目前闭源(保留所有权利);后续可能以更新后的许可证开源。

随每个 jar 一同打包的第三方组件完整声明(LICENSE / NOTICE):zstd-jni(BSD 2-Clause,内含 Meta 的 Zstandard,BSD 2-Clause)。区块引用缓存的 full / ref / patch 思路受 BandwidthOptimizer(LGPL 2.1)启发——ZstdNet 的实现是未使用其任何代码的净室重写。

---

---

🇨🇳 中文介绍

一句话：把客户端 ↔ 服务端之间的转发流量实时用 ZSTD 压一遍，公网带宽直接砍到原来的 二十分之一 左右，而玩家几乎完全无感。

ZstdNet 用 ZSTD 算法实时压缩客户端与服务端之间的转发流量。在「数据高度重复」的联机场景下大幅削减公网带宽占用。开启自动接管后，玩家继续填原来那个 IP 和端口就行；没装模组的原版玩家也能照常进服，互不影响。

🎯 它尤其适合谁

场景	为什么受益
⚙️ 机械动力（Create）类服务器	大量重复的机械运转数据，压缩率极高
📦 大型整合包服务器	登录初始的 registry / tag / recipe 爆发可被字典进一步压扁
🌐 FRP / 内网穿透 / 隧道转发	直接省下公网流量与穿透限速
🏠 单机开房的房主	想给朋友一个更省带宽的入口

📊 实际效果有多夸张

大型整合包「齿轮盛宴」服务器侧的一组真实统计 —— 同一段时间内原始流量已经跑到 189 GB，压缩后实际只传输了 10 GB：

Raw: 189.06 GB (3.6MB/s) | Zstd: 10.28 GB (252.7KB/s) | Ratio: 5.44% | Conns: 8
Raw: 189.06 GB (5.0MB/s) | Zstd: 10.28 GB (234.3KB/s) | Ratio: 5.44% | Conns: 8
Raw: 189.07 GB (4.8MB/s) | Zstd: 10.28 GB (303.7KB/s) | Ratio: 5.44% | Conns: 8

💡 Ratio = 5.44%，意味着公网上实际只跑了原始流量的 二十分之一 左右。

✨ 核心特性

• 🔁 自动接管，玩家零学习成本 —— 默认 auto_takeover=true，模组接管原公网端口、把后端 MC 悄悄挪到本地端口，玩家继续连原地址即可。
• 🖥️ 客户端 / 服务端 / 单机开房全覆盖 —— 专用服、插件端、以及单机「对局域网开放」的房主都能用。
• 📈 内置实时 HUD —— 游戏里一眼看清当前是否在走 ZSTD、实时速率、累计流量、压缩率、连接数。
• 🏓 原版状态查询透传 —— 服务器列表能正常 ping、显示在线人数和 MOTD。
• 🔊 同端口 UDP 原样透传 —— 兼容 Sable / 机械动力：航空学这类依赖同端口 UDP 的模组。
• 🎙️ 语音模组零配置兼容 —— 自动探测后端 Simple Voice Chat / Plasmo Voice 的独立 UDP 端口并一起接管，玩家进服自动开监听，服主无需手填端口。默认 tunnel 模式下语音也复用入口端口这一个口。

🚀 区块引用缓存（CRC，默认开启）

针对「同一个区块被反复下发」的场景（反复进出区块、跨维度往返、重连后重新加载 —— Create 系与大型整合包尤为常见），在 ZSTD 之前把客户端已持有的相同区块换成 8/16 字节令牌（会话内 REF / 跨会话 WARM_REF）或字节级增量（PATCH），与 ZSTD 叠加进一步压低带宽。默认 chunk_cache=auto、协商生效、fail-closed 不损坏数据 —— 不支持的客户端逐字节透传。

🧩 进阶压缩能力（全部可选，默认关闭）

• 🧩 长距离匹配（LDM） —— 面向「同样的大结构几分钟内反复出现」的服务器，进一步榨干压缩率。
• 📖 一键全自动字典 —— 服务端设 dictionary_auto=true 即可：自动采样 → 后台训练 → 热插启用并下发玩家，无需重启、无需手动分发。
• 🧬 实体包流变换 —— 面向大量实体 / 生物场景（机械动力契约体、刷怪塔、怪潮），在压缩前做可逆去交错。

✅ 以上选项默认关闭、可选开启；默认配置与历史行为逐字节一致，并对未升级客户端保持线兼容 —— 一端没开就自动回退原样转发。

🔐 内置正版验证（无需额外装 mod）

ZstdNet 可在登录阶段内置正版账号验证（access token 不出客户端），在离线后端上也能保留真实正版 UUID/皮肤，压缩照常 —— 无需再装 TrueUUID。premium_verification 默认 auto（跟随 server.properties 的 online-mode）。Fabric / Forge / NeoForge（1.18.2 ~ 26.1）全已内置；Bukkit/Spigot 插件端暂不支持，请保持后端 online-mode=false。

📦 支持的版本与平台

推荐客户端和服务端都安装。

加载器	支持版本
🟧 Forge	1.18.2 / 1.19.2 / 1.20.1
🟨 NeoForge	1.20.1 / 1.21.1 / 26.1
🟦 Fabric	1.20.1 / 1.21.1 / 26.1
🟩 插件端 / 混合端	Bukkit / Spigot / Paper / Purpur，以及 Arclight / Mohist / CatServer（一个 jar 跨 1.20.1 与 1.21.x）

（26.1 构建覆盖整个 26.1.x 线，需要 Java 25；1.18.2 为 Forge 专属。）

🔌 插件端（无需 mod 加载器）：把 zstdnet-bukkit 的 jar 丢进 plugins/ 即可。压缩需要两端配合：想要压缩的玩家仍需安装 ZstdNet 客户端 mod；没装的原版玩家照常直连，不受影响。

⚙️ 必要准备（专用服）

在专用服上使用内置 ZstdNet 服务端入口前，请在后端 server.properties 中至少设置 online-mode=false。如需在离线转发的同时保留正版身份：mod 版用上面的内置正版验证；插件版可搭配 TrueUUID。

🎮 常用指令

• /zstdhud —— 查看 / 切换游戏内 HUD（on / off / toggle）。
• /zstdport —— 单机 / 局域网开房时查看或修改端口（show / game / zstd / voice / zstdvoice）。

运行时配置文件位于 config/：客户端 zstdnet-client.toml、服务端 zstdnet-server.properties（自动维护、支持热重载）。

🙏 致谢与来源

本项目基于原作者 wish 的开源项目 wish131400/zstdnet（MIT License）二次开发，上游的 MIT 版权与许可声明随每个 jar 一同保留；由 xuenai · 麦块联机（minekuai.com） 维护与扩展。

本二次开发版本的源代码目前未开源（保留所有权利 / All Rights Reserved），后续可能在确定协议后开源。

随每个 jar 打包的第三方组件完整声明（LICENSE / NOTICE）：zstd-jni（BSD 2-Clause，内含 Meta 的 Zstandard）。「区块引用缓存」的 full / ref / patch 思路借鉴参考 BandwidthOptimizer（LGPL 2.1），但净室自研、未使用其代码。

---