Mod Whitelist Forge NeoForge

Mods Whitelist

一款用于 Minecraft Forge 和 NeoForge 的安全整合包强制管理模组。

由于现代 Minecraft 网络机制发生变化，仅通过服务器端已无法可靠验证客户端模组。
因此，本项目采用服务器端 + 轻量级客户端验证模式，实现准确且防篡改的模组检查。

---

✨ 功能

• 双端必需模组
  强制要求模组同时安装在服务器和客户端。
• 仅客户端必需模组
  即使服务器未安装，也可要求客户端安装指定模组。
• 仅客户端可选模组
  允许使用指定的客户端模组，例如性能优化、便捷功能或视觉类模组，而不将其设为必需。
• 服务器专属模组分类
  单独记录仅用于服务器的模组，避免它们被列入客户端必需清单。
• 禁止的模组和文件
  立即拒绝使用违规模组或被禁用 JAR 文件的玩家。
• 严格模式
  启用后，只接受明确允许的模组和文件。
• 文件完整性验证（SHA-256）
  可选的硬核模式，用于验证确切的文件名和哈希值。
• 受控收集流程
  使用可信的参考客户端，自动对模组和文件进行分类。
• 旧版配置迁移
  自动将旧的单文件配置迁移至新的多文件结构。
• 可配置的踢出消息
  支持自定义消息、可点击的整合包链接，以及格式更清晰的踢出原因。
• 服务器权威控制
  所有决定均由服务器强制执行。不使用分析、跟踪或第三方服务。

---

📁 配置结构

Modwhitelist 使用多文件配置布局：

config/modwhitelist/
  settings.json
  both_side_required.json
  client_required.json
  client_optional.json
  server_only.json
  deny.json

文件概览

settings.json

全局设置，例如：

• strict
• strictFiles
• collectMode
• collectWhitelist
• customMessage
• packLink

both_side_required.json

必须同时安装在服务器和客户端的模组与文件。

client_required.json

仍需安装的仅客户端模组与文件。

client_optional.json

允许使用但非必需的仅客户端模组与文件。

server_only.json

仅在服务器上使用的模组与文件。

deny.json

用于禁止违规模组和文件的硬性黑名单。仅在不使用其他文件时才需要。

---

🔒 隐私 / 数据保护

• 仅传输技术性模组标识符和可选的文件哈希值
• 不收集或存储个人数据
• 不使用跟踪、分析或第三方服务
• 服务器日志仅包含踢出原因等最低限度的管理信息

---

🛠 推荐设置 / 收集流程

Modwhitelist 提供受控收集模式，可帮助安全地生成初始配置结构。

1. 启动一次服务器

首次启动时，Modwhitelist 会自动创建配置文件夹和所需的 JSON 文件。

2. 添加可信管理员的 UUID

打开 config/modwhitelist/settings.json，并将可信管理员的 UUID 添加到 collectWhitelist。

示例：

{
  "collectWhitelist": [
    "1696566b-f0c6-473c-89b0-0f16d41a9608"
  ]
}

收集模式启用期间，只有列在其中的玩家才能加入。

3. 启用收集模式

运行：

/modwhitelist collect on

这会暂时关闭严格模式，并允许受信任的设置客户端加入。

4. 使用基准客户端整合包加入服务器

使用你希望作为基准的准确客户端配置加入服务器一次。

在此过程中，Modwhitelist 会比较：

• 服务器端模组/文件
• 客户端模组/文件

5. 自动分类

可信客户端成功加入后，Modwhitelist 会自动将条目分类到：

• both_side_required.json
• client_optional.json
• server_only.json

6. 检查仅客户端条目

收集过程中检测到的仅客户端模组默认会放入 client_optional.json。

如果其中某些仅客户端模组应设为必需，请手动将它们从：

• client_optional.json

移至：

• client_required.json

这是有意为之，因为只有服务器管理员才能决定哪些仅客户端模组确实需要设为必需。

7. 收集模式自动结束

成功完成收集后：

• collectMode 会自动禁用
• strict 会自动恢复

推荐的配置逻辑

建议按以下方式使用这些文件：

• both_side_required.json：两端都必需的模组
• client_required.json：仅客户端必需的模组
• client_optional.json：允许使用的仅客户端模组
• server_only.json：用于记录和区分仅服务端模组
• deny.json：永远不允许使用的模组或文件

---

📜 命令

所有命令都需要管理员权限。

/modwhitelist reload

从磁盘重新加载所有配置文件。

手动编辑 JSON 文件后使用此命令。

/modwhitelist init

如果多文件配置结构尚不存在，则创建该结构。

通常只有全新配置时才需要此命令。如果配置文件已存在或已自动迁移，通常无需使用此命令。

/modwhitelist collect on

启用收集模式，并临时禁用严格模式。

/modwhitelist collect off

禁用收集模式。

/modwhitelist collect clear

清除自动收集的清单：

• both_side_required.json
• client_optional.json
• server_only.json

此操作不会清除 client_required.json。

---

🚫 deny.json

deny.json 是硬性黑名单。

此处列出的所有内容都会被拦截，即使 strict=false 也是如此。

可将以下内容加入黑名单：

• 作弊模组
• 透视模组
• 不兼容的模组
• 你不希望服务器上出现的特定 JAR 文件

格式

{
  "mods": [],
  "files": []
}

按模组 ID 屏蔽模组

{
  "mods": [
    "xray",
    "freecam",
    "example*"
  ],
  "files": []
}

注意：

• xray 会屏蔽完全匹配该 ID 的模组
• example* 会屏蔽所有以 example 开头的内容
• 支持使用 * 进行通配符匹配

按文件名屏蔽文件

{
  "mods": [],
  "files": [
    {
      "name": "badmod.jar",
      "sha256": "*"
    }
  ]
}

此设置仅按文件名屏蔽该文件。

屏蔽某个确切版本的文件

{
  "mods": [],
  "files": [
    {
      "name": "badmod-1.0.0.jar",
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ]
}

此设置只会屏蔽该确切版本的文件。

推荐用法

• 使用 mods 添加常规黑名单条目
• 如果要按 JAR 文件名屏蔽，请在 files 中使用 sha256: "*"
• 只有在要屏蔽某个确切版本的文件时，才使用真实的 SHA-256 哈希值

deny.json会在常规白名单和严格处理之前进行检查。

这意味着：

• 匹配的条目会立即被拒绝
• 这也适用于 strict=false

---

🐛 已知问题

• 测试 Forge 1.7.10 版本时发现了一个 Bug，涉及 deny.json 与必需模组
• 在某些配置下，将 deny.json 与必需模组规则搭配使用，可能会导致 ModWhitelist 错误地屏蔽所有模组
• 该问题最初在 Forge 1.7.10 上被发现，但也可能影响其他受支持的 Forge 和 NeoForge 版本
• 在调查并修复此问题之前，谨慎将 deny.json 与必需模组规则搭配使用

---

备注

• 旧版单文件配置会在首次启动时自动迁移
• 自动收集会覆盖：
  • both_side_required.json
  • client_optional.json
  • server_only.json
• client_required.json 会有意保持手动设置，以便管理员决定哪些仅限客户端的模组确实必需
• 彩色踢出消息可帮助玩家立即了解缺少、被屏蔽或不允许的内容