EmpireBan
你的服务器。你的规则。
一个可配置的封禁/静音/踢出系统,具备递增的处罚 ID、员工备注、带有违规积分的智能聊天过滤器、通过 IP 检测小号账号,以及 VPN/代理检查功能——适用于 Spigot/Paper、BungeeCord 和 Velocity,打包为单个 JAR 文件。
Features
| 特性 |
说明 |
| Ban/Mute/Kick/Warn |
完整的惩罚系统,支持按玩家记录历史。 |
| 可配置的升级 ID |
定义任意数量的命名处罚原因(ids.yml),每个原因都有各自的升级等级——初次违规、二次违规等,直到耗尽最严厉的已配置等级为止。 |
| 小号检测 |
标记或由自动封禁从当前被封禁玩家的 IP 加入的玩家。 |
| VPN/代理/Tor 检查 |
可选的加入时通过 vpnapi.io 进行查询。 |
| 聊天过滤器与慢速模式 |
屏蔽黑名单中的词汇/链接并强制执行可配置的聊天延迟,两者均具有绕过权限。 |
| 智能内容过滤器 |
捕获象形文字(如 sh1t)和带重音的拼写,匹配整个单词以确保 ass 不会命中 class,支持正则表达式、单字权重、本地词文件和远程词表。检查聊天、命令以及(在 Spigot 上)告示牌。 |
| 违规积分 |
每次匹配都获得积分,积分会随时间衰减。stages.yml 中的阶段会自动发出警告、静音或封禁,或执行控制台命令。 |
| 命令拦截器 |
可选的命令允许和禁止列表,包括命名空间形式如 minecraft:op。 |
| 工作人员备注 |
/note <player> <text>(或 /ban note ...)留下内部备注,该备注会在 /history 中显示。 |
| 导出 |
/bansystem export 将处罚、日志、备注或过滤器违规情况以 JSON 或 CSV 格式写入,可选择限制为最近 N 天。IP 地址永远不会被导出。 |
| 导入 |
/bansystem import 接管 LiteBans、AdvancedBan(均通过 MySQL)和原版封禁列表中的封禁、静音、踢出、警告和备注,首先进行试运行。 |
| Redis 同步 |
可选。一个代理上的封禁会在一秒内将所有其他代理上的玩家踢下线。/bansystem sync 显示状态。 |
| 配置升级 |
更新时新选项会添加到您的 config.yml 中,附带注释,且不会触碰您更改的任何内容。保留 config.yml.bak 备份文件。 |
| 真正有效的静音 |
被静音的玩家也被禁止使用 /me 和私聊命令,可按命令名称进行配置。 |
| 仅 ID 模式 |
选择性地拒绝 /ban 和 /mute 上的自由持续时间,使每次处罚都通过配置的 ID 进行——管理员可选择退出。 |
| MySQL 或 SQLite |
HikariCP 池化的 MySQL,或默认零配置的 SQLite。 |
| 操作日志 |
每条处罚和解封都被记录,可在游戏内查看和清除。 |
| Discord Webhook |
每条封禁、静音、踢出、解封和解除静音都会发布到 Discord 频道,可选择按动作过滤。 |
| PlaceholderAPI |
%empireban_points%、%empireban_stage%、%empireban_muted% 和 %empireban_mute_remaining%(Spigot,可选)。 |
| 英文和德文 |
插件自带两种语言的消息文件;通过 language: german 切换。 |
| 单个跨平台 JAR |
一个 EmpireBan.jar —— 每个平台仅读取其自身的入口点并忽略其余部分。 |
依赖项
- Spigot / Paper、BungeeCord 或 Velocity -
必需 (仅选择一项,取决于你运行的平台)
- vpnapi.io -
可选 - vpnapi.io (免费套餐:每天最多 100 次查询)
- PlaceholderAPI -
可选 (仅限 Spigot)
- Redis -
可选 (仅用于多个代理服务器之间的同步)
工作原理
EmpireBan 作为一个包含所有三个平台集成的单个 JAR 文件分发。加载时,每个平台仅读取其自身的入口点——Spigot 读取 plugin.yml,BungeeCord 读取 bungee.yml,Velocity 读取带有 @Plugin 注解的类——而 JAR 文件的其余部分将被忽略。
代理设置: 仅在代理(Velocity 或 BungeeCord)上安装此 JAR 文件,不要同时安装在 Spigot 后端服务器上。它仅适用于没有前置代理的纯独立 Spigot 服务器环境。
处罚围绕 ID 组织——即像 griefing(破坏)或 cheating(作弊)这样命名且可复用的理由——每个 ID 都带有一个有序的高级别列表。玩家在给定 ID 下的第 N 次处罚将应用该 ID 的第 N 个级别(一旦所有级别都被使用过,则限制在最后一个级别),因此第一次违规可能是警告,第二次是禁言,第三次是封禁——每个 ID 均可完全自定义配置。/ban 和 /mute 命令均执行相同的高级逻辑并报告实际应用的处罚,因此即使通过 /mute 发出,如果某个 ID 的下一个级别是封禁,它也会执行封禁(并踢出玩家)。
加入游戏时,EmpireBan 会将连接玩家的 IP 与当前被封禁的玩家进行比对,并根据配置选择仅通知工作人员或自动封禁该小号账号。如果启用了 VPN 检查,它还会向 vpnapi.io 查询该 IP 是否使用了 VPN/代理/Tor。
配置
带有完整注释的文件位于 代码仓库(config.yml、stages.yml)。
点击展开 config.yml 键值
version: 2
language: english
database:
type: sqlite
mysql:
host: localhost
port: 3306
database: empireban
username: root
password: ''
use-ssl: false
ip-handling:
autoban: false
notify-staff: true
vpn-check:
enabled: false
api-key: ''
autoban: false
chat-filter:
enabled: true
blacklist:
- 'discord.gg/'
- 'http://'
- 'https://'
chat-delay:
seconds: 3
discord-webhook:
enabled: false
url: ''
username: 'EmpireBan'
actions: []
geyser:
support: true
mute-command-blacklist:
enabled: true
list:
- 'me'
- 'msg'
- 'tell'
- 'w'
- 'whisper'
- 'r'
- 'reply'
punishments:
require-id: false
admin-bypass: true
signed-chat-bypass: true
content-filter:
enabled: true
check-chat: true
check-commands: true
check-signs: true
leet-speak-detection: true
unicode-normalization: true
whole-words-only: true
default-weight: 10
words: []
remote-lists: []
regex: []
custom-weights: {}
replace-word-with: '***'
auto-update:
enabled: true
interval-minutes: 60
points:
enabled: true
decay-enabled: true
decay-after-minutes: 30
decay-amount: 5
reset-on-mute: true
command-blocker:
enabled: false
list: []
remote-lists: []
whitelist: []
redis:
enabled: false
host: localhost
port: 6379
username: ''
password: ''
ssl: false
channel: empireban
server-id: ''
import:
litebans:
host: localhost
port: 3306
database: litebans
username: root
password: ''
table-prefix: litebans_
advancedban:
host: localhost
port: 3306
database: advancedban
username: root
password: ''
点击展开默认 stages.yml
stages:
1:
points-threshold: 10
action: warn
2:
points-threshold: 30
action: warn
3:
points-threshold: 60
action: mute
mute-duration: 1800
4:
points-threshold: 120
action: mute
mute-duration: 86400
5:
points-threshold: 200
action: ban
ban-duration: 0
ban-reason: 'Repeated chat violations'
ids.yml 包含可配置的升级 ID 系统,而 messages_english.yml 包含所有面向玩家和工作人员的提示信息(通过 & 使用颜色代码,支持占位符)。在首次启动时,这两个文件会从 JAR 包复制到数据文件夹。该结构支持额外的 messages_<language>.yml 文件,以便你翻译面向玩家的提示信息。
持续时间在内部始终以秒为单位存储:1 天 = 86400,1 年 = 31536000,-1 = 永久。命令还接受简写形式,如 1d12h、30m、perm。
命令与权限
| 命令 |
权限 |
/bansystem (别名 /bansys) |
bansys.bansys |
/bansystem reload |
bansys.reload |
/bansystem export <punishments|logs|notes|violations> <json|csv> [timespan] |
bansys.export |
/bansystem import <litebans|advancedban|vanilla> [confirm] |
bansys.import |
/bansystem sync |
bansys.sync |
/bansystem ids create <id> <type> <onlyAdmins> <duration> <reason> |
bansys.ids.create |
/bansystem ids delete <id> |
bansys.ids.delete |
/bansystem ids edit <id> add lvl <lvl> <duration> <type> |
bansys.ids.addlvl |
/bansystem ids edit <id> remove lvl <lvl> |
bansys.ids.removelvl |
/bansystem ids edit <id> set lvlduration <lvl> <duration> |
bansys.ids.setduration |
/bansystem ids edit <id> set lvltype <lvl> <type> |
bansys.ids.settype |
/bansystem ids edit <id> set onlyadmins <true/false> |
bansys.ids.setonlyadmins |
/bansystem ids edit <id> set reason <reason> |
bansys.ids.setreason |
/bansystem ids show [id] |
bansys.ids.show |
/bansys logs show [page] |
bansys.logs.show |
/bansys logs clear |
bansys.logs.clear |
/ban <player> <id|duration> [reason] |
bansys.ban.<id> / bansys.ban.all / bansys.ban.admin |
/unban <player> [reason] |
bansys.unban |
/mute <player> <id|duration> [reason] |
bansys.ban.<id> / bansys.ban.all |
/unmute <player> [reason] |
bansys.unmute |
/kick <player> [reason] |
bansys.kick (绕过:bansys.kick.bypass) |
/check <player> |
bansys.check |
/history <player> |
bansys.history.show |
/deletehistory <player> |
bansys.history.delete |
/note <player> <text>, /ban note <player> <text> |
bansys.note |
/note remove <id> |
bansys.note.remove |
/chatfilter info <player> (别名 /cf) |
bansys.filter |
/chatfilter history <player> [page], lookup <id>, resetpoints <player> |
bansys.filter |
/chatfilter addword <word> [weight], removeword, listwords |
bansys.filter |
/chatfilter addcmd <command>, removecmd, listcmds |
bansys.filter |
/chatfilter test <text>, stats, update |
bansys.filter |
| - |
bansys.notify (接收副账号/VPN 工作人员警报) |
| - |
bansys.bypasschatfilter |
| - |
bansys.bypasschatdelay |
| - |
bansys.bypasscommands (豁免命令拦截器) |
| - |
bansys.ban.bypass (抑制封禁时的踢出操作) |
| - |
bansys.ban.admin (当 punishments.require-id 开启时,也可使用自由时长) |
已知限制
- 封禁列表没有 GUI 菜单——仅支持命令驱动。
- 签名聊天(Minecraft 1.19.1+)无法被 BungeeCord/Velocity 单独拦截——这需要在每个后端服务器上安装配套的 Spigot 聊天适配器(
config.yml: signed-chat-bypass),目前该适配器尚未打包在内。
- BungeeCord 无法将修改后的聊天消息传递给后端服务器。内容过滤器会拦截的内容将被直接阻止,并显示常规通知。Velocity 和 Spigot/Paper 则进行就地过滤。
- 内容过滤器的标语检查仅在 Spigot/Paper 上存在,代理服务器不会看到标语。
- LiteBans 和 AdvancedBan 只能从 MySQL 导入。它们的默认存储(H2 和 HSQLDB)是文件形式的,因此请先将其移至 MySQL。
- Redis 仅传递封禁通知。所有代理服务器必须共享同一个 MySQL 数据库,以便其他组件能够找到它。
- Geyser 支持仅限于
geyser.support 配置标志;除此之外没有原生的 Geyser 特定行为。
入门指南
- 将
EmpireBan.jar 放入你的 plugins/ 文件夹——如果你运行代理服务器(Velocity/BungeeCord),仅放置在代理端,否则放置在 Spigot 服务器上。
- 启动服务器一次以生成
config.yml、ids.yml、stages.yml 和 messages_english.yml。
- 设置你的数据库(默认为 SQLite,或 MySQL),如果需要的话启用 VPN 检查。
- 使用
/bansystem reload 重新加载——无需重启服务器。
致谢
内容过滤器、违规积分和命令拦截器源自 GigaProtect,现已合并至 EmpireBan。
Discord: dc.gg/paperstream
在 GNU 通用公共许可证 v3.0 下开源。
EmpireBan
Your server. Your rules.
A configurable ban/mute/kick system with escalating punishment IDs, staff notes, a smart chat filter with violation points, alt-account detection via IP, and VPN/proxy checking - for Spigot/Paper, BungeeCord, and Velocity, shipped as a single JAR.
Features
| Feature |
Description |
| Ban/Mute/Kick/Warn |
Full punishment system with per-player history. |
| Configurable Escalation IDs |
Define any number of named punishment reasons (ids.yml), each with its own escalation levels - 1st offense, 2nd offense, and so on, capped at the harshest configured level once exhausted. |
| Alt-Account Detection |
Flags staff or auto-bans players who join from the IP of a currently banned player. |
| VPN/Proxy/Tor Check |
Optional lookup via vpnapi.io on join. |
| Chat Filter & Slowmode |
Blacklist words/links and enforce a configurable chat delay, both with bypass permissions. |
| Smart Content Filter |
Catches leet speak (sh1t) and accented spellings, matches whole words so ass never hits class, supports regular expressions, per-word weights, local word files and remote word lists. Checks chat, commands and (on Spigot) signs. |
| Violation Points |
Every match is worth points that decay over time. Stages in stages.yml warn, mute or ban automatically, or run console commands. |
| Command Blocker |
Optional block and allow lists for commands, namespaced forms like minecraft:op included. |
| Staff Notes |
/note <player> <text> (or /ban note ...) leaves an internal note that shows up in /history. |
| Export |
/bansystem export writes punishments, logs, notes or filter violations as JSON or CSV, optionally limited to the last N days. IP addresses are never exported. |
| Import |
/bansystem import takes over bans, mutes, kicks, warnings and notes from LiteBans, AdvancedBan (both via MySQL) and the vanilla ban lists, with a dry run first. |
| Redis Sync |
Optional. A ban on one proxy throws the player off every other proxy within a second. /bansystem sync shows the state. |
| Config Upgrades |
New options are added to your config.yml on update, with their comments, and nothing you changed is touched. A config.yml.bak is kept. |
| Mutes That Actually Hold |
Muted players are also kept off /me and the private message commands, configurable per command name. |
| ID-Only Mode |
Optionally refuse free durations on /ban and /mute so every punishment goes through a configured ID - with an opt-out for admins. |
| MySQL or SQLite |
HikariCP-pooled MySQL, or zero-config SQLite by default. |
| Action Logs |
Every punishment and revocation is logged, viewable and clearable in-game. |
| Discord Webhook |
Every ban, mute, kick, unban and unmute posted to a Discord channel, optionally filtered by action. |
| PlaceholderAPI |
%empireban_points%, %empireban_stage%, %empireban_muted% and %empireban_mute_remaining% (Spigot, optional). |
| English and German |
Both message files ship with the plugin; switch with language: german. |
| Single Cross-Platform JAR |
One EmpireBan.jar - each platform only reads its own entry point and ignores the rest. |
Dependencies
- Spigot / Paper, BungeeCord, or Velocity -
required (exactly one, depending on where you run it)
- vpnapi.io -
optional - vpnapi.io (free tier: up to 100 lookups/day)
- PlaceholderAPI -
optional (Spigot only)
- Redis -
optional (only for the sync between several proxies)
How It Works
EmpireBan ships as a single JAR containing all three platform integrations. On load, each platform only reads its own entry point - Spigot reads plugin.yml, BungeeCord reads bungee.yml, Velocity reads the @Plugin-annotated class - and the rest of the JAR is ignored.
Proxy setups: install the JAR only on the proxy (Velocity or BungeeCord), not on the Spigot backend servers as well. It only belongs on a Spigot server in a pure standalone setup with no proxy in front.
Punishments are organized around IDs - named, reusable reasons like griefing or cheating - each with an ordered list of escalation levels. A player's Nth punishment under a given ID applies that ID's Nth level (capped at the last level once every level has been used), so a first offense might warn, a second mute, and a third ban - fully configurable per ID. /ban and /mute both run the same escalation and report the punishment that was actually applied, so an ID whose next level is a ban bans (and kicks) even when it was handed out via /mute.
On join, EmpireBan checks the connecting player's IP against currently banned players and, depending on config, either just notifies staff or automatically bans the alt account too. If VPN checking is enabled, it also queries vpnapi.io for VPN/proxy/Tor usage on that IP.
Configuration
The fully commented files are in the repository (config.yml, stages.yml).
Click to expand the config.yml keys
version: 2
language: english
database:
type: sqlite
mysql:
host: localhost
port: 3306
database: empireban
username: root
password: ''
use-ssl: false
ip-handling:
autoban: false
notify-staff: true
vpn-check:
enabled: false
api-key: ''
autoban: false
chat-filter:
enabled: true
blacklist:
- 'discord.gg/'
- 'http://'
- 'https://'
chat-delay:
seconds: 3
discord-webhook:
enabled: false
url: ''
username: 'EmpireBan'
actions: []
geyser:
support: true
mute-command-blacklist:
enabled: true
list:
- 'me'
- 'msg'
- 'tell'
- 'w'
- 'whisper'
- 'r'
- 'reply'
punishments:
require-id: false
admin-bypass: true
signed-chat-bypass: true
content-filter:
enabled: true
check-chat: true
check-commands: true
check-signs: true
leet-speak-detection: true
unicode-normalization: true
whole-words-only: true
default-weight: 10
words: []
remote-lists: []
regex: []
custom-weights: {}
replace-word-with: '***'
auto-update:
enabled: true
interval-minutes: 60
points:
enabled: true
decay-enabled: true
decay-after-minutes: 30
decay-amount: 5
reset-on-mute: true
command-blocker:
enabled: false
list: []
remote-lists: []
whitelist: []
redis:
enabled: false
host: localhost
port: 6379
username: ''
password: ''
ssl: false
channel: empireban
server-id: ''
import:
litebans:
host: localhost
port: 3306
database: litebans
username: root
password: ''
table-prefix: litebans_
advancedban:
host: localhost
port: 3306
database: advancedban
username: root
password: ''
Click to expand the default stages.yml
stages:
1:
points-threshold: 10
action: warn
2:
points-threshold: 30
action: warn
3:
points-threshold: 60
action: mute
mute-duration: 1800
4:
points-threshold: 120
action: mute
mute-duration: 86400
5:
points-threshold: 200
action: ban
ban-duration: 0
ban-reason: 'Repeated chat violations'
ids.yml holds the configurable escalation-ID system, and messages_english.yml holds every player- and staff-facing message (color codes via &, placeholders). Both are copied into the data folder from the JAR on first start. The structure supports additional messages_<language>.yml files if you want to translate the player-facing messages.
Durations are always stored internally in seconds: 1 day = 86400, 1 year = 31536000, -1 = permanent. Commands additionally accept shorthand like 1d12h, 30m, perm.
Commands & Permissions
| Command |
Permission |
/bansystem (alias /bansys) |
bansys.bansys |
/bansystem reload |
bansys.reload |
/bansystem export <punishments|logs|notes|violations> <json|csv> [timespan] |
bansys.export |
/bansystem import <litebans|advancedban|vanilla> [confirm] |
bansys.import |
/bansystem sync |
bansys.sync |
/bansystem ids create <id> <type> <onlyAdmins> <duration> <reason> |
bansys.ids.create |
/bansystem ids delete <id> |
bansys.ids.delete |
/bansystem ids edit <id> add lvl <lvl> <duration> <type> |
bansys.ids.addlvl |
/bansystem ids edit <id> remove lvl <lvl> |
bansys.ids.removelvl |
/bansystem ids edit <id> set lvlduration <lvl> <duration> |
bansys.ids.setduration |
/bansystem ids edit <id> set lvltype <lvl> <type> |
bansys.ids.settype |
/bansystem ids edit <id> set onlyadmins <true/false> |
bansys.ids.setonlyadmins |
/bansystem ids edit <id> set reason <reason> |
bansys.ids.setreason |
/bansystem ids show [id] |
bansys.ids.show |
/bansys logs show [page] |
bansys.logs.show |
/bansys logs clear |
bansys.logs.clear |
/ban <player> <id|duration> [reason] |
bansys.ban.<id> / bansys.ban.all / bansys.ban.admin |
/unban <player> [reason] |
bansys.unban |
/mute <player> <id|duration> [reason] |
bansys.ban.<id> / bansys.ban.all |
/unmute <player> [reason] |
bansys.unmute |
/kick <player> [reason] |
bansys.kick (bypass: bansys.kick.bypass) |
/check <player> |
bansys.check |
/history <player> |
bansys.history.show |
/deletehistory <player> |
bansys.history.delete |
/note <player> <text>, /ban note <player> <text> |
bansys.note |
/note remove <id> |
bansys.note.remove |
/chatfilter info <player> (alias /cf) |
bansys.filter |
/chatfilter history <player> [page], lookup <id>, resetpoints <player> |
bansys.filter |
/chatfilter addword <word> [weight], removeword, listwords |
bansys.filter |
/chatfilter addcmd <command>, removecmd, listcmds |
bansys.filter |
/chatfilter test <text>, stats, update |
bansys.filter |
| - |
bansys.notify (receives alt-account/VPN staff alerts) |
| - |
bansys.bypasschatfilter |
| - |
bansys.bypasschatdelay |
| - |
bansys.bypasscommands (exempt from the command blocker) |
| - |
bansys.ban.bypass (suppress kick-on-ban) |
| - |
bansys.ban.admin (also: use free durations while punishments.require-id is on) |
Known Limitations
- No GUI menu for the ban list - command-driven only.
- Signed chat (Minecraft 1.19.1+) can't be intercepted by BungeeCord/Velocity on their own - that needs the companion Spigot chat adapter on each backend server (
config.yml: signed-chat-bypass), which isn't bundled yet.
- BungeeCord cannot hand a changed chat message on to the backend server. A message the content filter would censor is blocked there instead, with the usual notice. Velocity and Spigot/Paper censor in place.
- The sign check of the content filter only exists on Spigot/Paper, a proxy never sees signs.
- LiteBans and AdvancedBan can only be imported from MySQL. Their default storage (H2 and HSQLDB) is a file, so move it to MySQL first.
- Redis only carries the news of a ban. All proxies have to share one MySQL database for the others to find it.
- Geyser support is limited to the
geyser.support config flag; no native Geyser-specific behavior beyond that.
Getting Started
- Drop
EmpireBan.jar into your plugins/ folder - only on the proxy (Velocity/BungeeCord) if you run one, otherwise on the Spigot server.
- Start the server once to generate
config.yml, ids.yml, stages.yml, and messages_english.yml.
- Set your database (SQLite by default, or MySQL) and enable VPN checking if you want it.
- Reload with
/bansystem reload - no restart needed.
Credits
|
|
| LucasTHCR |
Creator & maintainer |
| NTMFanSolidius |
Command blacklist for muted players (#1) |
The content filter, the violation points and the command blocker come from GigaProtect, which has been merged into EmpireBan.
Discord: dc.gg/paperstream
Open source under the GNU General Public License v3.0.
评论 0
登录后参与评分
还没有评论,来抢沙发吧