EvenBetterWhitelist - 插件
适用于 Minecraft Paper 1.21.x 的现代白名单系统,支持 Discord 集成。当玩家尝试加入服务器且未被列入白名单时,系统会将结构化的请求发布到您的 Discord 频道。管理员可以直接在 Discord 中使用按钮接受、拒绝或封禁请求。
安装步骤
- 将
WhitelistPluginButBetter-1.0.0.jar 放入服务器的 plugins/ 文件夹中
- 启动/重启您的服务器
- 编辑
plugins/WhitelistPluginButBetter/config.yml
- 下载 GeoLite2-City.mmdb 并将其放置在插件文件夹中
- 使用
/wlp reload 重新加载配置或重启服务器
? Discord Bot 设置
1. 创建 Discord 应用程序
- 前往 Discord Developer Portal
- 点击“New Application”并为其命名
- 进入“Bot”部分并点击“Add Bot”
- 复制 Bot Token(请保密!)
- 启用以下 Privileged Gateway Intents:
2. 邀请 Bot
- 进入“OAuth2” → “URL Generator”
- 选择作用域:
bot, applications.commands
- 选择权限:
Send Messages, Embed Links, Read Message History
- 复制生成的 URL 并打开它以邀请 bot
3. 获取您的 ID
在 Discord 中启用开发者模式(设置 → 高级 → 开发者模式)
- Server ID:右键点击您的服务器 → 复制服务器 ID
- Channel ID:右键点击该频道 → 复制频道 ID
- Admin User ID:右键点击自己 → 复制用户 ID
4. (可选)创建 Webhook
- 右键点击您的频道 → 编辑频道
- 进入 Integrations → Webhooks
- 创建一个 webhook 并复制其 URL
⚙️ 配置
discord:
bot-token: "YOUR_BOT_TOKEN_HERE"
webhook-url: "YOUR_WEBHOOK_URL_HERE"
server-id: "YOUR_SERVER_ID_HERE"
channel-id: "YOUR_CHANNEL_ID_HERE"
admin-user-ids: "USER_ID_1,USER_ID_2"
ping-admins: true
cooldowns:
deny-cooldown: 60 # 被拒绝的玩家再次尝试之前的分钟数
pending-cooldown: 5 # 等待期间两次加入尝试之间的分钟数
ip-cooldown: 10 # 同一 IP 发起新请求之前的分钟数
geoip:
enabled: true
database-path: "plugins/WhitelistPluginButBetter/GeoLite2-City.mmdb"
查看所有选项请参阅完整的 config.yml!
? 命令
| 命令 |
描述 |
/wlp accept <player> |
接受待处理的白名单请求 |
/wlp deny <player> |
拒绝待处理的白名单请求 |
/wlp pending |
查看所有待处理请求 |
/wlp list [page] |
查看已列入白名单的玩家 |
/wlp add <player> |
手动将玩家添加到白名单 |
/wlp remove <player> |
从白名单中移除玩家 |
/wlp info <player> |
查看玩家详细信息 |
/wlp status |
查看插件状态 |
/wlp reload |
重新加载配置 |
? 权限
| 权限 |
描述 |
默认值 |
whitelistplugin.admin |
访问所有命令 |
OP |
whitelistplugin.bypass |
绕过白名单检查 |
OP |
Discord Embed 预览
当玩家尝试加入时,管理员会收到如下嵌入消息:
┌─────────────────────────────────────────┐
│ New Whitelist Request │
├─────────────────────────────────────────┤
│ Player: Steve │
│ UUID: 069a79f4-... │
│ IP: ||192.168.1.1|| │
│ Location: New York, United States │
│ Client: fabric │
│ Language: en_US │
│ Requested: 2024-01-15 14:30 UTC │
│ │
│ Same IP as: Alex (1 other request) │
│ │
│ [Accept] [Deny] [Ban] │
└─────────────────────────────────────────┘
?️ 文件结构
plugins/WhitelistPluginButBetter/
├── config.yml # 主配置文件
├── whitelist.json # 白名单玩家
├── pending-requests.json # 待处理请求
├── denied-players.json # 被拒绝的玩家(用于冷却时间)
├── requests.log # 操作日志
└── GeoLite2-City.mmdb # GeoIP 数据库(需自行提供)
故障排除
Bot 对按钮无响应?
- 确保 Bot Token 正确
- 确保 Bot 在该频道拥有权限
- 检查控制台是否有连接错误
GeoIP 不工作?
- 从 MaxMind 下载 GeoLite2-City.mmdb
- 将其放置在插件文件夹中
- 检查 config.yml 中的路径
玩家未被踢出?
- 确保插件已加载(执行
/plugins)
- 检查玩家是否拥有
whitelistplugin.bypass 权限
- 查看控制台是否有错误
看到私有 IP(10.x.x.x, 192.168.x.x)?
当使用 反向代理(BungeeCord, Velocity, TCPShield 等)时会发生这种情况。
对于 BungeeCord:
- 在
spigot.yml 中设置 bungeecord: true
- 重启服务器
对于 Velocity:
- 编辑
config/paper-global.yml
- 设置
proxies.velocity.enabled: true
- 将
secret 设置为与 Velocity 的转发密钥匹配
- 重启服务器
对于 TCPShield/其他:
请遵循您所用代理的文档进行 IP 转发。
客户端/语言显示为“N/A(登录前)”?
这是预期行为!插件会在玩家完全连接之前进行拦截,因此此时客户端品牌和区域设置数据尚不可用。这是 Minecraft 的局限性,并非错误。
我们确实捕获的数据(IP、UUID、GeoIP 地理位置)对于识别玩家及其小号仍然非常有用!
? 许可证
保留所有权利。未经告知的任何修改均属非法。
专为 Minecraft 社区打造!
EvenBetterWhitelist - Plugin
A modern whitelist system for Minecraft Paper 1.21.x with Discord integration. When a player attempts to join and is not whitelisted, a structured request is posted to your Discord channel. Admins can accept, deny, or ban directly from Discord using buttons.
Installation Steps
- Place
WhitelistPluginButBetter-1.0.0.jar in your server's plugins/ folder
- Start/restart your server
- Edit
plugins/WhitelistPluginButBetter/config.yml
- Download GeoLite2-City.mmdb and place it in the plugin folder
- Reload with
/wlp reload or restart the server
? Discord Bot Setup
1. Create a Discord Application
- Go to Discord Developer Portal
- Click "New Application" and give it a name
- Go to "Bot" section and click "Add Bot"
- Copy the Bot Token (keep this secret!)
- Enable these Privileged Gateway Intents:
2. Invite the Bot
- Go to "OAuth2" → "URL Generator"
- Select scopes:
bot, applications.commands
- Select permissions:
Send Messages, Embed Links, Read Message History
- Copy the generated URL and open it to invite the bot
3. Get Your IDs
Enable Developer Mode in Discord (Settings → Advanced → Developer Mode)
- Server ID: Right-click your server → Copy Server ID
- Channel ID: Right-click the channel → Copy Channel ID
- Admin User ID: Right-click yourself → Copy User ID
4. (Optional) Create a Webhook
- Right-click your channel → Edit Channel
- Go to Integrations → Webhooks
- Create a webhook and copy the URL
⚙️ Configuration
discord:
bot-token: "YOUR_BOT_TOKEN_HERE"
webhook-url: "YOUR_WEBHOOK_URL_HERE"
server-id: "YOUR_SERVER_ID_HERE"
channel-id: "YOUR_CHANNEL_ID_HERE"
admin-user-ids: "USER_ID_1,USER_ID_2"
ping-admins: true
cooldowns:
deny-cooldown: 60 # Minutes before denied player can try again
pending-cooldown: 5 # Minutes between join attempts while pending
ip-cooldown: 10 # Minutes before same IP can make new request
geoip:
enabled: true
database-path: "plugins/WhitelistPluginButBetter/GeoLite2-City.mmdb"
See the full config.yml for all options!
? Commands
| Command |
Description |
/wlp accept <player> |
Accept a pending whitelist request |
/wlp deny <player> |
Deny a pending whitelist request |
/wlp pending |
View all pending requests |
/wlp list [page] |
View whitelisted players |
/wlp add <player> |
Manually add a player to whitelist |
/wlp remove <player> |
Remove a player from whitelist |
/wlp info <player> |
View detailed player info |
/wlp status |
View plugin status |
/wlp reload |
Reload configuration |
? Permissions
| Permission |
Description |
Default |
whitelistplugin.admin |
Access to all commands |
OP |
whitelistplugin.bypass |
Bypass whitelist check |
OP |
Discord Embed Preview
When a player tries to join, admins receive an embed like this:
┌─────────────────────────────────────────┐
│ New Whitelist Request │
├─────────────────────────────────────────┤
│ Player: Steve │
│ UUID: 069a79f4-... │
│ IP: ||192.168.1.1|| │
│ Location: New York, United States │
│ Client: fabric │
│ Language: en_US │
│ Requested: 2024-01-15 14:30 UTC │
│ │
│ Same IP as: Alex (1 other request) │
│ │
│ [Accept] [Deny] [Ban] │
└─────────────────────────────────────────┘
?️ File Structure
plugins/WhitelistPluginButBetter/
├── config.yml # Main configuration
├── whitelist.json # Whitelisted players
├── pending-requests.json # Pending requests
├── denied-players.json # Denied players (for cooldowns)
├── requests.log # Action log
└── GeoLite2-City.mmdb # GeoIP database (you provide this)
Troubleshooting
Bot not responding to buttons?
- Make sure the bot token is correct
- Ensure the bot has permissions in the channel
- Check console for connection errors
GeoIP not working?
- Download GeoLite2-City.mmdb from MaxMind
- Place it in the plugin folder
- Check the path in config.yml
Players not being kicked?
- Make sure the plugin is loaded (
/plugins)
- Check if player has
whitelistplugin.bypass permission
- Look for errors in console
Seeing Private IP (10.x.x.x, 192.168.x.x)?
This happens when using a reverse proxy (BungeeCord, Velocity, TCPShield, etc.)
For BungeeCord:
- Set
bungeecord: true in spigot.yml
- Restart the server
For Velocity:
- Edit
config/paper-global.yml
- Set
proxies.velocity.enabled: true
- Set the
secret to match Velocity's forwarding secret
- Restart the server
For TCPShield/Other:
Follow your proxy's documentation for IP forwarding.
Client/Language shows "N/A (Pre-login)"?
This is expected! The plugin intercepts players before they fully connect, so client brand and locale data isn't available yet. This is a Minecraft limitation, not a bug.
The data we DO capture (IP, UUID, GeoIP location) is still very useful for identifying players and alts!
? License
All Rights Reserved.Any modifications without informing is illegal.
Made for the Minecraft community!
评论 0
登录后参与评分
还没有评论,来抢沙发吧