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 中导入处罚记录。一条命令即可完成迁移。
统计
截图






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:
/voicemuteand/tempvoicemutemute 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






下载 ControlBans
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 ControlBans
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 ControlBans
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 ControlBans
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 ControlBans
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 ControlBans
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 ControlBans
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 ControlBans
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 ControlBans
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 ControlBans
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
e
更新日志
新增
-
在 Minecraft 1.21.9+(使用 1.21.9 对象文本组件)的
/punish对话框中内联显示物品图标和玩家头颅;对于较旧服务器,则自动回退为纯物品堆栈。 -
提供真实原版纹理的捆绑索引文件(
vanilla-sprites.txt),并增加严格模式(punish.sprite-strict,默认值为true),以防止将未知的图标路径发送给客户端——否则会在客户端显示紫色的缺失纹理方框。 -
在
offences.yml的每个类别和违规行为中均支持sprite:和head:选项;通过经典的拥有者档案 API,head:可转化为真实的玩家头颅物品,因此也能在库存 GUI 中正常显示。 -
在对话框 UI 和库存回退界面中的违规行为与等级屏幕上增加了返回按钮,使工作人员无需关闭菜单即可返回上一级。
-
在
offences.yml中支持配置类别:使用hidden:可在菜单中隐藏某个类别,使用order:可控制首屏的显示顺序,使用permission:可为整个类别设置所需的权限节点。 -
/punish的每项操作权限:每个层级的操作都需要与对应命令相同的节点(controlbans.ban、controlbans.tempban、controlbans.mute、controlbans.tempmute、controlbans.kick、controlbans.warn、controlbans.freeze、controlbans.voicemute、controlbans.tempvoicemute……)。只有当某个层级的所有操作都被阻止时,该层级才会被 锁定;对于混合层级,仍会执行允许的操作并跳过被阻止的操作。此检查也在服务器端运行,因此控制台快捷指令/punish <玩家> <违规>无法绕过它。 -
基于
config.yml(dialog.accent和dialog.colors)驱动的单一强调色主题,其余所有色调均由该强调色衍生;每种色调均可固定为精确的十六进制颜色值。 -
在版本 5(
config-version: 5、locale-version: 5)中实现的所有者感知配置与本地化同步:新键会连同其注释块一并插入,所有者修改过的值将被保留并报告,且永远不会删除任何内容。 -
新增对 Paper 1.21.11、Paper 26.1.2 和 Paper 26.2 的支持,同时保留现有版本的支持。
已修复
- 惩罚菜单中的 MiniMessage 描述和名称曾被作为纯文本插入,导致工具提示显示原始标签(如
<muted>其他所有内容</muted>)而非格式化后的描述。现在,在将描述和名称放入对话框或物品 lore 之前,会先将其解析为 MiniMessage 格式。 - “旧版预设”类别重复了违规列表并 cluttered 了菜单的第一个屏幕;该选项现在默认关闭。
- 发送给客户端的错误精灵路径会导致绘制缺失纹理的方框。现在会校验路径是否对应真实的原版纹理,并将唱片机纹理从不存在的
item/juke_box更正为block/jukebox_side。 - Paper 对话框 API 采用反射方式加载,因此在不包含
io.papermc.paper.dialog的服务器(Paper 1.21.6 及更早版本)上,插件不再抛出NoClassDefFoundError错误,而是改用库存回退方案。 - 格式错误的精灵或头颅引用可能导致对话框完全无法打开;现在会在这些引用到达客户端之前拒绝它们。
- 物品画布在 1.21.11 中发生了变化(物品纹理从
minecraft:blocks移至minecraft:items);现在会根据服务器版本选择正确的画布。 /punish命令不再对工作人员无权使用的等级执行操作。
更新内容
- 惩罚界面现在围绕单一强调色构建,而非使用多色调色板。
dialog.accent和dialog.colors取代了旧版按元素单独定义的颜色;所有衍生色调均通过相同的色相计算,并调整亮度和饱和度。 - 默认情况下不再将“传统升级预设”列为一个分类(配置项
punish.legacy-presets-enabled,默认值false)。你escalation.yml中的预设不会被删除 ——/punish <player> <presetId>命令依然有效,只是它们不会显示在菜单中。将该配置项设为true即可恢复旧的标签页。 /punish命令默认需要针对每个操作的具体权限节点(配置项punish.require-action-permission,默认值true)。将其设为false可恢复旧行为:任何拥有controlbans.punish权限的管理员均可应用所有层级的惩罚。punish.sprite-strict默认值为true:如果遇到未知的精灵图片路径,系统会记录日志并丢弃该资源,而不是发送给客户端。将其设为false则可强制发送。offences.yml包含 4 个分类(聊天、语音、游戏、其他)和 19 种违规行为;config.yml和locales/en.yml已更新至版本 5。- 本插件基于
paper-api 1.21.11编译,兼容 Paper 1.21.6、1.21.8、1.21.11、26.1.2 和 26.2,以及 Folia 1.21.11。 - 在不支持对话框 API 的服务器(Paper 1.21.6)上,
/punish菜单对所有三个屏幕均使用库存界面的后备方案。
更新日志: 已修复 Velocity
完全修复了在 Velocity 上插件完全无法加载的问题(Guice 无法绑定我们重新定位的日志记录器“No implementation for Logger was bound”)
代理扩展现在能正确加载并注册其消息通道(已在 Velocity 4.3 上验证)
已修复代理消息被静默丢弃的问题:消息路径现在会验证载体是否实际注册了该通道,而不是在无操作时报告成功
已修复离线服务器问题
已修复在惩罚一名从未见过的玩家时,封禁错误地匹配到陌生人的 Mojang 账户的问题(离线服务器现在将解析为离线 UUID,而不是向 Mojang 查询)
已修复被封禁的玩家能够在封禁期间重新加入游戏的问题,此问题由上述身份不匹配导致
如果 UUID 不一致,加入检查现在会回退到通过精确名称进行匹配,并且封禁和静音列表中新增了名称列(会自动迁移)
已修复跨服务器问题
已修复在一台服务器上解除封禁后,另一台服务器上长达缓存 TTL 时间内登录检查未生效的问题。现在的登录检查始终从数据库读取最新数据
已修复存储问题
已修复 database.sqlite.file 中的绝对路径被粘贴到插件文件夹中而非被正确识别的问题
已修复命令问题
已修复每次执行 /check 时出现的隐藏错误(异步链内部的 null 返回值)
/punish 现在可以从控制台和 RCON 正常使用
/history 和 /alts 现在会从控制台/RCON 输出真实的文本内容,而不再拒绝执行
命令变更
在本地或无效 IP 上执行 IP 封禁/静音时,现在会明确提示“IP 无效”,而不再是“玩家未找到”
区域设置变更
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
插件
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
插件
ExyliaPlugins 的库。
插件
通过对话框或铁砧界面帮助你的 Anthme
插件
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
插件
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
插件
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
评论 0
登录后参与评分
还没有评论,来抢沙发吧