IPWL 基于 IP 的白名单(Minecraft Fabric 模组)
Minecraft: 1.21.1-26.3 | 加载器: 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 <player> — 授予 IPWL 访问权限(立即保存到配置)
/ipwl admin remove <player> — 立即撤销权限,刷新其命令树
/ipwl admin list — 显示所有当前 IPWL 管理员
当管理员被移除时,他们将立即失去 Tab 补全和命令执行权限,无需重新加入服务器。
白名单命令
/ipwl add <player> — 允许该玩家从任意 IP 加入
/ipwl add <player> <ip> — 允许该玩家从特定 IP 加入
/ipwl addip <player> <ip> — 为现有玩家添加第二个允许的 IP
/ipwl removeip <player> <ip> — 移除玩家的一个特定 IP
/ipwl remove <player> — 完全移除玩家,如果在线则踢出
/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 <player> <ip> <duration>
在有限时间内授予访问权限,而不修改永久白名单。持续时间示例:30m、2h、1d、3600s。时间到期后,所有在线管理员会自动收到通知。
IP 封禁
/ipwl banip <ip> — 永久封禁某个 IP(阻止来自该 IP 的所有账号)
/ipwl unbanip <ip> — 解除永久封禁
/ipwl banip list — 显示所有永久封禁的 IP
永久封禁保存在 config/ipwl.json 中,并在服务器重启后依然有效。
安全工具
/lockdown on — 立即阻止所有新连接(管理员仍允许加入)
/lockdown off — 恢复正常操作
/seen <player> — 显示玩家最后已知 IP 和时间戳
/connections — 列出所有当前活动的连接
/security status — 显示实时安全统计信息(已阻止、已允许、临时封禁等)
未知玩家警报
当有人尝试加入且不在白名单上时,每位在线管理员都会收到一条聊天消息,包含两个可点击按钮:
- [接受] — 立即执行
/ipwl add <player> <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 封禁 → 阻止
- 临时封禁(速率限制或暴力破解升级)→ 阻止
- 暴力破解检测(60 秒内同一 IP 出现 3+ 个不同用户名)→ 封禁 1 小时
- 速率限制(请求过快)→ 阻止,达到阈值后升级为临时封禁
- 重复登录检查 → 阻止
- 白名单 IP 检查 → 阻止,若未列入白名单则触发管理员警报
- 每 IP 最大连接数限制 → 阻止
- 允许在加入后进行二次异步重新验证,作为安全网
IPWL IP-Based Whitelist for Minecraft (Fabric)
Minecraft: 1.21.1-26.3 | Loader: Fabric | Java: 25 | License: GPL
A server-side mod that adds a second security layer on top of Mojang authentication. Every player is bound to one or more approved IP addresses, even if someone has a valid account, they cannot join unless they are connecting from a pre-approved IP. Connections are blocked before authentication even completes, so rejected players consume minimal server resources.
Installation
- Drop the
.jar into your server's mods/ folder.
- Start the server. The mod creates
config/ipwl.json automatically.
- Add yourself as an IPWL admin (see below) and start managing players.
No OP required. IPWL uses its own admin list — OP status is completely separate.
Admin Setup
IPWL has its own permission system. Only players listed as IPWL admins can run any /ipwl, /lockdown, /seen, or /connections command. The server console always has full access.
/ipwl admin add <player> — Grant IPWL access (saved to config immediately)
/ipwl admin remove <player> — Revoke access instantly, refreshes their command tree
/ipwl admin list — Show all current IPWL admins
When an admin is removed they lose tab-complete and command execution immediately without needing to rejoin.
Whitelist Commands
/ipwl add <player> — Allow player from any IP
/ipwl add <player> <ip> — Allow player from a specific IP
/ipwl addip <player> <ip> — Add a second allowed IP to an existing player
/ipwl removeip <player> <ip> — Remove one specific IP from a player
/ipwl remove <player> — Remove player entirely and kick them if online
/ipwl list — Show all whitelisted players and their IPs
/ipwl reload — Reload config and whitelist from disk
IP formats supported:
- Exact:
192.168.1.5
- Wildcard suffix:
192.168.1.* (matches any IP starting with that prefix)
- CIDR notation:
192.168.1.0/24 (works for both IPv4 and IPv6)
- Any IP:
* (player can join from anywhere)
Temporary Access
/ipwl tempadd <player> <ip> <duration>
Grants access for a limited time without modifying the permanent whitelist. Duration examples: 30m, 2h, 1d, 3600s. When the time expires, all online admins are notified automatically.
IP Bans
/ipwl banip <ip> — Permanently ban an IP (blocks all accounts from it)
/ipwl unbanip <ip> — Lift a permanent ban
/ipwl banip list — Show all permanently banned IPs
Permanent bans are saved to config/ipwl.json and survive server restarts.
Security Tools
/lockdown on — Block all new connections immediately (admins still allowed)
/lockdown off — Resume normal operation
/seen <player> — Show last known IP and timestamp for a player
/connections — List all currently active connections
/security status — Show live security stats (blocked, allowed, temp bans, etc.)
Unknown Player Alerts
When someone tries to join and is not on the whitelist, every online admin receives a chat message with two clickable buttons:
- [Accept] — runs
/ipwl add <player> <ip> instantly
- [Ban IP] — runs
/ipwl banip <ip> instantly
At the same time, the server console prints a clearly visible block:
[IPWL] ====================================================
[IPWL] !! UNKNOWN CONNECTION ATTEMPT !!
[IPWL] ====================================================
[IPWL] Name : Steve
[IPWL] IP : 192.168.1.100
[IPWL] To add : /ipwl add Steve 192.168.1.100
[IPWL] To ban : /ipwl banip 192.168.1.100
[IPWL] ====================================================
All admin actions (accept, ban, remove) are broadcast to every online admin so no one acts on stale information.
Bruteforce & Rate Limiting
The mod automatically detects and blocks abusive connection patterns:
| Pattern |
Action |
| Same IP tries 3+ different usernames within 60 seconds |
1-hour ban (bot / credential stuffing) |
| Same IP hammers the server too fast (rate limit threshold) |
5-minute ban (configurable) |
| Permanent ban in config |
Blocked forever |
Both ban types are enforced before authentication completes.
Logging
/ipwl logs verbose — Log all attempts, retries, and debug info
/ipwl logs silent — Log only kicks and critical security events (default)
The console always shows unknown-player alerts and bruteforce detections regardless of log level.
Configuration
Located at config/ipwl.json. Created automatically on first run.
| Field |
Default |
Description |
maxConnectionsPerIp |
2 |
Max simultaneous sessions from one IP |
rateLimitWindowMs |
1000 |
Minimum ms between connections from same IP |
maxFailuresBeforeTempBan |
5 |
Rate limit failures before 5-min temp ban |
tempBanDurationMs |
300000 |
Single-name temp ban duration (ms) |
enableRateLimit |
true |
Toggle rate limiting |
enableDuplicateCheck |
true |
Block duplicate logins for the same username |
enableJoinAlerts |
true |
Send admin alerts for unknown players |
alertCooldownMs |
30000 |
Minimum ms between alerts for the same IP |
verboseLogging |
false |
Mirrors /ipwl logs verbose |
allowWildcardIps |
true |
Allow * as a wildcard IP entry |
allowSubnetPatterns |
true |
Allow 192.168.1.* style patterns |
admins |
[] |
List of IPWL admin usernames |
bannedIps |
[] |
Permanently banned IPs |
Data Files
| File |
Contents |
config/ipwl.json |
All settings, admin list, permanent IP bans |
config/ipwl_whitelist.json |
Player → IP mappings |
config/ipwl-stats.json |
Persistent connection statistics (survives restarts) |
config/ipwl-seen.json |
Last-seen data for /seen command |
config/ipwl-lang.json |
Optional message overrides (no rebuild needed) |
To customise any in-game message, create config/ipwl-lang.json on the server and add only the keys you want to change. This file takes priority over the built-in strings.
How It Works (Brief)
Every login attempt is intercepted at ServerboundHelloPacket — the very first packet a client sends — before Mojang authentication starts. The checks run in this order:
- Lockdown mode → block non-admins
- Permanent IP ban → block
- Temp ban (rate limit or bruteforce escalation) → block
- Bruteforce detection (3+ names from same IP in 60s) → 1-hour ban
- Rate limit (too fast) → block, escalate to temp ban after threshold
- Duplicate login check → block
- Whitelist IP check → block + fire admin alert if not listed
- Max connections per IP → block
- Allow secondary async re-verification runs post-join as a safety net
评论 0
登录后参与评分
还没有评论,来抢沙发吧