模组白名单 Forge NeoForge

模组白名单 Forge NeoForge

在登录时检查客户端的模组列表，如果存在不允许的模组或缺少必需的模组，则将其踢出。

模组白名单

一个面向 Minecraft Forge 和 NeoForge 的安全整合包强制模组。

本描述目前仅适用于 Minecraft 1.7.10-1.0.0、1.21.1-2.0.0 和 1.20.1-3.0.0 版本。其他版本将逐步更新，以匹配相同的功能和配置结构。

由于现代 Minecraft 网络机制的变化，仅靠服务器端方法已无法进行可靠的客户端模组验证。 因此，本项目采用 服务器端 + 轻量级客户端验证模型，以提供准确且防篡改的模组检查。

✨ 功能特性

  • 双侧必需模组
    强制执行服务器和客户端都必须存在的模组。
  • 客户端必需模组
    强制要求特定的客户端模组，即使服务器未安装这些模组。
  • 客户端可选模组
    允许指定的客户端模组（如性能优化、QoL 或视觉类模组），但不强制要求。
  • 仅服务器模组分离
    将仅服务器端使用的模组单独记录，避免其被列入客户端必需列表。
  • 禁止模组和文件
    立即拒绝使用被禁止模组或屏蔽 jar 文件的玩家。
  • 严格模式
    启用后，仅接受明确允许的模组和文件。
  • 文件完整性验证（SHA-256）
    可选的硬核模式，用于验证确切文件名和哈希值。
  • 受控收集流程
    使用受信任的参考客户端自动分类模组和文件。
  • 旧配置迁移
    自动将旧的单文件配置迁移到新的多文件结构。
  • 可配置踢出消息
    支持自定义消息、可点击的整合包链接，以及更清晰的格式化踢出原因。
  • 服务器权威
    所有决策均由服务器强制执行。无分析、无追踪、无第三方服务。

📁 配置结构

模组白名单使用多文件配置布局：

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

用于禁止模组和文件的硬黑名单。

🔒 隐私 / 数据保护

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

🛠 推荐设置 / 收集流程

模组白名单包含一个受控的收集模式，可帮助你安全地生成初始配置结构。

1. 启动一次服务器

首次启动时，模组白名单会自动创建配置文件夹和所需的 JSON 文件。

2. 添加受信任管理员 UUID

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

示例：

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

只有在此列表中列出的玩家才能在收集模式激活时加入服务器。

3. 启用收集模式

运行：

/modwhitelist collect on

这会临时禁用严格模式，并允许受信任的设置客户端加入。

4. 使用参考客户端整合包加入

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

在此过程中，模组白名单会对比：

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

5. 自动分类

受信任客户端成功加入后，模组白名单会自动将条目分类到：

  • 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 文件名阻止，使用 sha256: "*" 的 files
  • 仅当你想阻止一个精确文件版本时，才使用真实的 SHA-256 哈希

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

这意味着：

  • 匹配的条目会被立即拒绝
  • 即使 strict=false 时也同样适用

🐛 已知问题

  • 在测试 Forge 1.7.10 版本时，发现 deny.json 与必需模组组合使用时存在一个错误
  • 在某些配置下，将 deny.json 与必需模组规则一起使用可能导致模组白名单错误地阻止所有模组
  • 该问题最初在 Forge 1.7.10 上发现，但可能也会影响其他受支持的 Forge 和 NeoForge 版本
  • 在调查并修复之前，请谨慎将 deny.json 与必需模组规则一起使用

备注

  • 旧的单文件配置会在首次启动时自动迁移
  • 自动收集会覆盖：
    • both_side_required.json
    • client_optional.json
    • server_only.json
  • client_required.json 有意保持手动管理，以便管理员决定哪些客户端专用模组是真正必需的
  • 彩色踢出消息可帮助玩家立即看到缺少、被阻止或不允许的内容