?️ GeyserGuard
GeyserGuard 为 Geyser 流量添加了一层防御性 UDP 保护机制,在数据包到达网络栈中开销较大的部分之前,拦截空数据包、格式错误的网际数据报(datagrams)、快速突发流量以及滥用型发包速率。适用于 Spigot/Paper/Purpur(单服务器)和 Velocity(代理全局)环境。
防护内容
- 空 UDP 数据包
- 格式错误或体积过大的网际数据报
- 针对单个 IP 的发包洪水(每秒发包数限制),采用基于警告次数的升级机制,确保单次突发不会误封合法玩家
- 所有连接中的全局发包速率峰值
- 重复出现的可疑数据包,将触发临时 IP 封禁
- Ping 洪水 / 服务器列表扫描 — 可选择完全静默 Bedrock ping 请求的回复,从而向扫描器隐藏服务器,同时不阻挡真实玩家连接
- IPv6 子网感知式封禁(封禁整个 /64 块而非单个地址,因为攻击者可以在一个子网内轮换数十亿个独立 IPv6 地址)
- 由伪造 IP 洪水导致的内存耗尽(OOM) — 不仅主过滤器,所有内部跟踪结构均设有上限,并优先驱逐最旧的条目
- 控制台/日志垃圾信息抑制 — 格式错误的 Bedrock/RakNet 数据包(有效数据包 ID 但载荷被截断)通常会在控制台中引发大量的 Netty/Geyser 异常警告;GeyserGuard 会静默捕获这些数据包并封禁肇事 IP,而不是刷屏日志
⚙️ 功能特性
- 可配置的每秒发包数限制,支持按 IP 和全局设置
- 基于警告次数的速率限制:需在连续多个时间窗口内持续洪水攻击才会封禁,因此重连突发、延迟 spike 或多个真实玩家共享同一 CGNAT/移动 IP 的情况不会被误封
- 可选的 ping 响应抑制功能,用于向 Bedrock 服务器列表扫描器和 ping 洪水工具隐藏服务器,对真实连接零影响
- 可配置的最小/最大数据包大小过滤
- 临时封禁,支持自定义持续时间与可疑命中阈值
- 基于阈值的攻击警报 — 仅当被阻止的数据包累积超过可配置数量(或在实际封禁时立即)才提升为控制台/聊天警告,避免无害的单次丢弃被误认为正在进行中的攻击
- 持久化本地封禁数据库(重启后封禁记录依然存在)
- IP/CIDR 白名单,用于信任的地址(如你自己的服务器、反向代理、负载均衡器等),支持无需重启即可重载
- 面向管理员的游戏内和控制台警报,支持可选的 IP 掩码处理
- 自动内存保护:跟踪可配置的最大 IP 数量,并优先驱逐最久未活动的 IP,防止因伪造 IP 洪水导致内存耗尽
- 双语支持(英语/西班牙语),通过
config.yml 配置
- 低开销,无需外部依赖
命令与权限
| 命令 |
权限 |
描述 |
/geyserguard status |
geyserguard.admin |
显示当前保护状态 |
/geyserguard stats |
geyserguard.admin |
显示来源 IP 前几名及被阻止的事件 |
/geyserguard bans |
geyserguard.admin |
显示已存储的封禁记录,包含原因和时间 |
/geyserguard unban <IP> |
geyserguard.admin |
移除单个 IP 的临时封禁 |
/geyserguard reload |
geyserguard.admin |
重载 config.yml(包括白名单) |
| — |
geyserguard.alerts |
接收游戏内的攻击警报 |
OP 玩家默认拥有所有权限。如需手动授予,请使用 LuckPerms 等权限插件。
为什么使用它?
通过 Geyser 接受 Bedrock 玩家的服务器暴露了一个 UDP 监听端口,容易受到直接针对该端口的数据包洪水、伪造 IP 和格式错误数据包的攻击 —— 这些攻击可以绕过正常的 Java 版 TCP 保护机制。GeyserGuard 实时检查此类流量,并在其触及服务器核心逻辑之前阻止滥用源,无需额外的防火墙或代理设置。
? 安装
- 下载与你的平台匹配的 .jar 文件(Spigot/Paper/Purpur 或 Velocity)
- 将其放入服务器的(或代理的)
plugins 文件夹
- 重启服务器
- 编辑生成的
config.yml 以调整以下设置:
language — 设置为 EN(英语)或 ES(西班牙语/Español);控制所有插件消息、警报和命令输出
packet-protection.pps-limit — 每个 IP 的最大每秒发包数
packet-protection.global-pps-limit — 全局最大每秒发包数
packet-protection.suspicious-hit-threshold / ban-seconds — 何时以及封禁 IP 多长时间
packet-protection.rate-limit-strikes-before-ban — 在应用实际封禁之前,需要多少个连续的超限时间窗口
packet-protection.block-ping-response — 向 Bedrock ping/服务器列表扫描器隐藏服务器,不影响真实连接
packet-protection.log-threshold — 在触发“检测到攻击”警报之前,必须累积多少被阻止的数据包
ipv6.group-by-subnet — 按 IPv6 /64 子网进行封禁,而非单个地址
whitelist — 永远不会被封禁的 IP/CIDR
alerts — 控制台/聊天警报行为
- 使用
/geyserguard reload 重载配置或重启服务器
?️ GeyserGuard
GeyserGuard adds a defensive UDP protection layer for Geyser traffic,
catching empty packets, malformed datagrams, fast bursts, and abusive
packet rates before they reach the expensive parts of the network
stack. Available for both Spigot/Paper/Purpur (per-server) and
Velocity (proxy-wide) setups.
What it protects against
- Empty UDP packets
- Malformed or oversized datagrams
- Per-IP packet floods (rate limiting in packets per second), with strike-based escalation so a single burst never bans a legitimate player
- Global packet-rate spikes across all connections
- Repeated suspicious packets, which trigger a temporary IP ban
- Ping-flood / server-list scanning — optionally silences replies to Bedrock ping requests entirely, hiding the server from scanners without blocking real player connections
- IPv6 subnet-aware banning (bans the whole /64 block instead of a single address, since attackers can rotate through billions of individual IPv6 addresses within one subnet)
- Memory exhaustion (OOM) from spoofed IP floods — every internal tracking structure, not just the main filter, is capped and evicts oldest entries first
- Console/log spam suppression — malformed Bedrock/RakNet packets (valid packet ID but truncated payload) normally flood the console with repeated Netty/Geyser exception warnings; GeyserGuard silently catches these and bans the offending IP instead of spamming the log
⚙️ Features
- Configurable packets-per-second limit, per IP and globally
- Strike-based rate limiting: requires sustained flooding across consecutive windows before banning, so a reconnect burst, lag spike, or several real players sharing one CGNAT/mobile IP is never banned by mistake
- Optional ping-response suppression to hide the server from Bedrock server-list scanners and ping-flood tools, with zero impact on real connections
- Configurable minimum/maximum packet size filtering
- Temporary bans with configurable duration and suspicious-hit threshold
- Threshold-based attack alerts — only escalates to a console/chat warning once blocked packets build up past a configurable count (or immediately on an actual ban), so a harmless one-off drop never looks like an ongoing attack
- Persistent local ban database (bans survive a restart)
- IP/CIDR whitelist for trusted addresses (your own server, reverse proxy, load balancer, etc.), fully reloadable without a restart
- In-game and console alerts for admins, with optional IP masking
- Automatic memory protection: tracks a configurable maximum number of IPs and evicts the oldest inactive ones first, preventing memory exhaustion from spoofed IP floods
- Bilingual support (English/Spanish) via
config.yml
- Low overhead, no external dependencies required
Commands & Permissions
| Command |
Permission |
Description |
/geyserguard status |
geyserguard.admin |
Show current protection status |
/geyserguard stats |
geyserguard.admin |
Show top source IPs and blocked events |
/geyserguard bans |
geyserguard.admin |
Show stored bans with reason and time |
/geyserguard unban <IP> |
geyserguard.admin |
Remove a temporary ban from one IP |
/geyserguard reload |
geyserguard.admin |
Reload config.yml (including the whitelist) |
| — |
geyserguard.alerts |
Receive in-game attack alerts |
OP players have all permissions by default. To grant them manually, use a permissions plugin like LuckPerms.
Why use it?
Servers that accept Bedrock players through Geyser expose a UDP
listener that can be targeted directly with packet floods, spoofed
IPs, and malformed datagrams — attacks that bypass normal Java-edition
TCP protections. GeyserGuard inspects this traffic in real time and
blocks abusive sources before they reach your server's core logic,
without requiring a separate firewall or proxy setup.
? Installation
- Download the .jar matching your platform (Spigot/Paper/Purpur or Velocity)
- Place it in your server's (or proxy's)
plugins folder
- Restart the server
- Edit the generated
config.yml to adjust:
language — set to EN for English or ES for Spanish (Español); controls all plugin messages, alerts, and command output
packet-protection.pps-limit — max packets/second per IP
packet-protection.global-pps-limit — max packets/second overall
packet-protection.suspicious-hit-threshold / ban-seconds — when and how long IPs get banned
packet-protection.rate-limit-strikes-before-ban — how many consecutive over-limit windows before a real ban is applied
packet-protection.block-ping-response — hide the server from Bedrock ping/server-list scanners without affecting real connections
packet-protection.log-threshold — how many blocked packets must build up before an "attack detected" alert fires
ipv6.group-by-subnet — ban by IPv6 /64 subnet instead of single address
whitelist — IPs/CIDRs that are never blocked
alerts — console/chat alert behavior
- Reload with
/geyserguard reload or restart the server
评论 0
登录后参与评分
还没有评论,来抢沙发吧