ControlBans
ControlBans 是我最热衷于开发的 Moderation(管理)插件。我于 2025 年末开始开发它,并一直将其作为首要项目。更多插件正在开发中,那是另一个故事了。
我构建它是因为我受够了那些将有用命令放在付费层级背后的管理插件。这个插件是免费且开源的,只要你把 jar 文件放入服务器,页面上的所有功能即可立即使用。没有付费命令,没有阉割版,也没有陷阱。
它能做什么
ControlBans 涵盖了管理团队实际需要执行的工作:封禁、禁言、语音禁言、警告、踢出、冻结、举报、申诉、备注、小号检测以及围绕这些功能的管理员工具。
它运行在 Paper 1.21.6 及更高版本上,也支持 Folia。需要 Java 21。该插件直接使用 Paper API,因此服务器必须运行 Paper 或 Folia。同一个 jar 文件也可以作为代理扩展在 BungeeCord 和 Velocity 上工作,我稍后会详细说明。
处罚查询通过缓存进行,并且每次数据库调用都是异步的,因此封禁操作永远不会在主线程上等待查询。
/punish 菜单
/punish <player> 会引导你穿过三个界面:
- 类别:聊天、语音、游戏或其他,如果你还有旧的预设文件,还会显示一个“Legacy”(旧版)预设类别。
- 违规行为:该类别下的每种违规行为,提示工具中显示了其升级阶梯。
- 等级:该违规行为的阶梯。符合玩家自身记录的等级会被标记为“Recommended”(推荐),屏幕上会显示之前的违规次数。
然后你可以在聊天中输入可选的备注,或者输入 skip 继续下一步。如果你不想点击穿过三个界面,可以直接使用 /punish <player> chat.spamming 立即应用该违规行为。
在 Paper 1.21.6 及更高版本上,该菜单是一个真正的 Minecraft 对话框。在其他版本上,它会回退到具有相同内容的库存 GUI。其中的所有内容都来自配置文件:一种强调色驱动整个界面,每个图标都是一个真实的物品而不是文本字符,并且在 1.21.9 及更高版本上,对话框会绘制真实的物品精灵图和玩家头颅。
违规行为与升级
plugins/ControlBans/offences.yml 定义了类别、其中的违规行为以及每种违规行为的升级方式。没有任何内容被硬编码。捆绑的文件为你提供了 4 个类别和 19 种违规行为作为起点。
等级来源于目标玩家自身的历史记录。第一次对某人处以 chat.spamming(聊天刷屏)处罚时,他们获得 tier 0,第二次获得 tier 1,依此类推。当阶梯用完时,最后一个等级会重复出现,因此违规行为绝不会悄无声息地停止升级。判罚在设定的时间窗口后过期(默认为 90 天),而违规行为可以使用自己的设置覆盖该默认值。
应用的等级会与处罚一起保存,存储的理由可以通过模板包含违规行为名称和等级,以便几个月后历史记录仍能自我解释。
管理员限制与权限
两件事决定了管理员可以做什么。
他们的等级决定了他们可以处罚的时间长度,以纯权限节点表示:
controlbans.rank.duration.ban.7d
controlbans.rank.duration.mute.12h
controlbans.rank.unlimited
他们拥有的最大权限桶获胜。超过其限制的等级会显示为 Locked(锁定),点击将被拒绝,因此拥有 7 天上限的管理员无法发出 30 天的封禁。
他们的权限决定了他们可以发布哪些类型的处罚。/punish 检查与命令相同的节点,因此没有 controlbans.tempban 权限的人看到的封禁等级是锁定的,而不是悄悄地封禁玩家。当一个等级混合了允许和禁止的处罚时,允许的处罚仍然执行,其他处罚被跳过并在屏幕上显示备注。如果你想保留旧行为(即只需 controlbans.punish 即可),请设置 punish.require-action-permission: false。控制台不受任何限制。
命令
处罚
| 命令 |
作用 |
/ban, /tempban, /unban |
永久封禁或设定时间封禁 |
/mute, /tempmute, /unmute |
永久禁言或设定时间禁言 |
/shadowmute |
玩家能看到自己的消息,其他人看不到 |
/ipban, /ipmute, /unipban, /unipmute |
按 IP 地址处罚 |
/warn |
警告玩家 |
/kick |
带理由踢出玩家 |
/freeze |
冻结玩家以便屏幕共享 |
/voicemute, /tempvoicemute, /voiceunmute |
在 Simple Voice Chat 中禁言玩家 |
/banskin, /unbanskin |
强制将玩家的皮肤恢复为默认 |
/punish |
三级处罚菜单 |
管理员工具
| 命令 |
作用 |
/history |
玩家在 GUI 中的完整处罚时间线 |
/check |
玩家的封禁和禁言状态 |
/alts |
共享 IP 的账号,在 GUI 中显示 |
/note |
关于玩家的私人管理员备注 |
/banlist, /mutelist |
浏览当前的处罚 |
/blame |
某位管理员已进行的处罚 |
/reports |
举报审查 GUI:完整描述,按状态过滤,传送至任一玩家,解决、拒绝、重新打开或删除 |
/appeals |
申诉审查 GUI。批准申诉后玩家将被解除禁言 |
/chat lock, /chat slow, /chat clear |
锁定聊天、设置慢速模式、清除聊天 |
/staff |
在线人员列表 |
/scheduledpunishment |
安排稍后的处罚 |
/bulkpunishment |
一次性处罚多个玩家,可选择安排时间 |
/controlbans |
重载、导入、导出、数据库和回滚 |
针对玩家
| 命令 |
作用 |
/report |
通过 GUI 举报玩家(使用你配置的类别),或自行编写理由 |
/reports |
查看自己举报的状态 |
/appeal |
在游戏中申诉解除禁言 |
处罚命令可以使用 -s 进行静默处罚。拥有静默通知权限的管理员可以看到,其他人则看不到。
调度、批量处罚和冻结
定时处罚支持相对时间(30m、+2h)、墙钟时间(23:30)、日期和时间(2030-01-01 12:00)或月份和日期(11-02 23:30)。排期会在重启后保留,清除排期会直接删除对应的行,而不仅仅是隐藏它们。
/freeze <player> 将玩家锁定在原地,适用于屏幕共享场景。被冻结的玩家无法移动、破坏、放置方块、攻击、聊天或执行命令,除非你特别允许。冻结状态会在重启后保留,如果处于冻结状态的玩家登出,将被封禁。服务器关闭不被视为断开连接。
聊天、举报与申诉
/chat lock、/chat slow 和 /chat clear 分别用于锁定聊天、启用慢速模式以及清空聊天。锁定设置和慢速模式的延迟会被保存,因此重启后依然生效。
玩家可以通过 GUI 进行举报,你可以在配置文件中定义分类,或者让他们自行填写原因。工作人员会收到一个包含完整描述的审查 GUI,点击即可传送至涉事双方,并可选择解决、拒绝、重新打开或删除该举报。
mute(禁言)可以在游戏内发起申诉。工作人员阅读申诉内容,批准后将解除玩家的禁言。冷却时间、提交限制以及申诉窗口保持开放的时间均可自定义配置。
数据库与网络
默认使用 SQLite,插件会创建自己的文件,无需额外连接。如果你需要 MySQL 或 MariaDB,也可以通过 HikariCP 使用。过期的处罚会按计划清理,防止表中堆积大量无效数据。
玩家查询结果会被缓存,一旦有任何变更,缓存立即失效。
同一个 jar 包也可以作为代理扩展使用。将其放入 BungeeCord 或 Velocity 中,它就能在网络中转发踢人消息、广播和工作人员警报,并通知其他服务器清除各自的处罚缓存,从而确保在一台服务器上执行的封禁能同步到所有服务器。
集成
- Simple Voice Chat:
/voicemute 和 /tempvoicemute 可静音范围内的语音聊天玩家。
- Discord:为每种处罚类型配置 webhook,支持自定义颜色、标题、字段和页脚;如果你已运行 DiscordSRV,也可与之集成。
- Floodgate 和 Geyser:自动检测并正确处理 Bedrock 版玩家。
此外还提供公共 API,如果你正在开发自己的插件并希望接入封禁、禁言和举报系统,可以使用该 API。
外观与体验
每条消息均使用 MiniMessage 格式,存放在 plugins/ControlBans/locales/en.yml 中,因此你可以重写任何文本内容。jar 包自带位于 themes/ 目录中的主题包,模拟了 Hypixel、MineMen 和 MCPVP 等服务器的处罚界面样式,让你无需自己动手即可获得相同视觉效果。
菜单提供六种预设主题(arctic、ember、toxic、royal、crimson、mono)以及一种衍生自主色调的强调色。
翻译文件的配置方式类似。只需将你的语言文件放入 plugins/ControlBans/locales/ 目录,并在配置中将 language: 指向该文件即可。
从其他插件迁移
/cb import 可从 LiteBans、AdvancedBan 或 Essentials 中导入处罚记录。一条命令即可完成迁移。
统计
Discord · 源代码 · 问题反馈
截图






