FluxBans
你服务器网络一直在等待的处罚管理插件。
运营服务器意味着要处理破坏者、作弊者、有毒玩家以及偶尔出现的封禁规避者。你需要一个能跟上节奏、在所有运行平台上都能工作且无需保姆式照看的处罚系统。FluxBans 通过一个共享数据库,在 Spigot、Paper、Folia、BungeeCord、Velocity 和 NeoForge 上统一管理封禁、静音、踢出和警告。它内置了 Web 仪表板、完整的申诉系统、Discord 通知钩子(Webhooks)和 REST API —— 没有付费层级,没有功能限制,也没有被遗弃的代码库。

平台支持
| 平台 |
JAR 文件 |
支持的版本 |
| Spigot / Paper |
FluxBans-Bukkit.jar |
1.8.8 至 26.x |
| Folia |
FluxBans-Folia.jar |
最新稳定版 |
| BungeeCord |
FluxBans-BungeeCord.jar |
最新稳定版 |
| Velocity |
FluxBans-Velocity.jar |
3.x |
| NeoForge |
FluxBans-Forge.jar |
26.2 |
每个 JAR 文件都是独立的。将它们指向同一个数据库,它们就会自动保持同步。在 BungeeCord 上封禁某人,在他们重新连接之前就会被所有后端阻止。
与其他插件对比
| 功能 |
FluxBans |
LiteBans |
LibertyBans |
AdvancedBan |
BanManager |
CMI |
| 价格 |
免费 |
$15 |
免费 |
免费 |
免费 |
$15 |
| 积极维护中 |
是 |
是 |
是 |
否 |
是 |
是 |
| Spigot / Paper |
是 |
是 |
是 |
是 |
是 |
是 |
| BungeeCord |
是 |
是 |
是 |
否 |
是 |
否 |
| Velocity |
是 |
是 |
是 |
否 |
是 |
否 |
| Folia |
是 |
否 |
否 |
否 |
否 |
否 |
| NeoForge |
是 |
否 |
否 |
否 |
否 |
否 |
| 内置 Web 仪表板 |
是 |
是 |
否 |
否 |
否 |
否 |
| 内置申诉系统 |
是 |
否 |
否 |
否 |
否 |
否 |
| Discord 通知钩子 |
是 |
是 |
否 |
否 |
否 |
是 |
| 通用 HTTP 通知钩子 |
是 |
否 |
否 |
否 |
否 |
否 |
| REST API |
是 |
否 |
否 |
否 |
否 |
否 |
| IP / CIDR 封禁 |
是 |
是 |
是 |
否 |
是 |
是 |
| 自动升级警告 |
是 |
否 |
否 |
是 |
否 |
是 |
| LuckPerms 权重豁免 |
是 |
否 |
否 |
否 |
否 |
否 |
| ProtectCord 支持 |
是 |
否 |
否 |
否 |
否 |
否 |
| 配置热重载 |
是 |
否 |
否 |
否 |
否 |
是 |
| SQLite 支持 |
是 |
是 |
是 |
否 |
是 |
否 |
| MySQL / MariaDB 支持 |
是 |
是 |
是 |
否 |
是 |
是 |
| PostgreSQL 支持 |
是 |
是 |
是 |
否 |
否 |
否 |
| 从其他插件导入数据 |
是 |
否 |
是 |
否 |
否 |
否 |
封禁 (Bans)
封禁会阻止玩家在设定的时间内重新加入服务器。检查发生在连接时,因此他们无法通过登录界面。
/ban <player> [reason] [-s]
/tempban <player> <duration> [reason] [-s]
/banip <player|ip> [reason] [-s]
/unban <player|uuid>
/unbanip <ip>
临时封禁接受如 7d、12h、30m 或组合如 1d12h 这样的持续时间格式。你可以按用户名、UUID、IP 地址或整个 CIDR 子网进行封禁。-s 标志使封禁变为静默模式——详见下方的静默模式部分。
| 权限 |
描述 |
fluxbans.ban |
使用 /ban 命令 |
fluxbans.ban.temp |
使用 /tempban 命令 |
fluxbans.ban.ip |
使用 /banip 和 /unbanip 命令 |
fluxbans.ban.silent |
允许在封禁命令中添加 -s 标志 |
fluxbans.unban |
使用 /unban 命令 |
fluxbans.exempt.ban |
该玩家不能被封禁 |
静音 (Mutes)
静音会阻止玩家发送聊天消息并使用你在 config.yml 的 mute.blocked-commands 下列出的任何命令。检查会在每次聊天事件和被阻止的命令上运行,因此无法通过使用别名来绕过。
/mute <player> [reason] [-s]
/tempmute <player> <duration> [reason] [-s]
/unmute <player>
| 权限 |
描述 |
fluxbans.mute |
使用 /mute 命令 |
fluxbans.mute.temp |
使用 /tempmute 命令 |
fluxbans.mute.silent |
允许在静音命令中添加 -s 标志 |
fluxbans.unmute |
使用 /unmute 命令 |
fluxbans.exempt.mute |
该玩家不能被静音 |
踢出 (Kicks)
踢出会立即断开玩家的连接。除非他们同时被封禁,否则他们可以立即重新连接。
/kick <player> [reason] [-s]
| 权限 |
描述 |
fluxbans.kick |
使用 /kick 命令 |
fluxbans.kick.silent |
允许添加 -s 标志 |
fluxbans.exempt.kick |
该玩家不能被踢出 |
警告 (Warnings)
警告会累积,当玩家达到你在 config.yml 中设置的阈值时,会自动触发处罚。默认情况下,3 个警告会导致 1 小时静音,5 个警告会导致 1 天封禁,10 个警告会导致永久封禁。你可以根据服务器的政策更改所有这些设置。
/warn <player> [reason] [-s]
/unwarn <id>
| 权限 |
描述 |
fluxbans.warn |
使用 /warn 命令 |
fluxbans.warn.remove |
使用 /unwarn 移除特定警告 |
fluxbans.warn.silent |
允许添加 -s 标志 |
fluxbans.exempt.warn |
该玩家不能收到警告 |
静默模式
在任何处罚命令后添加 -s,即可抑制通常广播给所有玩家的消息。只有在线且拥有 fluxbans.notify 权限的管理员才能在他们的聊天中看到该消息。当你不想通过公开宣布封禁而向封禁规避者的朋友透露风声时,这非常有用。
预设理由
在 reasons.yml 中定义快捷方式,这样你的管理员就不必每次都输入相同的内容:
/ban Steve #hacking
/mute Dave #chat-spam
# 前缀会触发预设查找。可以为每个预设锁定持续时间,以防止工作人员意外给予比政策要求更轻的处罚。
信息命令
/check <player> — 提取玩家当前状态的完整快照:活跃封禁、活跃静音、警告次数、IP 地址以及任何关联的备用账号。
/history <player> — 显示曾向该玩家发出的所有处罚记录,包括已过期和已移除的,并附带发出者及时间。
/alts <player> — 显示所有曾从与目标相同 IP 地址连接的账号。
/dupeip <ip> — alts 的反向操作。提供一个 IP 地址,即可查看所有使用过该 IP 的人。
/banlist [page] 和 /mutelist [page] — 在聊天中列出所有当前活跃的封禁或静音,支持分页。
| 权限 |
描述 |
fluxbans.check |
使用 /check |
fluxbans.history |
使用 /history |
fluxbans.alts |
使用 /alts |
fluxbans.dupeip |
使用 /dupeip |
fluxbans.banlist |
使用 /banlist |
fluxbans.mutelist |
使用 /mutelist |
fluxbans.seeip |
在 /check 输出中查看完整 IP 地址 |
豁免与 LuckPerms
任何拥有 fluxbans.exempt.<type> 权限的玩家,都无法被排名低于他们的 staff 处罚。当安装了 LuckPerms 时,FluxBans 会使用基于权重的豁免机制——即使拥有 fluxbans.ban 权限,权重为 50 的管理员也无法封禁权重为 100 的玩家。高级 staff 始终覆盖低级 staff。此功能在不安装 LuckPerms 的情况下也能工作,此时仅回退到纯权限检查。
Web 仪表板
仪表板直接嵌入在 JAR 文件中,使用 NanoHTTPD 实现。无需安装额外组件,也无需单独进程。插件加载时自动启动,可通过 http://your-server-ip:8080 访问(可在 web.yml 中配置)。
任何人都可以查看封禁列表、静音列表和玩家历史记录。搜索并分页浏览记录,点击可查看玩家档案,显示其备用账号、加入历史以及曾对其发出的所有处罚。
持有管理员令牌 (admin token) 的 staff 可以审查并批准或拒绝申诉,手动解除处罚,撰写备注,并浏览完整的操作日志——所有这些功能都在同一个面板中完成。
开发者可以使用 /api/v1/ 处的 REST API 以 JSON 格式拉取数据,用于集成到自己的系统中:
GET /api/v1/bans 分页显示的活跃封禁列表
GET /api/v1/mutes 分页显示的活跃静音列表
GET /api/v1/player/:uuid 玩家的完整处罚历史
GET /api/v1/stats 全服务器范围的统计信息
如果在 web.yml 中提供密钥库 (keystore),则支持 HTTPS。绑定地址、端口、主题、品牌标识和速率限制均可配置。
申诉系统
玩家可直接通过网页发起申诉。无需 Discord 账号、论坛或第三方服务。
- 玩家访问你 Web 面板上的
/appeal
- 输入用户名并撰写申诉内容(50 至 5,000 个字符)
- FluxBans 生成一个唯一的私有链接——例如
/appeal/a3f9c2e1——以便他们后续查看状态
- 触发一个 Discord webhook,使 staff 团队能立即得知
- Staff 前往
/admin,阅读申诉,并点击“批准”或“拒绝”,可选择附带书面回复
- 如果批准,处罚会从数据库中立即移除。玩家可以重新加入服务器,无需执行任何命令
- 触发第二个 webhook 确认结果,玩家的链接更新以显示结果
限制每个 IP 每小时最多提交 3 次申诉。拥有未解决申诉的玩家无法提交新的申诉,直到之前的申诉得到处理。
Webhooks
webhooks:
# 带有丰富嵌入内容的 Discord webhook
- url: "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"
type: discord
enabled: true
events:
- ban
- unban
- mute
- unmute
- kick
- warn
- appeal_new
- appeal_resolved
skip-silent: true
colors:
ban: 15158332
unban: 3066993
mute: 15105570
unmute: 3447003
kick: 10181046
warn: 16776960
appeal_new: 3447003
appeal_resolved: 3066993
# 通用 HTTP webhook,可选 HMAC-SHA256 签名
- url: "https://your-site.com/api/fluxbans-webhook"
type: generic
enabled: true
events:
- appeal_new
- appeal_resolved
secret: "your-hmac-secret"
通用 webhook 会 POST JSON 负载。如果你设置了 secret,每个请求都会使用 X-FluxBans-Signature: sha256=<hex> 进行签名,以便你的端点验证其确实来自 FluxBans。
数据库支持
| 后端 |
说明 |
| SQLite |
内置,零设置 |
| MySQL |
推荐用于网络环境 |
| MariaDB |
完全支持 |
| PostgreSQL |
完全支持 |
所有后端均使用 HikariCP 连接池。架构会在启动时自动创建和迁移。
集成
ProtectCord — 在 config.yml 中启用 protectcord.enabled: true,FluxBans 将从 ProtectCord 元数据中读取真实玩家 IP,以确保通过代理层时 IP 封禁正常工作。
LuckPerms — 自动检测。存在时启用基于权重的 staff 豁免机制。
Vault — 自动检测。存在时从 Vault 获取 staff 显示名称和前缀,并将其纳入 Web UI 记录中。
从其他插件迁移
/fluxbans import litebans
/fluxbans import advancedban
/fluxbans import banmanager
读取现有数据库并将所有内容映射过来。在使用 --dry-run 先预览将导入的内容,确认无误后再正式执行。
完整默认配置
config.yml
# ─────────────────────────────────────────────────────────────
# FluxBans — 主配置文件
# 文档: https://github.com/sneakywrld/fluxbans/wiki
# ─────────────────────────────────────────────────────────────
# ── 数据库 ──────────────────────────────────────────────────
database:
# 后端类型: sqlite | mysql | mariadb | postgresql
type: sqlite
# SQLite — 相对于插件数据文件夹的文件路径
file: fluxbans.db
# MySQL / MariaDB / PostgreSQL 连接设置
host: localhost
port: 3306
name: fluxbans
username: root
password: ""
# 可选的其他 JDBC 属性 (键: 值)
properties: {}
# ── 常规设置 ───────────────────────────────────────────────────
general:
# 在处罚记录和 Web UI 中显示的服务器名称
server-name: "Survival"
# 将所有处罚记录输出到控制台
log-to-console: true
# 向所有在线工作人员(拥有 fluxbans.notify 权限)广播处罚信息
broadcast-to-staff: true
# 向所有在线玩家广播处罚信息
broadcast-globally: true
# 在 /history、/banlist 等命令中每页显示的条目数量
page-size: 10
# 同步间隔(秒)— 当使用共享的 MySQL/MariaDB/PostgreSQL 数据库时,获取跨服务器处罚更新的频率。
# 设置为 0 以禁用(仅多服务器架构需要)。
sync-interval: 30
# 对于没有 fluxbans.seeip 权限的玩家,在 /check 输出中隐藏 IP 地址
hide-ips: true
# 启用除 UUID 封禁之外的 IP 封禁
ip-banning: true
# 如果为 true,按名称封禁玩家时也会封禁其当前 IP
ban-ip-on-ban: false
# ── 豁免设置 ─────────────────────────────────────────────────
exemptions:
# 防止工作人员惩罚拥有更高 LuckPerms 权重的玩家
use-luckperms-weight: true
# ── ProtectCord ───────────────────────────────────────────────
protectcord:
# 当在 BungeeCord / Velocity 代理上使用 ProtectCord 时设为 true。
# FluxBans 将使用真实的转发 IP 而不是代理 IP。
enabled: false
# ── 禁言 ──────────────────────────────────────────────────────
mute:
# 玩家在禁言状态下被阻止的命令。
blocked-commands:
- /say
- /me
- /msg
- /tell
- /w
- /r
- /reply
- /pm
- /dm
- /whisper
# ── 警告 ──────────────────────────────────────────────────
warnings:
# 当玩家达到特定警告阈值时自动执行处罚。
auto-punish:
- count: 3
action: mute
duration: "1h"
reason: "累计 {count} 次警告"
- count: 5
action: ban
duration: "1d"
reason: "累计 {count} 次警告"
- count: 10
action: ban
duration: "perm"
reason: "累计 {count} 次警告 — 永久封禁"
# ── 日期/时间显示格式 ──────────────────────────────────
date-format: "dd MMM yyyy HH:mm:ss"
timezone: "UTC"
messages.yml
# ─────────────────────────────────────────────────────────────
# FluxBans — 消息配置
# 颜色代码:&0-9 &a-f &k-o &r
# 十六进制颜色 (1.16+):&#RRGGBB
# 占位符因上下文而异 — 完整列表请参阅维基。
# ─────────────────────────────────────────────────────────────
prefix: "&8[&cFluxBans&8] &r"
# ── 封禁 ──────────────────────────────────────────────────────
ban:
default-reason: "您已被封禁。"
temp-default-reason: "暂时封禁。"
ip-default-reason: "IP 被封禁。"
kick-message: |
&c&l您已被此服务器封禁。
&7原因:&f{reason}
&7持续时间:&f{duration}
&7到期时间:&f{expires}
&7申诉链接:&b{appeal-url}
&7封禁 ID:&f#{id}
broadcast: "&c{operator} &7封禁了 &c{player} &7» &f{reason} &7[{duration}]"
broadcast-silent: "&c{operator} &7静默封禁了 &c{player} &7» &f{reason} &7[{duration}]"
notify: "{prefix}&7{operator} 封禁了 &c{player} &7» {reason} [{duration}]"
ip-broadcast: "&c{operator} &7封禁了 IP (&c{player} ({ip}) &7» &f{reason} &7[{duration}]"
banned: "{prefix}&a成功封禁 &c{player}&a。"
already-banned: "{prefix}&c{player} &7已被封禁。"
unbanned: "{prefix}&a成功解除对 &c{player}&a 的封禁。"
not-banned: "{prefix}&c{player} &7未被封禁。"
# ── 禁言 ─────────────────────────────────────────────────────
mute:
default-reason: "已禁言。"
temp-default-reason: "暂时禁言。"
broadcast: "&c{operator} &7禁言了 &c{player} &7» &f{reason} &7[{duration}]"
broadcast-silent: "&c{operator} &7静默禁言了 &c{player} &7» &f{reason} &7[{duration}]"
notify: "{prefix}&7{operator} 禁言了 &c{player} &7» {reason} [{duration}]"
muted: "{prefix}&a成功禁言 &c{player}&a。"
already-muted: "{prefix}&c{player} &7已被禁言。"
unmuted: "{prefix}&a成功解除对 &c{player}&a 的禁言。"
not-muted: "{prefix}&c{player} &7未被禁言。"
chat-blocked: |
{prefix}&c您已被禁言。
&7原因:&f{reason}
&7到期时间:&f{expires}
# ── 踢出 ─────────────────────────────────────────────────────
kick:
default-reason: "被踢出。"
kick-message: |
&c&l您已被踢出服务器。
&7原因:&f{reason}
&7操作者:&f{operator}
broadcast: "&c{operator} &7踢出了 &c{player} &7» &f{reason}"
broadcast-silent: "&c{operator} &7静默踢出了 &c{player} &7» &f{reason}"
notify: "{prefix}&7{operator} 踢出了 &c{player} &7» {reason}"
kicked: "{prefix}&a踢出 &c{player}&a。"
# ── 警告 ──────────────────────────────────────────────────
warn:
default-reason: "已警告。"
broadcast: "&e{operator} &7警告了 &e{player} &7» &f{reason}"
broadcast-silent: "&e{operator} &7静默警告了 &e{player} &7» &f{reason}"
notify: "{prefix}&7{operator} 警告了 &e{player} &7» {reason}"
warned: "{prefix}&a警告 &e{player}&a。"
unwarned: "{prefix}&a移除了 &e{player}&a 的第 #{id} 条警告。"
not-warned: "{prefix}&c未找到第 #{id} 条警告。"
received: |
{prefix}&e您被 &c{operator}&e 警告了。
&7原因:&f{reason}
&7当前有效警告总数:&c{count}
# ── 历史记录 ───────────────────────────────────────────────────
history:
header: "{prefix}&7玩家 &c{player} &7的处罚历史(第 {page}/{pages} 页):"
entry: " &8» &7[&c{type}&7] &f{reason} &7by &f{operator} &7on &f{date}"
no-history: "{prefix}&7未找到玩家 &c{player}&7 的处罚历史。"
# ── 检查 ─────────────────────────────────────────────────────
check:
header: "{prefix}&7状态 &c{player}&7:"
banned: " &7封禁:&c是 &7(#{id}) — {reason} — 到期时间 {expires}"
not-banned: " &7封禁:&a无"
muted: " &7静音:&e是 &7(#{id}) — {reason} — 到期时间 {expires}"
not-muted: " &7静音:&a无"
warnings: " &7警告:&e{count} 条有效"
ip: " &7IP:&f{ip}"
# ── 封禁列表 / 静音列表 ────────────────────────────────────────
banlist:
header: "{prefix}&7当前封禁 &7(第 {page}/{pages} 页,共 {count} 条):"
entry: " &8» &c{player} &7由 &f{operator} &7执行 — {reason} &7[{duration}]"
empty: "{prefix}&7没有当前封禁。"
mutelist:
header: "{prefix}&7当前静音 &7(第 {page}/{pages} 页,共 {count} 条):"
entry: " &8» &e{player} &7由 &f{operator} &7执行 — {reason} &7[{duration}]"
empty: "{prefix}&7没有当前静音。"
# ── 小号 ─────────────────────────────────────────────────────
alts:
header: "{prefix}&7与 &c{player}&7 共享 IP 的小号账号:"
entry: " &8» &c{name} &7(最后上线:{date})"
none: "{prefix}&7未找到 &c{player}&7 的小号账号。"
shared-ip: " &7共享 IP:&f{ip}"
# ── 通用错误 ────────────────────────────────────────────
error:
no-permission: "{prefix}&c你没有权限执行此操作。"
player-not-found: "{prefix}&c未找到玩家 &f{player}&c。"
console-only: "{prefix}&c此命令仅能从控制台运行。"
player-only: "{prefix}&c此命令只能由玩家执行。"
invalid-duration: "{prefix}&c无效时长:&f{input}&c。"
player-exempt: "{prefix}&c{player} &7不受此处罚影响。"
self-punish: "{prefix}&c你不能惩罚自己。"
database-error: "{prefix}&c发生数据库错误。请检查控制台。"
usage: "{prefix}&c用法:&f{usage}"
unknown-command: "{prefix}&c未知命令。输入 &f/fluxbans help &c查看命令列表。"
# ── FluxBans 管理 ────────────────────────────────────────────
admin:
reloaded: "{prefix}&a配置已成功重载。"
import-start: "{prefix}&7开始从 &c{plugin}&7 导入..."
import-done: "{prefix}&a导入完成。&7已导入 &c{count} &7条记录。"
import-failed: "{prefix}&c导入失败:&f{error}"
# ── Web 申诉 URL ────────────────────────────────────────────
appeal-url: "http://example.com:8080/appeal"
reasons.yml
# ─────────────────────────────────────────────────────────────
# FluxBans — 预设理由
#
# 工作人员可使用以下预设理由:/ban <player> #hacking
# # 前缀会触发预设理由查找。
#
# 字段:
# display — 发送给玩家并记录在数据库中的理由文本
# duration — 可选的固定时长(工作人员无法覆盖)
# type — 可选类型:ban | mute | kick | warn
# ─────────────────────────────────────────────────────────────
hacking:
display: "作弊 / 使用外挂"
duration: "30d"
type: ban
xray:
display: "X-Ray / 滥用资源包"
duration: "14d"
type: ban
chat-spam:
display: "聊天刷屏"
duration: "1h"
type: mute
advertising:
display: "宣传其他服务器"
duration: "7d"
type: mute
hate-speech:
display: "仇恨言论 / 歧视"
duration: "30d"
type: mute
griefing:
display: "恶意破坏"
duration: "7d"
type: ban
bug-abuse:
display: "滥用漏洞 / 利用程序缺陷"
duration: "7d"
type: ban
inappropriate:
display: "不当行为"
type: warn
ban-evasion:
display: "规避封禁"
duration: "perm"
type: ban
web.yml
# ─────────────────────────────────────────────────────────────
# FluxBans — Web Server Configuration
# ─────────────────────────────────────────────────────────────
web:
enabled: true
# IP to bind to. Use 0.0.0.0 for all interfaces.
bind: "0.0.0.0"
port: 8080
# Base URL used to generate links shown to players in kick messages.
base-url: "http://example.com:8080"
# ── SSL / HTTPS ──────────────────────────────────────────────
ssl:
enabled: false
keystore-path: "ssl/keystore.jks"
keystore-password: "changeme"
port: 8443
# ── Admin panel ───────────────────────────────────────────────
admin:
# Change this to something secure before going live.
token: "CHANGE_THIS_SECRET_TOKEN"
session-timeout: 60
# Restrict admin panel access to specific IPs (empty = allow all)
allowed-ips: []
# ── Rate limiting ─────────────────────────────────────────────
rate-limit:
appeals-per-hour: 3
searches-per-minute: 30
# ── Theme and branding ────────────────────────────────────────
theme:
mode: dark # "dark" or "light"
server-name: "My Minecraft Server"
accent-color: "e74c3c"
server-description: ""
server-ip: ""
logo-url: ""
discord-url: ""
website-url: ""
# ── Privacy ──────────────────────────────────────────────────
privacy:
anonymise-ips: true
public-appeal-form: true
entries-per-page: 20
# ── SEO ──────────────────────────────────────────────────────
seo:
description: "View active bans, mutes, and submit appeals for our Minecraft server."
keywords: "minecraft ban list, mute list, ban appeal, punishment history"
allow-indexing: true
og-image: ""
twitter-site: ""
# Google Analytics 4 measurement ID (e.g. "G-XXXXXXXXXX"). Empty = disabled.
analytics-id: ""
webhooks.yml
# ─────────────────────────────────────────────────────────────
# FluxBans — Webhook 配置
#
# 支持类型:discord | generic
#
# 可用事件:
# ban, unban, mute, unmute, kick, warn,
# appeal_new, appeal_resolved
# ─────────────────────────────────────────────────────────────
webhooks:
-
url: "
type: discord
enabled: false
events:
- ban
- unban
- mute
- unmute
- kick
- warn
- appeal_new
- appeal_resolved
如果为 true,静默惩罚不会触发此 webhook
skip-silent: true
colors:
ban: 15158332 # red
unban: 3066993 # green
mute: 15105570 # orange
unmute: 3447003 # blue
kick: 10181046 # purple
warn: 16776960 # yellow
appeal_new: 3447003 # blue
appeal_resolved: 3066993
-
url: "
type: generic
enabled: false
events:
- appeal_new
- appeal_resolved
可选 — 使用 X-FluxBans-Signature: sha256=<hex> 对每个请求进行签名
secret: ""
</details>
---
## /fluxbans 命令
主要管理员命令。需要权限 `fluxbans.admin`。
/fluxbans reload 无需重启即可重新加载所有配置文件
/fluxbans import <plugin> 从另一个插件的数据库中导入数据
/fluxbans debug 打印版本、数据库状态和当前连接信息
---
## 依赖要求
Java 8 或更高版本。SQLite 已内置,因此单机服务器设置无需数据库服务器。ProtectCord、LuckPerms 和 Vault 均为可选依赖,若存在则会自动检测并加载。
---
<div align="center">
### 实时统计
[](https://bstats.org/plugin/bukkit/FluxBans/31262)
*FluxBans 通过 [bStats](https://bstats.org/plugin/bukkit/FluxBans/31262) 收集匿名使用统计数据。您可以在 `plugins/bStats/config.yml` 中退出统计。*
</div>
FluxBans
The punishment management plugin your network's been waiting for.
Running a server means dealing with griefers, cheaters, toxic players and the occasional ban evader. You need a punishment system that keeps up, works across every platform you're running, and doesn't need babysitting. FluxBans handles bans, mutes, kicks and warnings across Spigot, Paper, Folia, BungeeCord, Velocity and NeoForge from a single shared database. It ships with an embedded web dashboard, a full ban appeals system, Discord webhooks and a REST API — no paid tier, no feature gates, no abandoned repo.

Platform support
| Platform |
JAR |
Supported versions |
| Spigot / Paper |
FluxBans-Bukkit.jar |
1.8.8 to 26.x |
| Folia |
FluxBans-Folia.jar |
Latest stable |
| BungeeCord |
FluxBans-BungeeCord.jar |
Latest stable |
| Velocity |
FluxBans-Velocity.jar |
3.x |
| NeoForge |
FluxBans-Forge.jar |
26.2 |
Every JAR is self-contained. Point them all at the same database and they stay in sync automatically. Ban someone on BungeeCord and they're blocked on every backend before they can reconnect.
How it compares
| Feature |
FluxBans |
LiteBans |
LibertyBans |
AdvancedBan |
BanManager |
CMI |
| Price |
Free |
$15 |
Free |
Free |
Free |
$15 |
| Actively maintained |
Yes |
Yes |
Yes |
No |
Yes |
Yes |
| Spigot / Paper |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
| BungeeCord |
Yes |
Yes |
Yes |
No |
Yes |
No |
| Velocity |
Yes |
Yes |
Yes |
No |
Yes |
No |
| Folia |
Yes |
No |
No |
No |
No |
No |
| NeoForge |
Yes |
No |
No |
No |
No |
No |
| Embedded web dashboard |
Yes |
Yes |
No |
No |
No |
No |
| Built-in appeals system |
Yes |
No |
No |
No |
No |
No |
| Discord webhooks |
Yes |
Yes |
No |
No |
No |
Yes |
| Generic HTTP webhooks |
Yes |
No |
No |
No |
No |
No |
| REST API |
Yes |
No |
No |
No |
No |
No |
| IP / CIDR banning |
Yes |
Yes |
Yes |
No |
Yes |
Yes |
| Auto escalating warnings |
Yes |
No |
No |
Yes |
No |
Yes |
| LuckPerms weight exemptions |
Yes |
No |
No |
No |
No |
No |
| ProtectCord support |
Yes |
No |
No |
No |
No |
No |
| Config hot reload |
Yes |
No |
No |
No |
No |
Yes |
| SQLite support |
Yes |
Yes |
Yes |
No |
Yes |
No |
| MySQL / MariaDB support |
Yes |
Yes |
Yes |
No |
Yes |
Yes |
| PostgreSQL support |
Yes |
Yes |
Yes |
No |
No |
No |
| Import from other plugins |
Yes |
No |
Yes |
No |
No |
No |
Bans
Banning blocks a player from rejoining for the duration you set. The check happens at connection time so they never get past the login screen.
/ban <player> [reason] [-s]
/tempban <player> <duration> [reason] [-s]
/banip <player|ip> [reason] [-s]
/unban <player|uuid>
/unbanip <ip>
Temp bans take durations like 7d, 12h, 30m or combinations like 1d12h. You can ban by username, UUID, IP address or an entire CIDR subnet. The -s flag makes the ban silent — see the silent mode section below.
| Permission |
Description |
fluxbans.ban |
Use /ban |
fluxbans.ban.temp |
Use /tempban |
fluxbans.ban.ip |
Use /banip and /unbanip |
fluxbans.ban.silent |
Add the -s flag to ban commands |
fluxbans.unban |
Use /unban |
fluxbans.exempt.ban |
This player cannot be banned |
Mutes
Muting prevents a player from sending chat messages and using any command you list under mute.blocked-commands in config.yml. The check runs on every chat event and blocked command so it can't be bypassed by using an alias.
/mute <player> [reason] [-s]
/tempmute <player> <duration> [reason] [-s]
/unmute <player>
| Permission |
Description |
fluxbans.mute |
Use /mute |
fluxbans.mute.temp |
Use /tempmute |
fluxbans.mute.silent |
Add the -s flag to mute commands |
fluxbans.unmute |
Use /unmute |
fluxbans.exempt.mute |
This player cannot be muted |
Kicks
Kicks disconnect the player immediately. They can reconnect straight away unless they're also banned.
/kick <player> [reason] [-s]
| Permission |
Description |
fluxbans.kick |
Use /kick |
fluxbans.kick.silent |
Add the -s flag |
fluxbans.exempt.kick |
This player cannot be kicked |
Warnings
Warnings accumulate and trigger automatic punishments when a player hits the thresholds you set in config.yml. By default that's a 1 hour mute at 3 warnings, a 1 day ban at 5, and a permanent ban at 10. You can change all of that to whatever your server policy is.
/warn <player> [reason] [-s]
/unwarn <id>
| Permission |
Description |
fluxbans.warn |
Use /warn |
fluxbans.warn.remove |
Use /unwarn to remove a specific warning |
fluxbans.warn.silent |
Add the -s flag |
fluxbans.exempt.warn |
This player cannot be warned |
Silent mode
Add -s to any punishment command and the broadcast that normally goes to all players is suppressed. Only staff members online with fluxbans.notify will see it in their chat. Useful when you don't want to tip off a ban evader's friends by announcing the ban publicly.
Preset reasons
Define shortcuts in reasons.yml so your staff don't have to type the same thing every time:
/ban Steve #hacking
/mute Dave #chat-spam
The # prefix triggers a preset lookup. Durations can be locked per preset so staff can't accidentally give someone a lighter punishment than your policy requires.
Information commands
/check <player> — pulls up a full snapshot of a player's current status: active ban, active mute, warning count, IP address and any linked alt accounts.
/history <player> — shows every punishment ever issued to a player, including expired and removed ones, with who issued them and when.
/alts <player> — shows every account that has ever connected from the same IP addresses as the target.
/dupeip <ip> — the reverse of alts. Give it an IP and see everyone who has used it.
/banlist [page] and /mutelist [page] — lists all currently active bans or mutes in chat, paginated.
| Permission |
Description |
fluxbans.check |
Use /check |
fluxbans.history |
Use /history |
fluxbans.alts |
Use /alts |
fluxbans.dupeip |
Use /dupeip |
fluxbans.banlist |
Use /banlist |
fluxbans.mutelist |
Use /mutelist |
fluxbans.seeip |
See full IP addresses in /check output |
Exemptions and LuckPerms
Any player with fluxbans.exempt.<type> cannot be punished by staff who don't outrank them. When LuckPerms is installed, FluxBans uses weight-based exemption — a moderator with weight 50 can't ban a player with weight 100 even if they have fluxbans.ban. Senior staff always override junior staff. Works without LuckPerms too, it just falls back to permission-only checks.
Web dashboard
The dashboard is embedded directly in the JAR using NanoHTTPD. Nothing to install, no separate process. It starts when the plugin loads and is accessible at http://your-server-ip:8080 (configurable in web.yml).
Anyone can see the ban list, mute list and player history. Search and paginate through records, click through to a player profile showing their alt accounts, join history and everything ever issued against them.
Staff with the admin token can review and approve or deny appeals, manually lift punishments, write notes, and browse the full action log — all from the same panel.
Developers can use the REST API at /api/v1/ to pull data as JSON for their own integrations:
GET /api/v1/bans Paginated list of active bans
GET /api/v1/mutes Paginated list of active mutes
GET /api/v1/player/:uuid Full punishment history for a player
GET /api/v1/stats Server-wide moderation statistics
HTTPS is supported if you provide a keystore in web.yml. Bind address, port, theme, branding and rate limits are all configurable.
Appeals system
Players appeal directly from the web. No Discord account, no forum, no third party service.
- Player visits
/appeal on your web panel
- They enter their username and write their appeal (50 to 5,000 characters)
- FluxBans generates a unique private link — something like
/appeal/a3f9c2e1 — so they can check back on the status
- A Discord webhook fires so your staff team knows straight away
- Staff go to
/admin, read the appeal, and click Approve or Deny with an optional written response
- If approved, the punishment is removed from the database immediately. Player can rejoin, no command needed
- A second webhook fires confirming the outcome and the player's link updates to show the result
Rate limited to 3 submissions per hour per IP. Players with an open appeal can't submit another until it's resolved.
Webhooks
webhooks:
# Discord webhook with rich embeds
- url: "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"
type: discord
enabled: true
events:
- ban
- unban
- mute
- unmute
- kick
- warn
- appeal_new
- appeal_resolved
skip-silent: true
colors:
ban: 15158332
unban: 3066993
mute: 15105570
unmute: 3447003
kick: 10181046
warn: 16776960
appeal_new: 3447003
appeal_resolved: 3066993
# Generic HTTP webhook with optional HMAC-SHA256 signing
- url: "https://your-site.com/api/fluxbans-webhook"
type: generic
enabled: true
events:
- appeal_new
- appeal_resolved
secret: "your-hmac-secret"
Generic webhooks POST a JSON payload. If you set a secret, every request is signed with X-FluxBans-Signature: sha256=<hex> so your endpoint can verify it came from FluxBans.
Database support
| Backend |
Notes |
| SQLite |
Bundled, zero setup |
| MySQL |
Recommended for networks |
| MariaDB |
Full support |
| PostgreSQL |
Full support |
All backends use HikariCP connection pooling. The schema creates and migrates itself on startup.
Integrations
ProtectCord — enable with protectcord.enabled: true in config.yml and FluxBans will read the real player IP from ProtectCord metadata so IP bans work correctly through the proxy layer.
LuckPerms — auto-detected. Enables weight-based staff exemptions when present.
Vault — auto-detected. Pulls staff display names and prefixes into web UI records when present.
Migrating from another plugin
/fluxbans import litebans
/fluxbans import advancedban
/fluxbans import banmanager
Reads your existing database and maps everything across. Use --dry-run first to preview what will be imported before it touches anything.
Full default configuration
config.yml
# ─────────────────────────────────────────────────────────────
# FluxBans — Main Configuration
# Documentation: https://github.com/sneakywrld/fluxbans/wiki
# ─────────────────────────────────────────────────────────────
# ── Database ──────────────────────────────────────────────────
database:
# Backend type: sqlite | mysql | mariadb | postgresql
type: sqlite
# SQLite — file path relative to the plugin data folder
file: fluxbans.db
# MySQL / MariaDB / PostgreSQL connection settings
host: localhost
port: 3306
name: fluxbans
username: root
password: ""
# Optional additional JDBC properties (key: value)
properties: {}
# ── General ───────────────────────────────────────────────────
general:
# Server name shown in punishment records and the web UI
server-name: "Survival"
# Log all punishments to the console
log-to-console: true
# Broadcast a punishment to all online staff (fluxbans.notify permission)
broadcast-to-staff: true
# Broadcast a punishment to all online players
broadcast-globally: true
# How many entries to show per page in /history, /banlist etc.
page-size: 10
# Sync interval (seconds) — how often to fetch cross-server punishment
# updates when using a shared MySQL/MariaDB/PostgreSQL database.
# Set to 0 to disable (only needed for multi-server setups).
sync-interval: 30
# Hide IP addresses from /check output for players without fluxbans.seeip
hide-ips: true
# Enable IP banning in addition to UUID banning
ip-banning: true
# If true, banning a player by name also bans their current IP
ban-ip-on-ban: false
# ── Exemption ─────────────────────────────────────────────────
exemptions:
# Prevent staff from punishing players with a higher LuckPerms weight
use-luckperms-weight: true
# ── ProtectCord ───────────────────────────────────────────────
protectcord:
# Set to true when using ProtectCord on your BungeeCord / Velocity proxy.
# FluxBans will use the real forwarded IP instead of the proxy IP.
enabled: false
# ── Mute ──────────────────────────────────────────────────────
mute:
# Commands blocked while a player is muted.
blocked-commands:
- /say
- /me
- /msg
- /tell
- /w
- /r
- /reply
- /pm
- /dm
- /whisper
# ── Warnings ──────────────────────────────────────────────────
warnings:
# Auto-punish a player when they reach certain warning thresholds.
auto-punish:
- count: 3
action: mute
duration: "1h"
reason: "Accumulated {count} warnings"
- count: 5
action: ban
duration: "1d"
reason: "Accumulated {count} warnings"
- count: 10
action: ban
duration: "perm"
reason: "Accumulated {count} warnings — permanent ban"
# ── Date/time display format ──────────────────────────────────
date-format: "dd MMM yyyy HH:mm:ss"
timezone: "UTC"
messages.yml
# ─────────────────────────────────────────────────────────────
# FluxBans — Messages Configuration
# Colour codes: &0-9 &a-f &k-o &r
# Hex colours (1.16+): &#RRGGBB
# Placeholders vary by context — see the wiki for a full list.
# ─────────────────────────────────────────────────────────────
prefix: "&8[&cFluxBans&8] &r"
# ── Bans ──────────────────────────────────────────────────────
ban:
default-reason: "You have been banned."
temp-default-reason: "Temporarily banned."
ip-default-reason: "IP banned."
kick-message: |
&c&lYou are banned from this server.
&7Reason: &f{reason}
&7Duration: &f{duration}
&7Expires: &f{expires}
&7Appeal at: &b{appeal-url}
&7Ban ID: &f#{id}
broadcast: "&c{operator} &7banned &c{player} &7» &f{reason} &7[{duration}]"
broadcast-silent: "&c{operator} &7silently banned &c{player} &7» &f{reason} &7[{duration}]"
notify: "{prefix}&7{operator} banned &c{player} &7» {reason} [{duration}]"
ip-broadcast: "&c{operator} &7IP-banned &c{player} ({ip}) &7» &f{reason} &7[{duration}]"
banned: "{prefix}&aSuccessfully banned &c{player}&a."
already-banned: "{prefix}&c{player} &7is already banned."
unbanned: "{prefix}&aSuccessfully unbanned &c{player}&a."
not-banned: "{prefix}&c{player} &7is not banned."
# ── Mutes ─────────────────────────────────────────────────────
mute:
default-reason: "Muted."
temp-default-reason: "Temporarily muted."
broadcast: "&c{operator} &7muted &c{player} &7» &f{reason} &7[{duration}]"
broadcast-silent: "&c{operator} &7silently muted &c{player} &7» &f{reason} &7[{duration}]"
notify: "{prefix}&7{operator} muted &c{player} &7» {reason} [{duration}]"
muted: "{prefix}&aSuccessfully muted &c{player}&a."
already-muted: "{prefix}&c{player} &7is already muted."
unmuted: "{prefix}&aSuccessfully unmuted &c{player}&a."
not-muted: "{prefix}&c{player} &7is not muted."
chat-blocked: |
{prefix}&cYou are muted.
&7Reason: &f{reason}
&7Expires: &f{expires}
# ── Kicks ─────────────────────────────────────────────────────
kick:
default-reason: "Kicked."
kick-message: |
&c&lYou were kicked from the server.
&7Reason: &f{reason}
&7By: &f{operator}
broadcast: "&c{operator} &7kicked &c{player} &7» &f{reason}"
broadcast-silent: "&c{operator} &7silently kicked &c{player} &7» &f{reason}"
notify: "{prefix}&7{operator} kicked &c{player} &7» {reason}"
kicked: "{prefix}&aKicked &c{player}&a."
# ── Warnings ──────────────────────────────────────────────────
warn:
default-reason: "Warned."
broadcast: "&e{operator} &7warned &e{player} &7» &f{reason}"
broadcast-silent: "&e{operator} &7silently warned &e{player} &7» &f{reason}"
notify: "{prefix}&7{operator} warned &e{player} &7» {reason}"
warned: "{prefix}&aWarned &e{player}&a."
unwarned: "{prefix}&aRemoved warning #{id} from &e{player}&a."
not-warned: "{prefix}&cWarning #{id} not found."
received: |
{prefix}&eYou have been warned by &c{operator}&e.
&7Reason: &f{reason}
&7Total active warnings: &c{count}
# ── History ───────────────────────────────────────────────────
history:
header: "{prefix}&7Punishment history for &c{player} &7(page {page}/{pages}):"
entry: " &8» &7[&c{type}&7] &f{reason} &7by &f{operator} &7on &f{date}"
no-history: "{prefix}&7No punishment history found for &c{player}&7."
# ── Check ─────────────────────────────────────────────────────
check:
header: "{prefix}&7Status for &c{player}&7:"
banned: " &7Ban: &cYes &7(#{id}) — {reason} — expires {expires}"
not-banned: " &7Ban: &aNone"
muted: " &7Mute: &eYes &7(#{id}) — {reason} — expires {expires}"
not-muted: " &7Mute: &aNone"
warnings: " &7Warnings: &e{count} active"
ip: " &7IP: &f{ip}"
# ── Banlist / Mutelist ────────────────────────────────────────
banlist:
header: "{prefix}&7Active bans &7(page {page}/{pages}, total: {count}):"
entry: " &8» &c{player} &7by &f{operator} &7— {reason} &7[{duration}]"
empty: "{prefix}&7No active bans."
mutelist:
header: "{prefix}&7Active mutes &7(page {page}/{pages}, total: {count}):"
entry: " &8» &e{player} &7by &f{operator} &7— {reason} &7[{duration}]"
empty: "{prefix}&7No active mutes."
# ── Alts ─────────────────────────────────────────────────────
alts:
header: "{prefix}&7Alt accounts sharing IP with &c{player}&7:"
entry: " &8» &c{name} &7(last seen: {date})"
none: "{prefix}&7No alt accounts found for &c{player}&7."
shared-ip: " &7Shared IP: &f{ip}"
# ── General errors ────────────────────────────────────────────
error:
no-permission: "{prefix}&cYou do not have permission to do that."
player-not-found: "{prefix}&cPlayer &f{player} &cnot found."
console-only: "{prefix}&cThis command can only be run from the console."
player-only: "{prefix}&cThis command can only be run by a player."
invalid-duration: "{prefix}&cInvalid duration: &f{input}&c."
player-exempt: "{prefix}&c{player} &7is exempt from this punishment."
self-punish: "{prefix}&cYou cannot punish yourself."
database-error: "{prefix}&cA database error occurred. Please check the console."
usage: "{prefix}&cUsage: &f{usage}"
unknown-command: "{prefix}&cUnknown command. Type &f/fluxbans help &cfor a list."
# ── FluxBans admin ────────────────────────────────────────────
admin:
reloaded: "{prefix}&aConfiguration reloaded successfully."
import-start: "{prefix}&7Starting import from &c{plugin}&7..."
import-done: "{prefix}&aImport complete. &7Imported &c{count} &7records."
import-failed: "{prefix}&cImport failed: &f{error}"
# ── Web appeal URL ────────────────────────────────────────────
appeal-url: "http://example.com:8080/appeal"
reasons.yml
# ─────────────────────────────────────────────────────────────
# FluxBans — Preset Reasons
#
# Staff can use these with: /ban <player> #hacking
# The # prefix triggers a preset reason lookup.
#
# Fields:
# display — reason text sent to the player and logged in DB
# duration — optional locked duration (staff cannot override)
# type — optional: ban | mute | kick | warn
# ─────────────────────────────────────────────────────────────
hacking:
display: "Hacking / Cheating"
duration: "30d"
type: ban
xray:
display: "X-Ray / Resource pack abuse"
duration: "14d"
type: ban
chat-spam:
display: "Chat spam"
duration: "1h"
type: mute
advertising:
display: "Advertising other servers"
duration: "7d"
type: mute
hate-speech:
display: "Hate speech / Discrimination"
duration: "30d"
type: mute
griefing:
display: "Griefing"
duration: "7d"
type: ban
bug-abuse:
display: "Bug / Exploit abuse"
duration: "7d"
type: ban
inappropriate:
display: "Inappropriate behaviour"
type: warn
ban-evasion:
display: "Ban evasion"
duration: "perm"
type: ban
web.yml
# ─────────────────────────────────────────────────────────────
# FluxBans — Web Server Configuration
# ─────────────────────────────────────────────────────────────
web:
enabled: true
# IP to bind to. Use 0.0.0.0 for all interfaces.
bind: "0.0.0.0"
port: 8080
# Base URL used to generate links shown to players in kick messages.
base-url: "http://example.com:8080"
# ── SSL / HTTPS ──────────────────────────────────────────────
ssl:
enabled: false
keystore-path: "ssl/keystore.jks"
keystore-password: "changeme"
port: 8443
# ── Admin panel ───────────────────────────────────────────────
admin:
# Change this to something secure before going live.
token: "CHANGE_THIS_SECRET_TOKEN"
session-timeout: 60
# Restrict admin panel access to specific IPs (empty = allow all)
allowed-ips: []
# ── Rate limiting ─────────────────────────────────────────────
rate-limit:
appeals-per-hour: 3
searches-per-minute: 30
# ── Theme and branding ────────────────────────────────────────
theme:
mode: dark # "dark" or "light"
server-name: "My Minecraft Server"
accent-color: "e74c3c"
server-description: ""
server-ip: ""
logo-url: ""
discord-url: ""
website-url: ""
# ── Privacy ──────────────────────────────────────────────────
privacy:
anonymise-ips: true
public-appeal-form: true
entries-per-page: 20
# ── SEO ──────────────────────────────────────────────────────
seo:
description: "View active bans, mutes, and submit appeals for our Minecraft server."
keywords: "minecraft ban list, mute list, ban appeal, punishment history"
allow-indexing: true
og-image: ""
twitter-site: ""
# Google Analytics 4 measurement ID (e.g. "G-XXXXXXXXXX"). Empty = disabled.
analytics-id: ""
webhooks.yml
# ─────────────────────────────────────────────────────────────
# FluxBans — Webhook Configuration
#
# Supported types: discord | generic
#
# Available events:
# ban, unban, mute, unmute, kick, warn,
# appeal_new, appeal_resolved
# ─────────────────────────────────────────────────────────────
webhooks:
- url: "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"
type: discord
enabled: false
events:
- ban
- unban
- mute
- unmute
- kick
- warn
- appeal_new
- appeal_resolved
# If true, silent punishments will NOT fire this webhook
skip-silent: true
colors:
ban: 15158332 # red
unban: 3066993 # green
mute: 15105570 # orange
unmute: 3447003 # blue
kick: 10181046 # purple
warn: 16776960 # yellow
appeal_new: 3447003 # blue
appeal_resolved: 3066993
- url: "https://your-site.com/api/fluxbans-webhook"
type: generic
enabled: false
events:
- appeal_new
- appeal_resolved
# Optional — signs each request with X-FluxBans-Signature: sha256=<hex>
secret: ""
/fluxbans command
The main admin command. Requires fluxbans.admin.
/fluxbans reload Reloads all config files without restarting
/fluxbans import <plugin> Imports data from another plugin's database
/fluxbans debug Prints version, database status and active connections
Requirements
Java 8 or newer. SQLite is bundled so there's no database server needed for a single server setup. ProtectCord, LuckPerms and Vault are all optional and get picked up automatically if they're present.
Live stats
FluxBans collects anonymous usage statistics via bStats. You can opt out in plugins/bStats/config.yml.
评论 0
登录后参与评分
还没有评论,来抢沙发吧