
概述
mWL 是一款适用于 Paper、Spigot 和 Bukkit 服务器的白名单插件。它让你能完全掌控谁可以加入服务器,支持临时白名单条目、基于权限的绕过功能,以及 MongoDB 或 JSON 存储选项。它兼容从 1.18.x 到 Paper 26.2 的所有版本。
注意: mWL 要求你的服务器运行在在线模式(正版/授权账户)下。不支持离线/破解 UUID。
适用于私人服务器、白名单社区,或任何需要比原版内置白名单更多控制功能的服务器。

功能
| 功能 |
描述 |
| 临时白名单 |
为玩家在有限时间内添加白名单,过期后自动移除 |
| 权限绕过 |
允许工作人员或 VIP 无视白名单状态加入服务器 |
| 双数据库支持 |
将玩家数据存储在 JSON(无需设置)或 MongoDB 中 |
| 过期通知 |
当玩家的白名单时间即将耗尽时发出警告 |
| 移除时自动踢出 |
可选择在通过命令将玩家从白名单移除时将其踢出服务器 |
| 重载支持 |
无需重启即可重载配置文件和语言文件 |
| 权限系统 |
对每个命令进行细粒度的访问控制 |
| 插件 API |
提供公共 WhitelistAPI(通过 MWhitelist.getAPI() 或 Bukkit 的 ServicesManager),以及供其他插件挂钩的自定义事件 |
| 注重隐私 |
可选的 bStats 指标统计,可在配置文件中禁用 |
此外,该插件轻量级,采用异步数据库操作以避免查找过程冻结服务器,并开箱即用兼容 LuckPerms 等其他权限插件。

配置
你可以配置的部分内容如下:
- 通过命令或配置文件开启/关闭白名单
- 灵活的语法支持临时白名单(例如
1d12h30m)
- 可分配给任意权限插件的权限绕过功能
- 可配置间隔周期的玩家定期检查
- 过期通知阈值
- MongoDB 连接设置
- bStats 指标开关 (
enableMetrics: true/false)
whitelist:
status: false # 启用白名单
remove-on-expired: false # 如果玩家时间已过期,则在加入时从数据库中移除该玩家
kick-on-remove: false # 当通过命令将玩家从白名单移除时,将其踢出服务器
bypass:
permission:
enabled: true # 启用通过权限绕过
permission: mwl.whitelist.bypass
player-check: # 定期重新检查在线玩家,如果不再在白名单中或已过期则将其踢出
enabled: false
delay: 60000 # 每次检查之间的毫秒数
expired-notify: # 当玩家剩余时间低于 expired-notify.time 时警告玩家
enabled: true
time: 86400000 # 距离过期的毫秒数
database:
type: JSON # JSON 或 MONGO

命令与权限
命令
| 命令 |
描述 |
/mwl add <player> |
将玩家添加到白名单 |
/mwl remove <player> |
从白名单中移除玩家 |
/mwl addtemp <player> <time> |
临时添加玩家 |
/mwl settemp <player> <time> |
设置现有玩家的过期时间 |
/mwl extendtemp <player> <time> |
延长玩家的剩余时间 |
/mwl check <player> |
检查玩家是否在白名单中 |
/mwl list |
列出所有白名单玩家 |
/mwl toggle [enable|disable] |
切换或设置白名单状态 |
/mwl info |
显示插件信息 |
/mwl reload |
重载配置文件和语言文件 |
/mwl help |
显示帮助概览 |
权限
mwl.command.add: 添加玩家
mwl.command.remove: 移除玩家
mwl.command.addtemp: 添加临时玩家
mwl.command.settemp: 设置过期时间
mwl.command.extendtemp: 延长过期时间
mwl.command.check: 检查白名单状态
mwl.command.list: 列出白名单玩家
mwl.command.toggle: 切换白名单
mwl.command.info: 查看插件信息
mwl.command.reload: 重载配置
mwl.command.help: 查看帮助
mwl.whitelist.bypass: 完全绕过白名单检查

数据库支持
mWL 支持两种存储后端:
- JSON(默认):零设置,将数据本地存储在
whitelist.json 中
- MongoDB:适用于大型服务器或共享数据设置;在
config.yml 中配置连接 URL
你可以通过更改配置文件中的 database.type 并重启来随时切换后端。

