这是原版 MCBans 插件的重构分支。 封禁共享概念、命令结构和权限布局均源自 MCBans 团队及其贡献者。本分支将代码库现代化以适配 Java 21 / Paper 1.21+,并用 PvPIndex REST API 替换了旧的 MCBans 后端。
PvPIndex MCBans 将你的 Paper 服务器连接到 mcbans.pvpindex.com 全球封禁网络。在任何参与服务器上被封禁的玩家将在其他所有服务器上自动被拦截——同时你完全掌控本地封禁、存储后端和权限级别。
功能
- 全局与本地封禁 - 发布本地封禁(仅保留在你的服务器上)或实时同步到所有连接服务器的全局封禁
- 临时封禁 - 限时封禁,支持按分钟、小时、天或周自动过期
- IP 封禁 - 通过 IP 地址封禁,以阻止 VPN 滥用和规避封禁
- 理由预设 - 在配置中定义简写键(
#hacks, #toxicity),展开为完整的理由字符串;扩展形式支持用于临时封禁的 default-duration;不区分大小写并支持 Tab 补全
- 自定义踢出消息 - 每种类型(
global, local, temp, failsafe)的模板,包含 {reason}, {admin}, {expires} 和 {appeal_url} 占位符
- 离线韧性 - 在 API 中断期间发布的封禁会被排队并在恢复时推送;当 API 不可达时,
failsafe 模式可以阻止所有登录
- 增量同步 - 仅在可配置的间隔内下载封禁变更(默认 60 分钟)
- 多种存储后端 - SQLite(默认,零配置)、MySQL/MariaDB、PostgreSQL
- 小号检测 -
/altlookup 通过 PvPIndex API 显示已知的小号
- 开发者 API (JitPack) - 轻量级
pvpindex-mcbans-api 模块允许其他插件查询封禁状态,无需 Bukkit 依赖
- Vault 集成 - 可选;只需更改一行配置即可交换权限后端
- 完全可翻译 - 更改
language 键以加载不同的语言文件
要求
安装
- 从 GitHub Releases 下载
pvpindex-mcbans-<version>.jar。
- 将 JAR 放入
plugins/ 目录并启动服务器 - plugins/MCBans/config.yml 会自动生成。
- 申请 API 密钥 并将其粘贴到配置中:
pvpindex:
apiKey: "your-bearer-token-here"
- 使用
/mcbans reload 重新加载或重启服务器。
- 运行
/mcbans sync 从网络拉取当前的封禁列表。
→ 完整指南:docs.pvpindex.com/mcbans/installation
命令
封禁命令
| 命令 |
权限 |
描述 |
/ban <player> [reason] |
mcbans.ban.local |
发布本地封禁 |
/ban <player> g <reason> · /gban |
mcbans.ban.global |
发布全局封禁(全网同步) |
/ban <player> t <n> <m|h|d|w> [reason] · /tban |
mcbans.ban.temp |
带自动过期的临时封禁 |
/banip <ip> [reason] · /ipban |
mcbans.ban.ip |
封禁一个 IP 地址 |
/unban <player|IP|UUID> |
mcbans.unban |
移除任何活跃封禁 |
管理命令
| 命令 |
权限 |
描述 |
/kick <player> [reason] |
mcbans.kick |
踢出玩家而不封禁 |
/lookup <player|UUID> · /lup |
mcbans.lookup.player |
查看封禁历史 |
/banlookup <id> · /blup |
mcbans.lookup.ban |
按 ID 查看封禁记录 |
/altlookup <player|UUID> · /alup |
mcbans.lookup.alt |
显示已知的小号 |
管理员命令
| 命令 |
描述 |
/mcbans |
显示帮助 |
/mcbans reload |
重新加载配置和语言文件 |
/mcbans sync |
强制立即执行推送 + 下载循环 |
/mcbans presets |
列出所有配置的理由预设 (mcbans.ban.local) |
配置
pvpindex:
apiUrl: https://api.pvpindex.com
apiKey: "" # ← 在此粘贴你的密钥
syncInterval: 60 # 后台同步间隔(分钟)
storage:
backend: sqlite # sqlite | mysql | postgresql
language: default
permission: SuperPerms # SuperPerms | Vault
failsafe: false # true = 当 API 不可达时阻止所有登录
# 可选:自定义发送给被封禁/踢出玩家的消息
kick-message:
global: "&cYou are globally banned.\n&7Reason: {reason}\n&7Appeal: {appeal_url}"
local: "&cYou are banned from this server.\n&7Reason: {reason}"
temp: "&cYou are temporarily banned until {expires}.\n&7Reason: {reason}"
failsafe: "&cUnable to verify your ban status. Try again later."
# 可选:可在所有封禁命令中使用的简写理由键
reason-presets:
hacks:
reason: "Hacking / using unauthorized modifications"
toxicity:
reason: "Toxic behaviour"
farming:
reason: "Ban/ELO farming"
default-duration: "7d"
→ 完整参考:docs.pvpindex.com/mcbans/configuration
开发者 API (JitPack)
将轻量级 API 客户端添加到你自己的插件中 - 不需要 Bukkit 依赖:
<repositories>
<repository>
<id>jitpack</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependency>
<groupId>com.github.PVP-Index.pvpindex-mcbans</groupId>
<artifactId>pvpindex-mcbans-api</artifactId>
<version>1.1.0</version>
</dependency>
→ 开发者 API 文档
链接
PvPIndex 与 NeyHost 合作
结账时使用优惠券代码 PVPINDEX 可享受 10% 折扣。

致谢
PvPIndex MCBans 是原始 MCBans 插件的重新架构分支,该插件由 MCBans 团队及贡献者开发(dev.bukkit.org/projects/mcbans)。其封禁共享概念、TCP 线协议、命令集以及权限布局均源自该项目。本分支针对 Java 21 / Paper 1.21+ 对代码库进行了现代化改造,并将传统的 MCBans 后端替换为 PvPIndex REST API。
This is a refactored fork of the original MCBans plugin. The ban-sharing concept, command structure, and permission layout originate from the MCBans team and their contributors. This fork modernises the codebase for Java 21 / Paper 1.21+ and replaces the legacy MCBans backend with the PvPIndex REST API.
PvPIndex MCBans connects your Paper server to the mcbans.pvpindex.com global ban network. Players banned on any participating server are automatically blocked everywhere else - while you keep full control over local bans, storage backends, and permission levels.
Features
- Global & local bans - issue a local ban (stays on your server) or a global ban synced to all connected servers in real time
- Temporary bans - time-limited with auto-expiry in minutes, hours, days, or weeks
- IP bans - ban by IP address to block VPN abuse and ban evasion
- Reason presets - define shorthand keys in config (
#hacks, #toxicity) that expand to full reason strings; extended form supports a default-duration for temp bans; case-insensitive with tab-completion
- Customizable kick messages - per-type templates (
global, local, temp, failsafe) with {reason}, {admin}, {expires}, and {appeal_url} placeholders
- Offline resilience - bans issued during API outages are queued and pushed on recovery;
failsafe mode can block all logins when the API is unreachable
- Delta sync - downloads only ban changes on a configurable interval (default 60 min)
- Multiple storage backends - SQLite (default, zero-config), MySQL/MariaDB, PostgreSQL
- Alt-account detection -
/altlookup surfaces known alternate accounts via the PvPIndex API
- Developer API (JitPack) - lightweight
pvpindex-mcbans-api module lets other plugins query ban status without a Bukkit dependency
- Vault integration - optional; swap the permission backend in one config line
- Fully translatable - swap the
language key to load a different locale file
Requirements
| Component |
Version |
| Java |
21+ |
| Paper |
1.21+ |
| PvPIndex API key |
Free at pvpindex.com/apply |
| Vault (optional) |
Any recent version |
Installation
- Download
pvpindex-mcbans-<version>.jar from GitHub Releases.
- Drop the JAR into
plugins/ and start the server - plugins/MCBans/config.yml is generated automatically.
- Apply for an API key and paste it into config:
pvpindex:
apiKey: "your-bearer-token-here"
- Reload with
/mcbans reload or restart.
- Run
/mcbans sync to pull the current ban list from the network.
→ Full guide: docs.pvpindex.com/mcbans/installation
Commands
Ban commands
| Command |
Permission |
Description |
/ban <player> [reason] |
mcbans.ban.local |
Issue a local ban |
/ban <player> g <reason> · /gban |
mcbans.ban.global |
Issue a global ban (synced network-wide) |
/ban <player> t <n> <m|h|d|w> [reason] · /tban |
mcbans.ban.temp |
Temporary ban with auto-expiry |
/banip <ip> [reason] · /ipban |
mcbans.ban.ip |
Ban an IP address |
/unban <player|IP|UUID> |
mcbans.unban |
Remove any active ban |
Moderation commands
| Command |
Permission |
Description |
/kick <player> [reason] |
mcbans.kick |
Kick without banning |
/lookup <player|UUID> · /lup |
mcbans.lookup.player |
View ban history |
/banlookup <id> · /blup |
mcbans.lookup.ban |
View a ban record by ID |
/altlookup <player|UUID> · /alup |
mcbans.lookup.alt |
Show known alternate accounts |
Admin commands
| Command |
Description |
/mcbans |
Show help |
/mcbans reload |
Reload config and language files |
/mcbans sync |
Force an immediate push + download cycle |
/mcbans presets |
List all configured reason presets (mcbans.ban.local) |
Configuration
pvpindex:
apiUrl: https://api.pvpindex.com
apiKey: "" # ← paste your key here
syncInterval: 60 # background sync in minutes
storage:
backend: sqlite # sqlite | mysql | postgresql
language: default
permission: SuperPerms # SuperPerms | Vault
failsafe: false # true = block all logins when API unreachable
# Optional: customise the message shown to banned/kicked players
kick-message:
global: "&cYou are globally banned.\n&7Reason: {reason}\n&7Appeal: {appeal_url}"
local: "&cYou are banned from this server.\n&7Reason: {reason}"
temp: "&cYou are temporarily banned until {expires}.\n&7Reason: {reason}"
failsafe: "&cUnable to verify your ban status. Try again later."
# Optional: shorthand reason keys usable in all ban commands
reason-presets:
hacks:
reason: "Hacking / using unauthorized modifications"
toxicity:
reason: "Toxic behaviour"
farming:
reason: "Ban/ELO farming"
default-duration: "7d"
→ Full reference: docs.pvpindex.com/mcbans/configuration
Developer API (JitPack)
Add the lightweight API client to your own plugin - no Bukkit dependency required:
<repositories>
<repository>
<id>jitpack</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependency>
<groupId>com.github.PVP-Index.pvpindex-mcbans</groupId>
<artifactId>pvpindex-mcbans-api</artifactId>
<version>1.1.0</version>
</dependency>
→ Developer API documentation
Links
PvPIndex is partnered with NeyHost
Use the coupon code PVPINDEX for 10% off on checkout.

Credits
PvPIndex MCBans is a refactored fork of the original MCBans plugin by the MCBans team and contributors (dev.bukkit.org/projects/mcbans). The ban-sharing concept, TCP wire protocol, command set, and permission layout all originate from that project. This fork modernises the codebase for Java 21 / Paper 1.21+ and replaces the legacy MCBans backend with the PvPIndex REST API.
评论 0
登录后参与评分
还没有评论,来抢沙发吧