OmniBans

插件

· 作者 Hihelloy

一款高级的跨网络管理插件!

0 本站下载 0 关注 更新于 4 个月前

最新 1.0-velocity · 26.2 · Velocity

一键开服(送7天)

OmniBans

欢迎!OmniBans 是专为你 Minecraft 网络设计的综合管理套件。它作为插件运行于你的 Paper、Spigot 或 Folia 服务器,并附带两个轻量级的桥接插件(分别用于 Velocity 和 BungeeCord),确保你在任一服务器上执行的封禁或静音操作会立即在整个网络中生效。感谢试用,我们希望它能让你运营服务器变得更加轻松。<3

如果你是第一次进行设置,INSTALL.md 将逐步引导你完成整个过程。以下内容假设插件已经正常运行,主要介绍 OmniBans 在日常使用中能为提供的功能。

支持的版本

项目 支持范围
Minecraft 1.8 至 26.2
服务端软件 Spigot, Paper, Folia
代理端软件 Velocity, BungeeCord
Java 17 或更高版本(见下方说明)

Folia 的支持仅适用于 Folia 本身覆盖的 Minecraft 版本(1.19.4 及更高版本)。在旧版本上,会自动使用标准的 Bukkit 调度器,无需任何配置。

关于 Minecraft 版本号: Mojang 从 2026 年开始改用基于年份的版本号格式。2026 年发布的版本编号为 26.1、26.2 等,不再延续旧的 1.x 格式。采用旧格式的最后一个发布版本属于 1.21.x 系列。因此,上述支持范围涵盖了从 1.8 开始贯穿整个 1.x 时代,并延伸至新的 26.x 时代。

关于 Java: 该插件编译时目标版本为 Java 17,这意味着任何运行 Java 17 或更高版本的服务器都可以加载它。适合你服务器的 Java 版本取决于你所运行的 Minecraft 版本。运行 1.18 至 1.20.4 的服务器至少需要 Java 17。运行 1.20.5 至 1.21.x 的服务器至少需要 Java 21。运行 26.1 和 26.2 的服务器需要 Java 25,但由于 Java 在此方向上具有向后兼容性,Java 25 仍然可以加载为 Java 17 编译的插件。

启动方法

使用 Gradle 构建项目(./gradlew build)。你将得到三个 jar 文件:

  • paper/build/libs/OmniBans-Paper.jar 放入你运行的每个 Paper、Spigot 或 Folia 服务器的 plugins 文件夹中。
  • velocity/build/libs/OmniBans-Velocity.jar 放入你的 Velocity 代理端的 plugins 文件夹中。
  • bungee/build/libs/OmniBans-Bungee.jar 放入你的 BungeeCord 代理端的 plugins 文件夹中。

如果你只有一个服务器且没有代理端,则只需使用 Paper jar 文件即可。

默认情况下,OmniBans 将其所有数据存储在其自身文件夹内的一个小型 SQLite 文件中,这无需安装任何额外内容或进行任何设置,只要启动服务器即可立即工作。如果你只运行一个服务器,这是最佳选择。如果你运行多个服务器并希望封禁能在服务器之间同步,那么每个服务器和你的代理端都需要指向同一个 MySQL 数据库,请在 config.yml 的 storage 下(以及每个代理端 config.properties 的相应部分)进行设置。在这种情况下,你唯一需要自行安装的只是已创建好该数据库的 MySQL 或 MariaDB 服务器。

与玩家沟通