插件 API
在你的插件中使用 WhitelistAPI
mWL 公开了 WhitelistAPI,以便其他插件可以在不接触内部服务的情况下添加、移除和查询白名单条目。
在你的 plugin.yml 中将 mWL 添加为 depend(或 softdepend),以确保其优先加载:
depend: [mWL]
通过 Bukkit 的 ServicesManager 获取 API:
RegisteredServiceProvider<WhitelistAPI> provider =
Bukkit.getServicesManager().getRegistration(WhitelistAPI.class);
if (provider == null) return; // mWL not installed
WhitelistAPI whitelistApi = provider.getProvider();
或者,如果你的用例允许直接依赖 mWL 的类:
WhitelistAPI whitelistApi = MWhitelist.getAPI();
添加、移除、检查
UUID uuid = player.getUniqueId();
whitelistApi.addPlayer(uuid, player.getName());
whitelistApi.addPlayerTemp(uuid, player.getName(), Duration.ofDays(7).toMillis());
whitelistApi.isWhitelisted(uuid);
whitelistApi.removePlayer(uuid);
whitelistApi.setPlayerTemp(uuid, Duration.ofHours(12).toMillis()); // 覆盖过期时间
whitelistApi.extendPlayerTemp(uuid, Duration.ofHours(12).toMillis()); // 在当前过期时间基础上增加
基于名称的重载方法会自动解析玩家的真实 Mojang UUID。由于这可能会调用 Mojang API,因此它会在调用线程之外运行并返回一个 CompletableFuture:
whitelistApi.addPlayer("Notch").thenAccept(success -> { /* ... */ });
读取条目
Optional<WhitelistEntry> entry = whitelistApi.getEntry(uuid);
entry.ifPresent(e -> {
e.getUuid();
e.getName();
e.getAddedAt(); // 纪元毫秒
e.getExpiresAt(); // 纪元毫秒,仅在 !isPermanent() 时有意义
e.isPermanent();
});
List<WhitelistEntry> all = whitelistApi.getAll();
int size = whitelistApi.getWhitelistSize();
开启/关闭白名单
whitelistApi.isWhitelistEnabled();
whitelistApi.setWhitelistEnabled(true);
监听事件
所有事件均位于 me.truec0der.mwhitelist.api.event 包中,并在主线程上触发:
| 事件 |
触发时机 |
PlayerWhitelistAddEvent |
玩家被添加(永久或临时)。可取消 |
PlayerWhitelistRemoveEvent |
玩家被移除。可取消 |
PlayerWhitelistExpiredEvent |
临时条目过期。不可取消 |
WhitelistStatusChangeEvent |
白名单状态切换(开/关)。可取消 |
@EventHandler
public void onAdd(PlayerWhitelistAddEvent event) {
getLogger().info(event.getName() + " was whitelisted (temp: " + event.isTemp() + ")");
}

要求
- Minecraft: 1.18.x+(兼容 1.18.x 至 1.21.x 以及 Paper 26.2)
- 服务器: Paper、Spigot、Bukkit 或 Paper 分支(如 Purpur 等)
- Java: 17+(Paper 26.x 需要 Java 25+)
致谢
原始插件: mWL,由 TRUEC0DER 开发
这是一个更新后的分支版本,已与原作者协调并获得认可,因为原始插件现已进入生命周期结束(EOL)阶段,不再维护。此分支增加了错误修复、更广泛的版本兼容性(1.18.x 至 26.2),并为现代 Paper、Spigot 和 Bukkit 服务器添加了额外功能。
许可证
本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

Overview
mWL is a whitelist plugin for Paper, Spigot, and Bukkit servers. It gives you full control over who can join, with temporary whitelist entries, permission-based bypass, and a choice of MongoDB or JSON storage. It runs on anything from 1.18.x up to Paper 26.2.
Note: mWL requires your server to run in online-mode (premium/licensed accounts). Offline/cracked UUIDs are not supported.
Useful for private servers, whitelisted communities, or any server that needs more control than vanilla's built-in whitelist.

