冰墙

HailWall — 模组白名单

HailWall 会在玩家加入时检查其客户端上安装的模组，如果他们拥有被禁止的模组（或缺少必需的模组），则会将其踢出。这是对经典 模组白名单 理念的现代化、轻量级实现。

⚠️ 请同时在服务器和每个客户端上安装。 纯服务端模组无法读取客户端的完整模组列表——原版根本不会发送这些信息。因此，与所有此类模组一样，HailWall 需要在客户端上运行一个轻量级配套模组。

✨ 特性

• 白名单模式（默认）— 除你允许的模组外，阻止一切。基础模组（minecraft、模组加载器、java、hailwall）始终被允许。
• 黑名单模式 — 除特定模组（作弊客户端、X-ray 等）外，允许一切。
• 必需模组 — 踢出缺少必备模组的玩家。
• 管理员豁免 — 服务器管理员永远不会被踢出，即使安装了额外模组（可通过 usePermission 开关控制）。
• 过渡/监控模式（enforce: false）— 不踢任何人，但仍记录所有人的模组。非常适合在不干扰玩家的情况下逐步推行 HailWall，同时构建你的列表。
• 访问日志 — 每天生成一个 JSON-Lines 文件（保存在 config/ 下，即使在 Aternos 等主机上也可访问），记录谁加入了以及他们携带了哪些模组。旧文件会自动清理。
• 签名握手 — HMAC + 每次连接的挑战机制，防止简单的数据包伪造。
• 零游戏性能开销 — 一切仅在登录时发生一次；日志在非主线程中写入。无每 tick 消耗。

⚙️ 工作原理

在登录握手期间，服务器向客户端请求其模组列表。客户端回复其安装的顶级模组（ID + 版本），并使用 HMAC 签名。服务器验证签名，将列表与你的配置进行比较，然后要么放行玩家，要么断开连接——这一切都发生在玩家进入世界之前。

情况	结果
客户端和服务器均已安装	✅ 完整验证
仅客户端安装	你仍可在其他服务器上游玩；此处不提供任何保护
仅服务器安装	未安装 HailWall 的客户端无法加入（当 requireCompanionMod 开启时）

📦 安装步骤

1. 在服务器和每个客户端上安装正确版本你选择的模组加载器（例如 Fabric、Forge 或 NeoForge）以及任何必需的 API。
2. 将 hailwall-x.y.z.jar 放入服务器和每个客户端的 mods/ 文件夹中。
3. 启动服务器一次以生成 config/hailwall.json，编辑它，然后重启。

🔧 配置 — config/hailwall.json

{
  "mode": "whitelist",          // "whitelist" 或 "blacklist"
  "enforce": true,              // false = 监控模式（仅记录，不踢任何人）
  "operatorsBypass": true,      // 管理员永远不会被踢出
  "requireCompanionMod": true,  // 踢出未安装 HailWall 的客户端
  "verifySignature": true,
  "logModLists": true,
  "enableAccessLog": true,
  "accessLogRetentionDays": 5,

  "whitelist": ["sodium", "iris", "modmenu"],          // 你允许的模组
  "blacklist": ["meteor-client", "wurst", "baritone"], // 仅黑名单模式使用
  "requiredMods": []
  // + 完全可自定义/可翻译的踢出消息
}

在任何模组的 mod.json 中查找其 ID（id 字段）。更简单的方法是：直接从访问日志中读取，或从客户端的 logs/latest.log 中读取——HailWall 会打印报告的模组列表。

🔒 隐私与数据

• 客户端仅发送顶级模组的 ID 和版本——不包含文件路径、不包含系统信息、不包含个人数据。
• 这些数据仅用于允许/拒绝加入，并且仅记录在服务器自己的访问日志中（默认保留 5 天）。不会发送到任何其他地方，其他玩家也无法看到。
• 开源——你可以验证它的确切行为。

🛡️ 关于安全性的诚实说明

与所有客户端侧模组检查一样，HailWall 并非无懈可击：一个执着的人仍可能绕过它。HMAC + 挑战机制可以阻止随意的数据包伪造，但无法阻止专家。它对于普通玩家非常有效，并且最好与 online-mode=true 搭配使用。请将其视为一个坚实的安全层，而非万能解决方案。