OmniBans 发送的所有消息,无论是封禁界面、聊天警告还是广播,都来自 messages.yml,你可以按照自己最熟悉的风格编写。你可以使用普通的 & 颜色代码(如 &c)、旧式的 section sign 代码、MiniMessage 标签(如 <red> 和 <gradient:#ff0000:#0000ff>)、以 &#ff00aa 形式编写的十六进制代码,甚至如果确实需要,可以使用原始聊天 JSON。OmniBans 会自动识别你的写法并正确渲染,无论使用 MiniMessage 自带的渐变标签还是手动编写一系列十六进制代码,渐变效果都能正常工作。

如果玩家恰好使用的是纯 Spigot 而非 Paper,OmniBans 仍能正确渲染你的格式。由于 Spigot 完全没有内置 Adventure 的文本系统,OmniBans 会在发送前悄悄地将你的消息转换为 Spigot 自己的聊天组件格式,这样玩家看到的颜色和样式完全一致。

命令

/ban, /tempban, /unban, /banip, /unbanip, /mute, /tempmute, /unmute, /kick, /warn, /note, /history, /check, /banlist, /mutelist, /alts, 以及 /omnibans reload, /omnibans version, /omnibans config, /omnibans messages。所有这些命令都支持完善的 Tab 补全功能。例如,输入 /ban Ste 并按 Tab 键会列出名字以该字母开头的在线玩家;/tempban 会提供合理的持续时间建议,如 1d 或 7d;原因可以从 config.yml 下 punishments.common-reasons 中的快速列表中选择。如果玩家实际上没有执行某条命令的权限,他们也不会看到任何 Tab 补全建议,因此从某种意义上说,管理命令对其他所有人也是不可见的。

/alts <player> 显示指定玩家的已知小号账号,并告知每个小号当前是否被封禁或静音,以及他们共享的 IP 地址是否被封禁或静音。如果你检查的玩家是操作员,或者通过 LuckPerms 拥有 * 权限,OmniBans 只会提示其享有豁免权,而不会显示有关他们的任何信息,因为管理账号不应以此方式进行交叉引用。

在游戏中编辑配置

/omnibans config 和 /omnibans messages 会将 config.yml 和 messages.yml 以游戏内菜单的形式打开,每个设置对应一个物品。像 redis.enabled 这样的开关只需点击即可切换,并根据当前状态显示为绿色或红色物品。其他类型(数字、文本或列表如 punishments.common-reasons)则会关闭菜单,并在聊天栏中要求你输入新值。此时输入 cancel 可取消操作而不做任何更改。列表应以逗号分隔的纯文本形式输入。如果你正在编辑多行消息模板,可以在希望换行的位置输入 \n。每处更改都会立即保存到磁盘并生效,无需随后再运行 /omnibans reload。

跨版本更新保持 config.yml 和 messages.yml 同步

每次 OmniBans 启动时,它都会悄悄地将你现有的 config.yml 和 messages.yml 与当前版本所期望的内容进行比对。如果新版 OmniBans 引入了此前不存在的设置项,它会使用默认值自动将其添加到你的文件中,而你原本已有的所有设置都保持原样,绝不会因这一过程而被覆盖。这意味着你可以更新 OmniBans 并保留旧配置文件,无需手动复制任何新设置。

只有当某个版本的 OmniBans 明确停止使用某项设置时,该设置才会从你的文件中被移除。发生这种情况时,系统会干净地移除该项,并在控制台打印一行日志,明确指出移除了什么内容以及来自哪个文件。以这种方式不会触碰任何其他内容:你自己添加的、OmniBans 从未知晓的设置(无论是否为默认值)将永远保持不变。在任何实际更改发生之前(无论是添加还是移除),系统在更改前的文件状态会被备份到一个同目录下的 .bak 文件中,以便在需要时可以一键恢复之前的状态。

有两点诚实的限制值得了解。首先,如果未来版本中某项设置只是被重命名而非简单地添加或删除,此系统不会自动将你旧的值迁移到新名称下,因为重命名属于不同于添加或删除的变更类型,而这正是本系统专门设计来处理的情形。若发生此类情况,本 README 会在相应更新时提供清晰的指引。其次,此机制仅在确实需要更改时才检查并重写文件;但在那次更新发生时,你在 config.yml 或 messages.yml 中手写的注释将不会保留下来。这是因为 Bukkit 读取和写入 YAML 文件的通用长期限制所致,并非 OmniBans 特有的问题。无论如何,你的设置及其值始终会被完美保留,受影响的仅是你周围的注释,且仅限于实际发生更改的更新。

整个上述机制仅适用于 config.yml 和 messages.yml。Velocity 和 BungeeCord 代理桥接使用的是 config.properties 文件,这是一种不同且更简单的格式,不受以上任何影响。

防止玩家受到意外处罚

你可以将这些权限之一授予特定玩家,以确保任何人——包括偶尔情绪不佳的信任度高的管理员——都不会误封禁、静音、踢出或警告他们:

  • omnibans.exempt.ban
  • omnibans.exempt.mute
  • omnibans.exempt.kick
  • omnibans.exempt.warn
  • omnibans.exempt.banip

这些权限默认情况下不会授予任何人。由你来决定谁获得这些权限。

接管 Essentials 和原版命令

Minecraft 本身自带了 /ban、/ban-ip、/kick、/pardon 和 /pardon-ip 命令,而 EssentialsX 历史上也提供了自己的 /mute 等命令。OmniBans 旨在成为服务器上实际处理 moderation 的核心,因此它接管了所有这些命令标签,包括两个拼写与其自身命令略有不同的命令(ban-ip 以及 pardon/pardon-ip),这样即使玩家在其他服务器养成的习惯或肌肉记忆触发了原版命令,最终仍会由 OmniBans 处理,而非其他插件。如果安装了 Essentials,OmniBans 会在启动时检测到这一点,并明确重新接管你们双方可能都想使用的每一个命令,无论哪一个先加载,同时会在控制台记录一行日志确认已执行此操作。

关于玩家隐私的注意事项

OmniBans 需要记住玩家连接的地址,以便封禁 IP 并检测多个账号是否共享同一地址,但它永远不会向任何人展示该地址——无论是在聊天消息、命令输出还是 Discord 消息中。如果你通过 /check 或 /alts 查询某位玩家,你会看到有多少个地址被记录,以及其中是否有任意一个当前被封禁或静音,但绝不会显示地址本身。唯一出现地址的情况是工作人员自己在如 /banip 这样的命令中输入了地址,这是他们自己的输入行为,而非 OmniBans 返回给他们的信息。

我们在此坦诚相告。在开发过程中,曾有几个地方疏忽导致地址在确认消息中回显给了工作人员(/banip 的成功消息、/unbanip 的成功与失败消息,以及 /check 的摘要行)。这些问题已全部修复,/unbanip 现在也支持直接使用玩家名称,从而你几乎无需再手动输入地址。我们选择公开说明此事,而不是悄悄打补丁后一言不发。

随后又发现了另一处同类性质的泄露:当你直接在 /banip 中输入裸 IP 地址而未关联任何玩家时,OmniBans 会将该字面意义上的地址作为处罚的显示名称存储,这会导致它在原本用于显示玩家名称的地方出现,例如全服封禁广播、Discord Webhook 以及 /banlist。该问题已在源头修复,针对裸 IP 的封禁不再保留其地址作为名称,所有显示处罚名称的地方现在都会 fallback 到通用标签,即便未来某些变更意外尝试暴露地址也不会再发生。此外,在我们处理这些问题期间,也将 /banlist 和 /mutelist 的默认权限收紧为仅限操作员可见,因为即使不包含地址,完整的封禁列表也不是每位玩家都需要查看的内容。

在 Discord 上通知你的管理员

OmniBans 拥有两种完全独立的 Discord 推送方式,你可以单独使用其中一种、两者都用,或者都不使用。

简单的方案是使用 Webhook,通过在 config.yml 中设置 discord.webhook-url 和 discord.enabled 来启用。Webhook 只是 Discord 为单个频道提供的一个单向 URL,完全不需要机器人。开启此功能后,每当发生封禁、IP 封禁、静音、IP 静音、踢出或警告时,OmniBans 都会向该频道发送一个纯文本嵌入消息(embed),其中包含玩家名称、执行操作的管理人员以及原因。Webhook 没有提及角色的概念,OmniBans 也不会尝试这样做;此外,Webhook 无法获取任何关于小号的信息,它仅发布这一种简单的消息。

更完整的方案是一个真正的 Discord 机器人,通过 discord-bot 部分进行配置。它触发与 Webhook 完全相同的事件,并增加第二种类型的消息:每当一名非操作员且不持有 LuckPerms 的 * 权限的玩家加入服务器,且被发现拥有已知的小号时(即触发游戏内管理员警告的相同情况),机器人就会发送通知。机器人发送的每个嵌入消息还会告知你该玩家的已知小号及其哪些小号已被封禁,这与游戏内 /alts 命令的方式相同,而普通的 Webhook 嵌入不包含这些信息;并且它可以可选地 ping 某个角色,以便你的管理团队能够注意到这些通知。在 config.yml 中设置如下:

discord-bot:
  enabled: true
  token: "your bot's token"
  server-id: "your discord server's id"
  channel-id: "the channel you want these messages posted in"
  admin-role-id: "the role you want pinged, optional"

你需要将你自己的机器人邀请到你的服务器,并授予其在相应频道发送消息和嵌入内容的权限。与 OmniBans 中的其他所有功能一样,无论是 Webhook 还是机器人嵌入,都永远不会包含地址信息。

关于快速发出大量惩罚的说明

如果你曾在服务器控制台中看到在封禁后立即出现的提及 AsyncCatcher 和 player kick 的错误,并且在连续发生多次惩罚时伴随明显的卡顿,那是一个真实的 Bug,而非你操作层面的问题。OmniBans 在保存封禁或静音记录后执行的某些操作——包括踢出玩家和广播公告——原本是在后台线程上运行的,而不是在主服务器上运行,但 Minecraft 不允许对这类操作使用后台线程。即使出现这种情况,惩罚本身仍然会被正确应用,但重复出现的错误确实造成了额外的开销,也就是你可能注意到的轻微卡顿。此问题已修复,现在相关工作始终按照应有的方式在主线程上执行。

关于 Gradle 构建的简要说明

如果你的构建在 shadowJar 阶段失败,并出现提及 org.objectweb.asm.commons.Remapper 的奇怪错误,那是 Shadow 插件自身的包重定位步骤在某些版本的 Shadow 中遇到了问题,与 OmniBans 实际包含的代码无关。构建脚本目前已不再要求 Shadow 执行任何包的重新定位,因为正是这个重定位步骤导致了各种各样的持续失败。OmniBans 所需的所有依赖项仍会直接打包到每个 jar 文件中,只是保留了其原始包名而未进行重命名。这是一种完全正常的插件分发方式,仅当你的服务器上另一个插件恰好捆绑了相同库的冲突版本时才会产生影响。

仍在计划中的一些事项

/history、/banlist 和 /mutelist 命令目前输出到聊天栏而非打开菜单,虽然这样已经足够好用,但未来若能提供一个完善的界面会更好。此外,目前还没有针对诸如玩家封禁次数等数据的 PlaceholderAPI 扩展。如果有时间,这两项都将是非常受欢迎的补充功能。

项目所在处

OmniBans 的开发位于 github.com/Hihelloy-main/OmniBans。如果你遇到任何与本文档描述不符的问题,请前往此处反馈。本仓库不接受通过拉取请求(pull requests)进行的直接贡献,因此请勿提交 PR,但我们非常欢迎并认真处理问题和 Bug 报告。再次感谢使用 OmniBans。 <3

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源