IP白名单 · 我的世界Mod

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

IPWL —— 基于 IP 的 Minecraft 白名单 (Fabric)

Minecraft: 1.21.1-26.2 | 加载器: Fabric | Java: 25 | 许可协议: GPL

一款服务端模组，在 Mojang 官方验证之上增加了第二层安全防护。每位玩家都会被绑定到一个或多个被批准的 IP 地址，即使某人拥有有效账号，除非从预先批准的 IP 地址连接，否则无法加入游戏。连接在身份验证完成前就会被阻止，因此被拒绝的玩家只会消耗极少的服务器资源。

安装

将 .jar 文件放入服务器的 mods/ 文件夹。
启动服务器。模组会自动创建 config/ipwl.json 文件。
将你自己添加为 IPWL 管理员（见下文），然后开始管理玩家。

无需 OP 权限。 IPWL 使用自己的管理员列表 —— OP 状态是完全独立的。

管理员设置

IPWL 拥有自己的权限系统。只有被列为 IPWL 管理员的玩家才能执行任何 /ipwl、/lockdown、/seen 或 /connections 命令。服务器控制台始终拥有完全访问权限。

/ipwl admin add <玩家>     — 授予 IPWL 访问权限（立即保存到配置）
/ipwl admin remove <玩家>  — 立即撤销访问权限，并刷新其命令树
/ipwl admin list             — 显示所有当前 IPWL 管理员

当管理员被移除时，他们会立即失去 Tab 补全和命令执行权限，无需重新加入游戏。

白名单命令

/ipwl add <玩家>           — 允许玩家从任意 IP 加入
/ipwl add <玩家> <IP>      — 允许玩家从特定 IP 加入
/ipwl addip <玩家> <IP>    — 为已有玩家添加第二个允许的 IP
/ipwl removeip <玩家> <IP> — 移除玩家的一个特定 IP
/ipwl remove <玩家>        — 完全移除玩家，如果在线则将其踢出
/ipwl list                   — 显示所有白名单玩家及其 IP
/ipwl reload                 — 从磁盘重新加载配置和白名单

支持的 IP 格式：

精确: 192.168.1.5
通配符后缀: 192.168.1.* （匹配所有以该前缀开头的 IP）
CIDR 表示法: 192.168.1.0/24 （适用于 IPv4 和 IPv6）
任意 IP: * （玩家可以从任何地方加入）

临时访问

/ipwl tempadd <玩家> <IP> <时长>

在有限时间内授予访问权限，而无需修改永久白名单。时长示例：30m、2h、1d、3600s。当时间到期时，所有在线管理员都会自动收到通知。

IP 封禁

/ipwl banip <IP>       — 永久封禁一个 IP（阻止其下的所有账号）
/ipwl unbanip <IP>     — 解除永久封禁
/ipwl banip list       — 显示所有已被永久封禁的 IP

永久封禁会保存到 config/ipwl.json 文件中，并在服务器重启后依然生效。

安全工具

/lockdown on     — 立即阻止所有新连接（管理员仍可进入）
/lockdown off    — 恢复正常运行
/seen <玩家>     — 显示玩家最后已知的 IP 和时间戳
/connections     — 列出所有当前活跃的连接
/security status — 显示实时安全统计（已阻止、已允许、临时封禁等）

未知玩家警报

当有人尝试加入但不在白名单上时，每位在线管理员都会收到一条包含两个可点击按钮的聊天消息：

[接受] — 立即执行 /ipwl add <玩家> <IP>
[封禁 IP] — 立即执行 /ipwl banip <IP>

与此同时，服务器控制台会打印一个清晰可见的提示框：

[IPWL] ====================================================
[IPWL]   !! 未知连接尝试 !!
[IPWL] ====================================================
[IPWL]   名称   : Steve
[IPWL]   IP     : 192.168.1.100
[IPWL]   添加   : /ipwl add Steve 192.168.1.100
[IPWL]   封禁   : /ipwl banip 192.168.1.100
[IPWL] ====================================================

所有管理员操作（接受、封禁、移除）都会广播给所有在线管理员，以确保操作不会基于过时信息。

暴力破解与速率限制

该模组会自动检测并阻止滥用性的连接模式：

模式	处理措施
同一 IP 在 60 秒内尝试 3 个以上不同的用户名	封禁 1 小时（机器人 / 撞库攻击）
同一 IP 连接服务器过于频繁（达到速率限制阈值）	封禁 5 分钟（可配置）
配置中的永久封禁	永久阻止

两种封禁类型都在身份验证完成前强制执行。

日志记录

/ipwl logs verbose   — 记录所有尝试、重试和调试信息
/ipwl logs silent    — 仅记录踢出和关键安全事件（默认）

无论日志级别如何，控制台始终显示未知玩家警报和暴力破解检测信息。

配置

配置文件位于 config/ipwl.json。首次运行时自动创建。

字段	默认值	描述
`maxConnectionsPerIp`	`2`	同一 IP 的最大同时连接数
`rateLimitWindowMs`	`1000`	同一 IP 两次连接之间的最小间隔毫秒数
`maxFailuresBeforeTempBan`	`5`	触发 5 分钟临时封禁前的速率限制失败次数
`tempBanDurationMs`	`300000`	单名玩家临时封禁时长（毫秒）
`enableRateLimit`	`true`	启停速率限制功能
`enableDuplicateCheck`	`true`	阻止同一用户名的重复登录
`enableJoinAlerts`	`true`	向管理员发送未知玩家加入警报
`alertCooldownMs`	`30000`	同一 IP 的警报之间的最小间隔毫秒数
`verboseLogging`	`false`	等价于 `/ipwl logs verbose`
`allowWildcardIps`	`true`	允许将 `*` 作为通配符 IP 条目
`allowSubnetPatterns`	`true`	允许 `192.168.1.*` 此类模式
`admins`	`[]`	IPWL 管理员用户名列表
`bannedIps`	`[]`	被永久封禁的 IP 列表

数据文件

文件	内容
`config/ipwl.json`	所有设置、管理员列表、永久 IP 封禁
`config/ipwl_whitelist.json`	玩家 → IP 映射
`config/ipwl-stats.json`	持久化的连接统计（重启后依然有效）
`config/ipwl-seen.json`	用于 `/seen` 命令的最后上线数据
`config/ipwl-lang.json`	可选的消息覆盖（无需重新构建）

若要自定义任何游戏内消息，请在服务器上创建 config/ipwl-lang.json，并只添加你想要更改的键。该文件的优先级高于内置字符串。

工作原理（简述）

每次登录尝试都会在 ServerboundHelloPacket 处被拦截 —— 这是客户端发送的第一个数据包，远在 Mojang 身份验证开始之前。检查按以下顺序进行：

封锁模式 → 阻止非管理员
永久 IP 封禁 → 阻止
临时封禁（速率限制或暴力破解升级） → 阻止
暴力破解检测（同一 IP 在 60 秒内使用 3 个以上用户名） → 封禁 1 小时
速率限制（连接过快） → 阻止，超过阈值后升级为临时封禁
重复登录检查 → 阻止
白名单 IP 检查 → 阻止，如果未列出则触发管理员警报
每个 IP 的最大连接数 → 阻止
允许加入后运行异步二次重新验证作为安全网