mBans
适用于 Paper、Purpur、Folia 和 Velocity 网络的灵活管理与处罚系统。
后端插件支持 Paper、Purpur 和 Folia 26.3。代理模块可在封禁账号进入 Velocity 网络前将其拦截。
功能特性
- 永久与临时封禁、IP 封禁、常规/IP/静默禁言,警告及踢出
- 优先基于 UUID 的记录,支持在线查询、本地玩家历史记录以及异步 Mojang 备用查询
- 单机使用 H2 或 SQLite;共享网络使用 MySQL、MariaDB 或 PostgreSQL
- 基于轮询的跨服务器同步及独立的 Velocity 登录检查
- 处罚历史、员工记录、回滚、备注、IP 例外、小号检测及导出
- 权限限制的静默处罚、理由模板、证据链接及
-last 聊天记录取证
- 缓存式禁言执行(聊天与可配置私聊命令);无需每条消息都进行数据库查询
- 仅发送者、控制台及拥有
mbans.notify.shadow 权限的员工可见静默禁言聊天内容
- 活跃封禁/禁言/警告列表、按 ID 查找处罚、编辑理由及基于 ID 撤销
- 可配置的警告升级机制及管理员豁免等级
- 离线警告送达及生成的申诉 ID
- 绑定 UUID 的游戏内禁言申诉,附带员工审核队列;封禁仍保留外部支持链接
- Discord 嵌入消息,支持按类型配置 Webhook 及可选的申诉按钮
- 可选的本地 GeoLite2 国家过滤及经过身份验证的只读 REST API
- 原生 JSON 格式及自适应 JDBC 迁移,支持试运行模式
- 提供英文和俄文消息文件,集成 bStats 及 Modrinth 更新检查
要求
- Java 25
- Paper、Purpur 或 Folia 26.3
- 使用
mBans-Velocity-1.2.1.jar 时需 Velocity 3.4
单台服务器无需外部数据库。网络部署必须使用共享的 MySQL、MariaDB 或 PostgreSQL 数据库。切勿在多个进程间共享 H2 或 SQLite 文件。
单服安装
- 将
mBans-1.2.1.jar 放入服务器的 plugins 目录。
- 启动一次服务器。
- 编辑
plugins/mBans/config.yml,修改存储或网络设置后重启生效。
默认使用 H2 数据库。玩家消息从 lang/en_US.yml 加载;如需使用内置俄语文件,请设置 language.default: ru_RU。
Velocity 网络安装
- 创建一个 MySQL、MariaDB 或 PostgreSQL 数据库。
- 在每个后端节点安装
mBans-1.2.1.jar。
- 在所有后端节点配置相同的数据库,并为每个节点设置不同的
network.server-name。
- 将
mBans-Velocity-1.2.1.jar 放入 Velocity 的 plugins 目录。
- 启动一次 Velocity,并使用相同的 JDBC 连接配置
plugins/mbans-velocity/config.properties。
- 重启代理及所有后端节点。
Velocity 模块直接读取共享的处罚表。请先安装并初始化后端节点以确保存在相应的数据库结构。完整示例请参阅 网络指南。
配置
主要配置项包括:
storage: 本地文件、数据库引擎、连接凭证、连接池限制及可选的完整 JDBC URL
network: 唯一的后端名称及数据库日志轮询间隔
templates 和 durations: 可复用的理由及 GUI 持续时间选项
escalation: 计数、时间窗口、触发操作、持续时间及理由
immunity 和 exemptions: 权限等级、排除的世界及 IPv4/IPv6 CIDR 范围
discord: 默认或按处罚类型配置的 Webhook 及包含 <appeal_id> 的申诉 URL
chat-evidence: -last N 命令可用的内存中消息数量
geoip: 本地 MMDB 文件名及 ISO 国家允许/阻止列表
rest-api: 本地监听地址、端口及 Bearer Token
appeals: 启用游戏内提交及消息长度上限
metrics 和 updates: bStats 统计及 Modrinth 更新发现
缺失的默认值将以默认值补充,不会替换现有值。/mbans reload 用于重载消息及安全设置;存储、网络、REST 及 GeoIP 更改需要重启服务器。详见 配置说明。
指令
| 命令 |
用途 |
/ban <player> [duration] [reason] |
永久或临时封禁一名玩家 |
/tempban <player> <duration> [reason] |
要求指定临时封禁时长 |
/unban <player> [reason] |
移除当前有效的封禁 |
/banip <player|ip> [duration] [reason] |
封禁一个 IP 地址 |
/unbanip <player|ip> |
移除 IP 封禁 |
/mute, /tempmute, /unmute |
管理聊天禁言 |
/ipmute <player|ip> [duration] [reason] |
禁用使用特定 IP 的账号的聊天功能 |
/unipmute <player|ip> |
移除 IP 禁言 |
/shadowmute <player> [duration] [reason] |
隔离聊天而不通知目标玩家 |
/tempshadowmute <player> <duration> [reason] |
要求指定临时静默禁言时长 |
/unshadowmute <player> |
移除静默禁言 |
/appeal <appeal-id> <message> |
提交与自身处罚相关的申诉 |
/warn <player> [reason] |
添加警告并评估升级规则 |
/unwarn <player> <id|all> |
移除一条或多条当前有效的警告 |
/kick <player> [reason] |
踢出在线玩家 |
/history <player> [page] |
查看玩家的处罚历史 |
/staffhistory <staff> [page] |
查看某位管理员的操作记录 |
/check <player> |
显示当前的封禁、禁言和警告状态 |
/banlist [page] |
列出当前有效的封禁 |
/mutelist [page] |
列出当前有效的禁言 |
/warns <player> |
列出当前有效的警告 |
/punishment <id> |
检查某项处罚及其申诉 ID |
/alts <player> |
查找具有相同记录 IP 的账号;别名 /dupeip |
/muser <player> |
打开管理 GUI,包括离线记录 |
/mbans rollback <staff> [time] |
撤销某位管理员最近的处罚 |
/mbans revoke <id> [reason] |
通过 ID 撤销一项当前有效的处罚 |
/mbans reason <id> <reason> |
更正已存储的处罚原因 |
/mbans allow <player> [ip-ban-id] |
允许某个 UUID 豁免其当前的 IP 封禁 |
/mbans note <player> <text> |
添加一条仅供内部使用的员工备注 |
/mbans notes <player> |
读取最近的员工备注 |
/mbans stats <staff> |
显示管理员操作计数 |
/mbans appeals [page] |
列出游戏中未处理的申诉 |
/mbans appeal <id> <accept|deny> [note] |
审核申诉;接受申诉将撤销当前有效的处罚 |
/mbans import ... |
预览或导入旧版数据 |
/mbans export <player> [json|csv] |
导出玩家的历史记录 |
/mbans reload |
重新加载安全配置和语言值 |
时长支持组合单位,例如 30m、2h、7d 和 1mo。封禁、禁言、警告和 IP 封禁命令支持 -s 和 --evidence=<url>。封禁、禁言和警告命令还支持 -last <count> 以附加最近的聊天记录行。模板名称可替代原因,例如 /ban Steve cheat。
每项管理命令都对应一个 mbans.command.<name> 权限。mbans.admin 授予完整的命令集。敏感 IP 输出需要 mbans.view.ip;账号关联通知需要 mbans.notify.alts;允许观察静默禁言聊天的员工需要 mbans.notify.shadow。目标豁免使用 mbans.bypass.ban、mbans.bypass.mute、mbans.bypass.warn 和 mbans.bypass.kick。替换现有封禁或禁言需要 mbans.override;缩短时长还需额外具备 mbans.override.shorten。-s 标志需要 mbans.silent。
PlaceholderAPI
安装 PlaceholderAPI 后,mBans 会注册 %mbans_banned%、%mbans_muted%、%mbans_warnings%、%mbans_status% 和 %mbans_version%。处罚状态以异步方式加载,并缓存五秒。首个未解析的请求将返回空值,而不会阻塞服务器线程。
迁移
导入前务必备份源数据和目标数据。从 --dry-run(试运行)开始:
/mbans import vanilla . --dry-run
/mbans import litebans --dry-run
vanilla 配置文件读取 banned-players.json 和 banned-ips.json。JDBC URL 和凭据从 imports.<profile> 中读取,因此密码不会进入命令历史记录。JDBC 配置文件会检查源表元数据,并识别常见的处罚字段名称。在运行不带 --dry-run 的同一命令前,请仔细核对数量详情与限制条件见 迁移指南。
构建产物
mBans-1.2.1.jar: Paper、Purpur 和 Folia 后端
mBans-Velocity-1.2.1.jar: Velocity 登录强制执行
遥测与更新
mBans 使用 bStats 插件 ID 33351 进行匿名使用统计。可通过设置 metrics.enabled: false 禁用收集。更新检查器读取公共 Modrinth 项目,并可独立通过 updates.enabled: false 禁用。
构建
./gradlew clean build :velocity:build
本项目采用 MIT 许可证授权。
mBans
Flexible moderation and punishment management for Paper, Purpur, Folia, and Velocity networks.
The backend plugin supports Paper, Purpur, and Folia 26.3. The proxy module blocks banned accounts before they enter a Velocity network.
What it does
- permanent and temporary bans, IP bans, regular/IP/shadow mutes, warnings, and kicks
- UUID-first records with online lookup, local player history, and an asynchronous Mojang fallback
- H2 and SQLite for a single server; MySQL, MariaDB, and PostgreSQL for shared networks
- polling-based cross-server synchronization and a separate Velocity login check
- punishment history, staff history, rollback, notes, IP exceptions, alt detection, and exports
- permission-gated silent punishments, reason templates, evidence links, and
-last chat evidence
- cached mute enforcement for chat and configurable private-message commands; no database query per message
- shadow-muted chat is visible only to its sender, console, and staff with
mbans.notify.shadow
- active ban/mute/warning lists, punishment lookup by ID, reason editing, and ID-based revocation
- configurable warning escalation and moderator immunity levels
- offline warning delivery and generated appeal IDs
- UUID-bound in-game mute appeals with a staff review queue; external support links remain available for bans
- Discord embeds with per-type webhooks and an optional appeal button
- optional local GeoLite2 country filtering and an authenticated read-only REST API
- vanilla JSON and adaptive JDBC migration with dry-run support
- English and Russian messages, bStats, and Modrinth update checks
Requirements
- Java 25
- Paper, Purpur, or Folia 26.3
- Velocity 3.4 when using
mBans-Velocity-1.2.1.jar
No external database is required for one backend. A network installation must use one shared MySQL, MariaDB, or PostgreSQL database. Do not share an H2 or SQLite file between processes.
Install on one server
- Put
mBans-1.2.1.jar in the server plugins directory.
- Start the server once.
- Edit
plugins/mBans/config.yml and restart when changing storage or network settings.
H2 is selected by default. Player messages are loaded from lang/en_US.yml; set language.default: ru_RU to use the bundled Russian file.
Install on a Velocity network
- Create one MySQL, MariaDB, or PostgreSQL database.
- Install
mBans-1.2.1.jar on every backend.
- Configure the same database on every backend and give each one a different
network.server-name.
- Install
mBans-Velocity-1.2.1.jar in the Velocity plugins directory.
- Start Velocity once and configure
plugins/mbans-velocity/config.properties with the same JDBC connection.
- Restart the proxy and all backends.
The Velocity module reads the shared punishment tables directly. Install and initialize a backend first so that the schema exists. See the network guide for complete examples.
Configuration
The main sections are:
storage: local file, database engine, connection credentials, pool limits, and optional complete JDBC URL
network: unique backend name and database journal polling interval
templates and durations: reusable reasons and GUI duration choices
escalation: count, time window, resulting action, duration, and reason
immunity and exemptions: permission levels, excluded worlds, and IPv4/IPv6 CIDR ranges
discord: default or per-punishment webhooks and an appeal URL containing <appeal_id>
chat-evidence: in-memory message count available to -last N
geoip: local MMDB filename and ISO country allow/block lists
rest-api: localhost bind, port, and bearer token
appeals: enable in-game submissions and cap message length
metrics and updates: bStats and Modrinth update discovery
Missing defaults are added without replacing existing values. /mbans reload reloads messages and safe settings; storage, network, REST, and GeoIP changes require a restart. See configuration.
Commands
| Command |
Purpose |
/ban <player> [duration] [reason] |
Ban a player permanently or temporarily |
/tempban <player> <duration> [reason] |
Require a temporary ban duration |
/unban <player> [reason] |
Remove an active ban |
/banip <player|ip> [duration] [reason] |
Ban an IP address |
/unbanip <player|ip> |
Remove an IP ban |
/mute, /tempmute, /unmute |
Manage chat mutes |
/ipmute <player|ip> [duration] [reason] |
Mute accounts using an IP address |
/unipmute <player|ip> |
Remove an IP mute |
/shadowmute <player> [duration] [reason] |
Isolate chat without notifying the target |
/tempshadowmute <player> <duration> [reason] |
Require a temporary shadow-mute duration |
/unshadowmute <player> |
Remove a shadow mute |
/appeal <appeal-id> <message> |
Submit an appeal tied to your own punishment |
/warn <player> [reason] |
Add a warning and evaluate escalation rules |
/unwarn <player> <id|all> |
Remove one or all active warnings |
/kick <player> [reason] |
Remove an online player |
/history <player> [page] |
View player punishment history |
/staffhistory <staff> [page] |
View actions issued by a moderator |
/check <player> |
Show active ban, mute, and warning state |
/banlist [page] |
List active bans |
/mutelist [page] |
List active mutes |
/warns <player> |
List active warnings |
/punishment <id> |
Inspect a punishment and its appeal ID |
/alts <player> |
Find accounts with the same recorded IP; alias /dupeip |
/muser <player> |
Open the moderation GUI, including offline records |
/mbans rollback <staff> [time] |
Revoke recent punishments from one moderator |
/mbans revoke <id> [reason] |
Revoke an active punishment by ID |
/mbans reason <id> <reason> |
Correct a stored punishment reason |
/mbans allow <player> [ip-ban-id] |
Exempt one UUID from its active IP ban |
/mbans note <player> <text> |
Add a private staff note |
/mbans notes <player> |
Read recent staff notes |
/mbans stats <staff> |
Show staff action counts |
/mbans appeals [page] |
List open in-game appeals |
/mbans appeal <id> <accept|deny> [note] |
Review an appeal; accepting revokes an active punishment |
/mbans import ... |
Preview or import legacy data |
/mbans export <player> [json|csv] |
Export a player's history |
/mbans reload |
Reload safe configuration and language values |
Durations accept combined units such as 30m, 2h, 7d, and 1mo. Ban, mute, warning, and IP-ban commands accept -s and --evidence=<url>. Ban, mute, and warning commands also accept -last <count> to attach recent chat lines. A template name can replace the reason, for example /ban Steve cheat.
Every administrative command has a matching mbans.command.<name> permission. mbans.admin grants the complete command set. Sensitive IP output requires mbans.view.ip; alt notifications require mbans.notify.alts; staff allowed to observe shadow-muted chat need mbans.notify.shadow. Target exemptions use mbans.bypass.ban, mbans.bypass.mute, mbans.bypass.warn, and mbans.bypass.kick. Replacing an existing ban or mute requires mbans.override; shortening it additionally requires mbans.override.shorten. The -s flag requires mbans.silent.
PlaceholderAPI
When PlaceholderAPI is installed, mBans registers %mbans_banned%, %mbans_muted%, %mbans_warnings%, %mbans_status%, and %mbans_version%. Punishment state is loaded asynchronously and cached for five seconds. The first unresolved request returns an empty value instead of blocking the server thread.
Migration
Always back up the source and destination before importing. Start with --dry-run:
/mbans import vanilla . --dry-run
/mbans import litebans --dry-run
The vanilla profile reads banned-players.json and banned-ips.json. JDBC URLs and credentials are read from imports.<profile> so passwords do not enter command history. JDBC profiles inspect source table metadata and recognize common punishment field names. Review the counts before running the same command without --dry-run. Details and limitations are in the migration guide.
Artifacts
mBans-1.2.1.jar: Paper, Purpur, and Folia backend
mBans-Velocity-1.2.1.jar: Velocity login enforcement
Telemetry and updates
mBans uses bStats plugin ID 33351 for anonymous usage statistics. Disable collection with metrics.enabled: false. The update checker reads the public Modrinth project and can be disabled independently with updates.enabled: false.
Build
./gradlew clean build :velocity:build
The project is licensed under the MIT License.
评论 0
登录后参与评分
还没有评论,来抢沙发吧