ControlBans
ControlBans is the moderation plugin I enjoy working on the most. I started it in late 2025 and I've been putting it first ever since. More plugins are on the way, but that's a different story.
I built it because I got tired of moderation plugins that put the useful commands behind a premium tier. This one is free and open source, and everything on this page works the moment you drop the jar in. No paid commands, no cut-down version, no catch.
What it does
ControlBans covers the work a moderation team actually has to do: bans, mutes, voice mutes, warnings, kicks, freezes, reports, appeals, notes, alt detection and the staff tools around them.
It runs on Paper 1.21.6 and newer, and on Folia. Java 21. The plugin uses Paper APIs directly, so a server needs Paper or Folia. The same jar also works on BungeeCord and Velocity as a proxy extension, which I'll come back to further down.
Punishment lookups go through a cache and every database call is asynchronous, so a ban never sits on the main thread waiting for a query.
The /punish menu
/punish <player> walks through three screens:
- Category: Chat, Voice, Game or Misc, plus a Legacy presets category if you still have old presets lying around.
- Offence: every offence in that category, with its escalation ladder in the tooltip.
- Tier: the ladder of that offence. The tier that fits the player's own record is marked Recommended, and the number of previous offences shows up on the screen.
Then you type optional notes in chat, or type skip to move on. /punish <player> chat.spamming applies an offence straight away if you'd rather not click through three screens.
On Paper 1.21.6 and newer the menu is a real Minecraft dialog. Everywhere else it falls back to an inventory GUI with the same content. Everything in it comes from config: one accent colour drives the whole interface, every icon is a real item rather than a text character, and on 1.21.9 and newer the dialogs draw actual item sprites and player heads.
Offences and escalation
plugins/ControlBans/offences.yml defines the categories, the offences inside them and how each offence escalates. Nothing is hard-coded. The bundled file gives you 4 categories and 19 offences to start from.
The tier comes out of the target's own history. Punish someone for chat.spamming for the first time and they get tier 0, the second time tier 1, and so on. When the ladder runs out the last tier repeats, so an offence never quietly stops escalating. Strikes expire after a window you set (90 days by default), and an offence can override that with its own.
The tier that was applied is saved next to the punishment, and the stored reason can include the offence name and tier through a template, so the history still explains itself months later.
Staff limits and permissions
Two separate things decide what a staff member can get away with.
Their rank decides how long they may punish for, expressed as plain permission nodes:
controlbans.rank.duration.ban.7d
controlbans.rank.duration.mute.12h
controlbans.rank.unlimited
The biggest bucket they hold wins. A tier above their limit shows up as Locked and the click is refused, so a moderator with a 7 day cap can't hand out a 30 day ban.
Their permissions decide which punishments they may issue at all. /punish checks the same nodes the commands do, so someone without controlbans.tempban sees the ban tiers locked instead of quietly banning people. When a tier mixes an allowed and a forbidden punishment, the allowed one still runs and the other is skipped with a note on the screen. Set punish.require-action-permission: false if you want the old behaviour where controlbans.punish was enough. The console is never restricted.
Commands
Punishments
| Command |
What it does |
/ban, /tempban, /unban |
Ban permanently or for a set time |
/mute, /tempmute, /unmute |
Mute permanently or for a set time |
/shadowmute |
The player sees their own messages, nobody else does |
/ipban, /ipmute, /unipban, /unipmute |
Punish by IP address |
/warn |
Warn a player |
/kick |
Kick a player with a reason |
/freeze |
Freeze a player for a screenshare |
/voicemute, /tempvoicemute, /voiceunmute |
Mute players in Simple Voice Chat |
/banskin, /unbanskin |
Force a player's skin back to the default |
/punish |
The three-screen punish menu |
Staff tools
| Command |
What it does |
/history |
Full punishment timeline for a player, in a GUI |
/check |
A player's ban and mute status |
/alts |
Accounts sharing an IP, in a GUI |
/note |
Private staff notes on a player |
/banlist, /mutelist |
Browse the active punishments |
/blame |
What a staff member has punished |
/reports |
Report review GUI: full descriptions, filter by status, teleport to either player, resolve, reject, reopen or delete |
/appeals |
Appeal review GUI. Approve one and the player is unmuted |
/chat lock, /chat slow, /chat clear |
Lock chat, set slowmode, wipe chat |
/staff |
Who is online |
/scheduledpunishment |
Schedule a punishment for later |
/bulkpunishment |
Punish a list of players at once, optionally on a schedule |
/controlbans |
Reload, import, export, database and rollback |
For players
| Command |
What it does |
/report |
Report a player through a GUI with the categories you configured, or write your own reason |
/reports |
Check the status of your own reports |
/appeal |
Appeal a mute in game |
The punishment commands take -s for a silent punishment. Staff with the silent notify permission see it, everyone else doesn't.
Scheduling, bulk punishments and freeze
Scheduled punishments take relative times (30m, +2h), a wall clock time (23:30), a date and time (2030-01-01 12:00) or a month and day (11-02 23:30). Schedules survive a restart, and clearing them deletes the rows instead of only hiding them.
/freeze <player> locks a player in place for a screenshare. They can't move, break, place, attack, chat or run commands, apart from the ones you allow. The freeze survives a restart, and a frozen player who logs out gets banned. A server shutdown is not treated as a disconnect.
Chat, reports and appeals
/chat lock, /chat slow and /chat clear do what they say. The lock and the slowmode delay are saved, so they survive a restart.
Players report through a GUI with categories you define in the config, or they can write their own reason. Staff get a review GUI with the full description, a click that teleports to either player, and resolve, reject, reopen or delete.
Mutes can be appealed in game. Staff read the appeal and approving it unmutes the player. Cooldown, submission limit and how long the appeal window stays open are all configurable.
Databases and networks
SQLite is the default, so the plugin makes its own file and there's nothing to connect. MySQL and MariaDB are there when you want them, through HikariCP. Expired punishments get cleared on a schedule so the table doesn't fill up with dead rows.
Player lookups are cached, and the cache is invalidated the moment something changes.
The same jar works as a proxy extension too. Drop it into BungeeCord or Velocity and it relays kick messages, broadcasts and staff alerts across the network, and tells the other servers to drop their punishment cache, so a ban on one server lands on the rest.
Integrations
- Simple Voice Chat:
/voicemute and /tempvoicemute mute players in proximity voice.
- Discord: a webhook per punishment type with your own colours, titles, fields and footers, or DiscordSRV if you already run it.
- Floodgate and Geyser: Bedrock players are detected and handled properly.
There's a public API too, if you're writing a plugin of your own and want to hook into bans, mutes and reports.
Look and feel
Every message is MiniMessage and lives in plugins/ControlBans/locales/en.yml, so you can rewrite any of it. The jar ships with theme packs in themes/ that mimic the punishment screens of servers like Hypixel, MineMen and MCPVP, if you want that look without doing the work yourself.
The menu has six presets (arctic, ember, toxic, royal, crimson, mono) and one accent colour that every other shade is derived from.
Translations work the same way. Drop your own file into plugins/ControlBans/locales/ and point language: at it.
Coming from another plugin
/cb import pulls punishments out of LiteBans, AdvancedBan or Essentials. One command and you're over.
Stats
Discord · Source Code · Issues
Images






评论 0
登录后参与评分
还没有评论,来抢沙发吧