Features
| Feature |
Description |
| Temporary Whitelist |
Add players for a limited time, removed automatically on expiry |
| Bypass Permission |
Let staff or VIPs join regardless of whitelist status |
| Dual Database Support |
Store players in JSON (no setup) or MongoDB |
| Expiry Notifications |
Warn players when their whitelist time is about to run out |
| Auto-kick on Remove |
Optionally kick online players when removed from the whitelist |
| Reload Support |
Reload config and language files without restarting |
| Permission System |
Fine-grained access control for every command |
| Addon API |
Public WhitelistAPI (MWhitelist.getAPI() or Bukkit's ServicesManager), plus custom events for other plugins to hook into |
| Privacy-Focused |
Optional bStats metrics, can be disabled in config |
Also lightweight, with async database operations so lookups don't freeze the server, and works with LuckPerms and other permission plugins out of the box.

Configuration
Some of what you can configure:
- Whitelist on/off toggle, via command or config
- Temporary whitelist with flexible time syntax (e.g.
1d12h30m)
- Permission bypass, assignable via any permission plugin
- Periodic player check with configurable interval
- Expiry notify threshold
- MongoDB connection settings
- bStats metrics toggle (
enableMetrics: true/false)
whitelist:
status: false # Whitelist enabled
remove-on-expired: false # Remove player from database on join if their time has expired
kick-on-remove: false # Kick player from server when removed from the whitelist via command
bypass:
permission:
enabled: true # Enable bypass via permission
permission: mwl.whitelist.bypass
player-check: # Periodically re-checks online players and kicks them if no longer whitelisted or expired
enabled: false
delay: 60000 # Milliseconds between checks
expired-notify: # Warns a player once their remaining time drops below expired-notify.time
enabled: true
time: 86400000 # Milliseconds before expiry
database:
type: JSON # JSON or MONGO

Commands & Permissions
Commands
| Command |
Description |
/mwl add <player> |
Add a player to the whitelist |
/mwl remove <player> |
Remove a player from the whitelist |
/mwl addtemp <player> <time> |
Add a player temporarily |
/mwl settemp <player> <time> |
Set expiry time for an existing player |
/mwl extendtemp <player> <time> |
Extend a player's remaining time |
/mwl check <player> |
Check if a player is whitelisted |
/mwl list |
List all whitelisted players |
/mwl toggle [enable|disable] |
Toggle or set whitelist status |
/mwl info |
Show plugin information |
/mwl reload |
Reload config and language files |
/mwl help |
Show help overview |
Permissions
mwl.command.add: add players
mwl.command.remove: remove players
mwl.command.addtemp: add temporary players
mwl.command.settemp: set expiry time
mwl.command.extendtemp: extend expiry time
mwl.command.check: check whitelist status
mwl.command.list: list whitelisted players
mwl.command.toggle: toggle whitelist
mwl.command.info: view plugin info
mwl.command.reload: reload config
mwl.command.help: view help
mwl.whitelist.bypass: bypass whitelist check entirely

Database Support
mWL supports two storage backends:
- JSON (default): zero setup, stores data locally in
whitelist.json
- MongoDB: for larger servers or shared data setups; configure the connection URL in
config.yml
You can switch between backends at any time by changing database.type in the config and restarting.

Addon API
Using the WhitelistAPI in your own plugin
mWL exposes a public WhitelistAPI so other plugins can add, remove, and query whitelist entries without touching internal services.
Add mWL as a depend (or softdepend) in your plugin.yml so it's guaranteed to be loaded first:
depend: [mWL]
Get the API through Bukkit's ServicesManager:
RegisteredServiceProvider<WhitelistAPI> provider =
Bukkit.getServicesManager().getRegistration(WhitelistAPI.class);
if (provider == null) return; // mWL not installed
WhitelistAPI whitelistApi = provider.getProvider();
Or, if a hard dependency on mWL's classes is fine for your use case:
WhitelistAPI whitelistApi = MWhitelist.getAPI();
Adding, removing, checking
UUID uuid = player.getUniqueId();
whitelistApi.addPlayer(uuid, player.getName());
whitelistApi.addPlayerTemp(uuid, player.getName(), Duration.ofDays(7).toMillis());
whitelistApi.isWhitelisted(uuid);
whitelistApi.removePlayer(uuid);
whitelistApi.setPlayerTemp(uuid, Duration.ofHours(12).toMillis()); // overwrite expiry
whitelistApi.extendPlayerTemp(uuid, Duration.ofHours(12).toMillis()); // add to current expiry
The name-based overloads resolve the player's real Mojang UUID for you. This can call the Mojang API, so it runs off the calling thread and returns a CompletableFuture:
whitelistApi.addPlayer("Notch").thenAccept(success -> { /* ... */ });
Reading entries
Optional<WhitelistEntry> entry = whitelistApi.getEntry(uuid);
entry.ifPresent(e -> {
e.getUuid();
e.getName();
e.getAddedAt(); // epoch millis
e.getExpiresAt(); // epoch millis, only meaningful if !isPermanent()
e.isPermanent();
});
List<WhitelistEntry> all = whitelistApi.getAll();
int size = whitelistApi.getWhitelistSize();
Whitelist on/off
whitelistApi.isWhitelistEnabled();
whitelistApi.setWhitelistEnabled(true);
Listening to events
All events live in me.truec0der.mwhitelist.api.event and fire on the main thread:
| Event |
Fired when |
PlayerWhitelistAddEvent |
A player is added (permanently or temporarily). Cancellable |
PlayerWhitelistRemoveEvent |
A player is removed. Cancellable |
PlayerWhitelistExpiredEvent |
A temp entry expires. Not cancellable |
WhitelistStatusChangeEvent |
The whitelist is toggled on/off. Cancellable |
@EventHandler
public void onAdd(PlayerWhitelistAddEvent event) {
getLogger().info(event.getName() + " was whitelisted (temp: " + event.isTemp() + ")");
}

Requirements
- Minecraft: 1.18.x+ (compatible with 1.18.x through 1.21.x and Paper 26.2)
- Server: Paper, Spigot, Bukkit, or Paper forks (Purpur, etc.)
- Java: 17+ (Java 25+ required for Paper 26.x)
Credits
Original Plugin: mWL by TRUEC0DER
This is an updated fork, coordinated with and known to the original author, since the original plugin is now EOL (end of life) and no longer maintained. This fork adds bug fixes, broader version compatibility (1.18.x through 26.2), and additional features for modern Paper, Spigot, and Bukkit servers.
License
This project is licensed under the MIT License. See the LICENSE file for details.
评论 0
登录后参与评分
还没有评论,来抢沙发吧