ProxyShield
适用于 Minecraft 服务器的防 VPN 和防代理保护。支持国家过滤、Discord Webhook 警报、
静默模式和试运行模式。共享同一个检测核心,提供五种行为一致的原生构建版本。
| 构建版本 |
文件 |
运行环境 |
| Paper |
ProxyShield-Paper-2.5.1.jar |
Paper, Purpur 和 Spigot 1.21+ |
| Folia |
ProxyShield-Folia-2.5.1.jar |
Folia |
| BungeeCord |
ProxyShield-Bungee-2.5.1.jar |
BungeeCord / Waterfall |
| Velocity |
ProxyShield-Velocity-2.5.1.jar |
Velocity 3.3+ |
| Sponge |
ProxyShield-Sponge-2.5.1.jar |
SpongeAPI 17 |
| Universal (通用) |
ProxyShield-Universal-2.5.1.jar |
上述所有平台,单个文件即可 |
通用版 JAR 包同时包含四个入口点和四个插件描述符。每个服务器只会读取它熟悉的描述符并忽略其余部分,因此同一个文件可以放入 Paper 的 plugins/ 文件夹、BungeeCord 的对应文件夹、Velocity 的对应文件夹或 Sponge 的 mods/ 文件夹中。相比单平台 JAR 包,它仅多出约 400 KB 的大小,但这为运行多个平台的网络节省了一次下载。如果你只运行其中一个平台,使用各平台专用的 JAR 包仍然是更简洁的选择。
Paper 和 Folia 的 JAR 包基于相同的源代码构建,且可以互换使用。调度逻辑已经使用了区域化 API,因此任一版本均可在任一服务器上运行。它们之所以分开存在,是因为服务器管理员通常会寻找以其平台命名的 JAR 包。
Spigot 由同一个 JAR 包支持。Paper 和 Folia 提供了 AsyncScheduler(异步调度器)、每实体调度器和 Adventure 组件;而 Spigot 并不具备这三项功能。该 JAR 包会在启动时选择相应的实现方式,而仅限 Paper 使用的类型则存在于一个在没有这些特性的服务器上永远不会被加载的类中。
请在接受连接的那台机器上安装一个 JAR 包。在一个网络中,这通常是代理服务器(BungeeCord 或 Velocity)。如果代理后面使用的是 Paper 构建版本,它将只能看到代理服务器自身的地址。
展示
简要演示检查过程、判定结果以及被阻止的连接是什么样子的。
特性
检测
- 内置了 26 项 IP 情报服务,按名称启用——其中 15 项完全无需 API 密钥
- 共识评分:同时向多个提供商发起请求并累加其权重,因此即使某个服务从未听说过某 VPN 也无法将其清除,而某个噪声较大的服务也不能单独踢人
- 公共 VPN、数据中心和 Tor 出口节点列表,支持正确的 CIDR 匹配,涵盖 IPv4 和 IPv6
- 网络(ASN)区块与白名单规则,能在任何列表收录之前捕获 VPN 的新网段,并提供可自动刷新的 ASN 列表下载功能
- 基于正则表达式的 ISP 过滤器,用于屏蔽特定主机商或始终放行移动运营商
- 针对任意提供商返回结果的判断条件(例如
risk.score >= 85、connection.type = mobile)以及自定义请求头,从而精确接入未列出的服务
- 直接拒绝 Bogon 地址
- 将反向 DNS 模式作为信号——免费、无限制,且对未被编目记录的范围非常有效
- 行为启发式检测:每个子网的加入频率、每个地址的账号数量、账号变更国家等行为
- 对常客建立信任机制,确保收紧规则或某提供商出现异常时不会误踢你的玩家
- 国家筛选,支持黑名单或白名单模式
- 手动黑名单,在所有其他检查之前优先执行
- 每个地址的连接数限制,基于在线玩家数量或时间窗口内计数
- 当检查无法完成时,可配置为“失败开放”或“失败关闭”行为
例外情况
- IP 白名单,支持单个地址、CIDR 块和范围
- 玩家名称白名单
- 绕过权限
- 回环地址和私有地址永远不会被检查,也不消耗查询配额
- 默认豁免通过 Geyser/Floodgate 加入的 Bedrock 玩家
运维功能
- 试运行模式:检测并报告,但不断开任何人的连接
- 被动模式:登录时不进行检查,仅在需要时进行查询
- BungeeCord 和 Velocity 上的受限服务器:将被标记的玩家留在大厅而不是断开其连接
- 带有原因和过期时间的白名单与黑名单条目
/proxyshield alts 列出同一地址上出现的每一个账号
- 显示每个提供商原始响应的调试输出
- 在检测到违规时执行控制台命令,从而允许标记或限制被标记的玩家而非直接踢出
/proxyshield check 显示每个提供商的具体反馈,以便追踪误报
- 查询缓存在重启和重载后依然保留;来自同一地址的同时登录共享一次查询
- 网络共享存储:支持 MySQL、MariaDB、PostgreSQL、SQLite、H2 或 Redis
- PlaceholderAPI 支持与匿名 bStats 指标上报
- 静默模式:不向工作人员或控制台发送警报,但日志文件和 webhook 仍继续记录
- Discord webhook,具备队列、重试和速率限制处理功能,布局由你自行定义
- Telegram 和 VK 警报
- 拦截日志位于
plugins/ProxyShield/blocks.log
- 完整的
/proxyshield 命令集,支持 Tab 补全
- 开箱即用支持英语和德语,复制一个文件即可添加任意语言
快速开始
- 将对应平台的 jar 文件放入
plugins/ 目录,然后启动服务器一次。
- 编辑
plugins/ProxyShield/config.yml。
- 运行
/proxyshield reload。
推荐首次运行时,保持 detection.dry-run: true 状态一天,并观察 blocks.log。它会记录本应被阻止但并未实际断开任何人连接的情况,这是在影响真实玩家之前发现误报的最经济方式。
提供商与评分
按名称启用某项服务。列表中列为免费的十五项完全不需要密钥:
api:
mode: consensus # 或 failover
required-score: 1.5
providers:
ip-api: { enabled: true, weight: 1.0 }
blackbox: { enabled: true, weight: 1.0 }
ipapi-is: { enabled: true, weight: 1.5 }
proxycheck: { enabled: false, weight: 2.0, key: "" }
在共识模式下,所有启用的提供商会被同时询问,并将标记该地址的提供商权重相加。在 required-score: 1.5 设置下,单个强提供商就足以触发拦截,或者两个较弱提供商的组合,亦或一个弱提供商加上一次反向 DNS 命中。如果你更倾向于宁可漏掉 VPN 也不误踢真实玩家,可将阈值提高到 2.5;若想对任何单次命中都进行拦截,则可降低至 1.0。
这并不会像你想象的那样成倍消耗你的查询配额。答案会被缓存(IPv6 折叠为其 /64 前缀),来自同一地址的同时登录共享一次查询,一旦达到分数阈值即停止扇出查询,缓存在重启和重载后依然保留,且如果某提供商开始故障,它将从轮换中被剔除直到恢复。
对于目录中未知的服务,可以直接在 config.yml 中通过 URL 和点分字段路径进行描述——请参阅 providers 部分底部的注释示例。
国家筛选
country:
enabled: true
mode: whitelist # 仅允许这些国家连接
codes: ["DE", "AT", "CH"]
block-unknown: false
设置 mode: blacklist 可反转此逻辑。国家数据来源于查询提供商,因此即使 detection.use-api 为 off,country.enabled 也会触发提供商查询。
静默模式
notifications:
silent: true
抑制工作人员广播和控制台行输出。日志文件和 webhook 仍会记录每次检测事件,这样你可以在不向所有在线用户宣告过滤器已触发的情况下保留数据。
检测时的动作
并非所有服务器都希望移除被标记的玩家。若要改为标记他们,可以运行你原本打算手动执行的命令:
detection:
dry-run: true
actions:
on-flag:
- "lp user {player} permission set myserver.vpnflagged true"
- "webhook {player} flagged {reason} from {ip}"
delay-seconds: 3
run-when: always
开启 dry-run 后,检测事件仍然触发,警报和 webhook 仍然发出,这些命令也依然执行,但玩家保持连接。这就是“标记而非踢出”的设置:将他们移至受限组,要求他们通过 Discord 验证,或将他们的名字交给另一个插件处理。
以控制台身份运行命令,可带可不带前导斜杠。可用的占位符包括
{player}、{uuid}、{ip}、{reason}、{reason_id}、{country}、{isp}、{asn}、{score}、
{sources}、{action} 和 {platform}。
delay-seconds 的重要性超乎想象。在玩家进入服务器之前就会进行判断,因此在 0 时,命令会在他们仍处于连接状态时运行。这对于权限授予或 webhook 来说没问题,但任何需要他们真正在线的操作(例如向他们发送消息或提示他们关联账户)都需要在此处设置几秒钟的延迟。
run-when 接受 always、kicked 或 allowed,分别表示无论何时都触发、仅针对被断开的玩家触发,或仅针对未被断开的玩家触发。
Discord webhook
discord:
enabled: true
webhook-url: "https://discord.com/api/webhooks/..."
show-ip: true
show-ip: false 会发布 hidden 而不是地址。仅接受 https:// URL。
消息布局由您自行编写。默认情况下是一个标题和六个内联字段;清空这些字段并改为编写描述:
discord:
embed:
title: "`{player}`"
description: |
```ansi
IP: `{ip}`
Country: {country}
Action: {action}
```
thumbnail: "https://your-server.example/alert.gif"
fields: {}
占位符:{player} {uuid} {ip} {reason} {country} {isp} {asn} {score}
{sources} {platform} {version} {action} {action_id}。字段是命名条目,并按书写顺序显示。
值按原样填入,因此您需要手动添加反引号。Discord 将嵌入文本解析为 Markdown,而下划线是 Minecraft 用户名的合法字符,因此如果没有代码块包裹,Some_Name 会显示为斜体,__Name__ 会显示为删除了下划线的下划线。删除整个 embed 部分可恢复至 2.4 版本之前的布局。
网络存储
单个服务器无需设置——判决和信任记录保存在两个文件中。对于由多个代理组成的网络,应共享这些数据,以便整个网络中每个地址只查询一次,而不是每个代理各查询一次:
storage:
type: redis # 也可以是 mysql, mariadb, postgresql, sqlite, h2, file, memory
redis:
host: "127.0.0.1"
port: 6379
password: ""
Redis 还会推送失效通知:在一个代理上对地址执行白名单操作或运行 /proxyshield clearcache,其他代理会立即生效,而不必等到条目过期。
ProxyShield 不捆绑任何数据库驱动或 Redis 库,因此不会向未请求它们的服务器移动任何东西。大多数 Bukkit 服务器已经拥有 MySQL 和 SQLite 驱动;如果您的没有,请将驱动 jar 放入 ProxyShield 文件夹,并在 storage.sql.driver-path 下命名它。如果无法访问存储,插件会提示一次并回退到文件存储——数据库故障永远不会导致登录故障。
PlaceholderAPI
当安装 PlaceholderAPI 时,Bukkit 构建版可用。每个占位符都会读取缓存,因此它们都不会阻塞主线程:
| 占位符 |
显示内容 |
%proxyshield_blocked% / %proxyshield_checked% |
自启动以来的计数器 |
%proxyshield_blocked_proxy% / %proxyshield_blocked_hosting% / %proxyshield_blocked_country% |
按原因分类的拦截 |
%proxyshield_country% / %proxyshield_isp% / %proxyshield_asn% |
玩家自身的地址 |
%proxyshield_is_proxy% / %proxyshield_is_hosting% / %proxyshield_score% |
对该地址的判决 |
%proxyshield_sources% |
标记它的服务 |
%proxyshield_trusted% |
玩家是否已获得豁免 |
%proxyshield_mode% / %proxyshield_providers% / %proxyshield_storage% |
插件的设置方式 |
%proxyshield_cache_size% / %proxyshield_trusted_players% / %proxyshield_uptime% |
实时状态 |
指标
通过 bStats 进行的匿名统计:服务器数量、平台、Java 版本以及正在使用的 ProxyShield 设置。不包含任何地址或玩家数据。公开于
bstats.org,可通过
metrics.enabled: false 关闭。
其他插件的 API
if (ProxyShieldApi.isAvailable() && ProxyShieldApi.isProxy(address)) {
// 仅缓存,在主线程上安全
}
LookupResult result = ProxyShieldApi.lookup(address); // 阻塞,仅限异步
boolean regular = ProxyShieldApi.isTrusted(uuid);
de.lucasthcr.bridgesave.proxyshield.api.ProxyShieldApi 是只读的:它回答问题,从不更改判决或断开任何人的连接。
语言
所有面向玩家的文本位于 messages_en.yml 和 messages_de.yml。将 settings.language 指向您想要的那个。对于另一种语言,复制一个文件到 messages_<code>.yml,翻译它并设置
settings.language: <code>。如果您删除任何键,它将回退到内置英文,因此来自旧版本的 message 文件在更新后仍可正常工作。
命令
所有这些都需要 proxyshield.admin 权限。别名:/ps、/antivpn。
| 命令 |
作用 |
/proxyshield info |
版本、活动模式、查找模式和列表状态 |
/proxyshield providers |
每个启用的服务及其权重、健康状况和延迟 |
/proxyshield stats |
检测计数器、缓存和 webhook 状态 |
/proxyshield check <player|ip> |
运行完整流程并解释判决 |
/proxyshield lookup <player|ip> |
新的提供商查找,忽略缓存 |
/proxyshield whitelist <add|remove|info|list|purge> [entry] [time] [reason] |
管理永不拦截列表 |
/proxyshield blacklist <add|remove|info|list|purge> [entry] [time] [reason] |
管理始终拦截列表 |
/proxyshield alts <player|ip> |
在同一地址上看到的所有账户 |
/proxyshield refresh |
重新下载数据源 |
/proxyshield recheck |
重新检查所有在线玩家,断开任何失败者 |
/proxyshield clearcache |
丢弃缓存的查找结果 |
/proxyshield reload |
重新读取 config.yml 和消息文件 |
在游戏中添加的条目存储在 whitelist.txt 和 blacklist.txt 中,重启后依然保留。
来自 config.yml 的条目需要在那里移除。
/proxyshield check 是用于报告误报的工具:它会遍历整个流程并打印每个阶段的判定结果,让你能确切看到是哪个规则触发了拦截。
权限
| 节点 |
默认值 |
授予 |
proxyshield.bypass |
op |
跳过所有检查 |
proxyshield.notify |
op |
接收实时拦截警报 |
proxyshield.admin |
op |
使用 /proxyshield 命令 |
在 Paper、BungeeCord 和 Sponge 上,登录握手期间尚无权限数据,因此 proxyshield.bypass 仅对操作员生效。若要在这些平台上实现可靠的豁免,请使用 whitelist.players 或 whitelist.ips。在 Velocity 上,玩家对象在 LoginEvent 中可用,权限功能正常工作。
连接判定逻辑
严格自上而下,首次匹配即生效。所有能允许玩家的判定先于任何能阻止玩家的判定执行,因此操作员始终可以通过白名单绕过误报。
| # |
检查项 |
结果 |
开销 |
| 1 |
proxyshield.bypass 权限 |
allow |
无 |
| 2 |
名称在 whitelist.players 中 |
allow |
无 |
| 3 |
IP 在 whitelist.ips 中 |
allow |
无 |
| 4 |
通过 Floodgate 的基岩版玩家 |
allow |
无 |
| 5 |
回环地址或私有地址 |
allow |
无 |
| 6 |
Bogon 地址 |
block |
无 |
| 7 |
IP 在 blacklist.ips 中 |
block |
无 |
| 8 |
IP 在下载的数据源中 |
block |
~0.6 µs |
| 9 |
网络 (ASN) 或 ISP 规则 |
allow 或 block |
每个未缓存的 IP 一次 HTTP 请求 |
| 10 |
提供商报告 proxy |
block |
同上请求 |
| 11 |
提供商报告 hosting |
block |
同上请求 |
| 12 |
国家不被允许 |
block |
同上请求 |
| 13 |
超过连接限制 |
block |
无 |
步骤 1 到 8 从不涉及网络。从步骤 9 开始,每个不在缓存中的地址会产生一次提供商请求,这就是为什么在大多数服务器上缓存 TTL 比速率限制更重要。
性能
使用四个默认数据源(62,555 个条目编译为 35,161 个合并范围)测得:
|
|
| 占用内存 |
1.3 MB |
| 启动解析 |
259 ms,在异步线程上 |
| 每次登录的数据源检查 |
589 ns |
| 1000 次登录 |
总计 0.59 ms,约相当于 1/85 个游戏刻 |
提供商查找是唯一具有实际延迟的部分:通常为 50 到 200 ms,上限由 api.timeout-seconds 设定。它在所有平台上都在主线程之外运行,因此只会延迟该玩家的登录,而不会影响服务器游戏刻。设置 detection.use-api: false 可启用纯数据源模式,每次登录零网络流量。
构建
需要 JDK 21 和 Maven。
mvn clean package
五个插件 jar 包位于 proxyshield-*/target/ 下。测试作为构建的一部分运行。
模块结构
proxyshield-common 检测核心,无平台 API,124 个测试
proxyshield-paper Bukkit 适配器 -> AsyncPlayerPreLoginEvent, Paper/Folia/Spigot
proxyshield-folia 与 proxyshield-paper 相同源码,独立的描述文件和 jar 名称
proxyshield-bungee Bungee 适配器 -> LoginEvent with intents
proxyshield-velocity Velocity 适配器 -> LoginEvent with EventTask.async
proxyshield-sponge Sponge 适配器 -> ServerSideConnectionEvent.Auth
每个平台模块都 shaded proxyshield-common,因此每个 jar 都是自包含的。Velocity 和 Sponge 的构建还捆绑了重定位的 SnakeYAML,因为两者均未暴露 YAML 配置 API,且与其他模块一样读取相同的 config.yml。
proxyshield-folia 没有添加自己的 Java 源码。它通过 build-helper-maven-plugin 引入 proxyshield-paper/src/main/java,因此两个 jar 包均由同一份代码编译而成,修复永远不会只出现在其中一个中。
测试
mvn -pl proxyshield-common test
除了单元测试外,有两个测试值得了解:ShieldConfigTest 解析 jar 中实际附带的 config.yml,并断言阅读器期望的所有值;MessagesTest 断言两个捆绑的消息文件定义了代码查找所需的确切键,且没有任何键或值被 YAML 的布尔强制转换所吞没。这两个测试在开发过程中都捕获了真实的缺陷。
1.1 版本变更
请参阅 CHANGELOG.md。简而言之:v1 中的 IP 数据源从未匹配到任何内容,因为 CIDR 前缀被丢弃了;代理检测是子字符串测试;webhook 负载可注入;且 BungeeCord 和 Velocity 在错误的线程上执行阻塞操作。
原始的 1.1 源代码保存在 legacy-1.1/ 下,原始反编译器输出保存在 decompiled/ 下以供参考。
许可证
GPL-3.0,详见 LICENSE。
ProxyShield
Anti-VPN and anti-proxy protection for Minecraft servers. Country filtering, Discord webhook alerts,
a silent mode and a dry-run mode. One shared detection core, five native builds that behave
identically.
| Build |
File |
Runs on |
| Paper |
ProxyShield-Paper-2.5.1.jar |
Paper, Purpur and Spigot 1.21+ |
| Folia |
ProxyShield-Folia-2.5.1.jar |
Folia |
| BungeeCord |
ProxyShield-Bungee-2.5.1.jar |
BungeeCord / Waterfall |
| Velocity |
ProxyShield-Velocity-2.5.1.jar |
Velocity 3.3+ |
| Sponge |
ProxyShield-Sponge-2.5.1.jar |
SpongeAPI 17 |
| Universal |
ProxyShield-Universal-2.5.1.jar |
all five of the above, one file |
The universal jar carries all four entry points and all four plugin descriptors at once. Every
server reads the descriptor it knows and ignores the rest, so the same file drops into a Paper
plugins/ folder, a BungeeCord one, a Velocity one or a Sponge mods/ folder. It costs about
400 KB over a single-platform jar, which buys one download for a network running several of them.
The per-platform jars are still the plainer choice when you only run one.
The Paper and Folia jars are built from the same sources and are interchangeable. The scheduling
already uses the regionised API, so either one runs on either server. They exist separately because
server owners look for a jar named after their platform.
Spigot is supported by the same jar. Paper and Folia offer AsyncScheduler, a per-entity scheduler
and Adventure components; Spigot has none of the three. The jar picks an implementation at start-up,
and the Paper-only types live in a class that is never loaded on a server without them.
Install one jar, on the machine that accepts the connection. On a network that is the proxy
(BungeeCord or Velocity). The Paper build behind a proxy would only ever see the proxy's own
address.
Showcase
A short demonstration of the checks, the verdict and what a blocked connection looks like.
Features
Detection
- 26 IP intelligence services built in, enabled by name - 15 of them need no API key at all
- Consensus scoring: several providers are asked at once and their weights added up, so one service
that has never heard of a VPN cannot clear it, and one noisy service cannot kick anybody alone
- Public VPN, datacenter and Tor exit feeds with correct CIDR matching, IPv4 and IPv6
- Network (ASN) block and allow rules, which catch a VPN's new range before any feed lists it,
plus downloadable ASN lists that refresh on their own
- ISP filter with regular expressions, to block a hoster or always admit a mobile carrier
- Conditions on any provider's answer (
risk.score >= 85, connection.type = mobile) and
custom request headers, so an unlisted service can be wired in exactly
- Bogon addresses refused outright
- Reverse DNS patterns as a signal - free, unlimited, and effective on ranges nobody has catalogued
- Behavioural heuristics: join rate per subnet, accounts per address, an account changing country
- Trust for regulars, so a tightened rule or a provider having a bad day does not kick your players
- Country filtering, blacklist or whitelist mode
- Manual blacklist, checked before everything else
- Connection limit per address, by players online or within a time window
- Configurable fail-open or fail-closed behaviour when a check cannot complete
Exemptions
- IP whitelist accepting single addresses, CIDR blocks and ranges
- Player name whitelist
- Bypass permission
- Loopback and private addresses are never checked, and never cost lookup quota
- Bedrock players joining through Geyser/Floodgate are exempt by default
Operations
- Dry-run mode: detect and report without disconnecting anybody
- Passive mode: no checks at login, lookups on demand only
- Restricted servers on BungeeCord and Velocity: keep a flagged player in the lobby instead of
disconnecting them
- Whitelist and blacklist entries with a reason and an expiry
/proxyshield alts lists every account seen on the same address
- Debug output with every provider's raw answer
- Console commands on a detection, so a flagged player can be marked or restricted instead of kicked
/proxyshield check shows what every single provider said, so a false positive can be traced
- Lookup cache survives restarts and reloads; simultaneous logins from one address share one query
- Shared storage for a network: MySQL, MariaDB, PostgreSQL, SQLite, H2 or Redis
- PlaceholderAPI support and anonymous bStats metrics
- Silent mode: no staff or console alerts, while the log file and webhook keep recording
- Discord webhook with queueing, retry and rate-limit handling, and a layout you write yourself
- Telegram and VK alerts
- Block log at
plugins/ProxyShield/blocks.log
- Full
/proxyshield command set with tab completion
- English and German out of the box, any language by copying one file
Getting started
- Drop the jar for your platform into
plugins/ and start the server once.
- Edit
plugins/ProxyShield/config.yml.
- Run
/proxyshield reload.
Recommended first run: leave detection.dry-run: true for a day and watch blocks.log. It records
what would have been blocked without disconnecting anybody, which is the cheapest way to find false
positives before they hit real players.
Providers and scoring
Enable a service by name. The fifteen listed as free need no key at all:
api:
mode: consensus # or failover
required-score: 1.5
providers:
ip-api: { enabled: true, weight: 1.0 }
blackbox: { enabled: true, weight: 1.0 }
ipapi-is: { enabled: true, weight: 1.5 }
proxycheck: { enabled: false, weight: 2.0, key: "" }
In consensus mode every enabled provider is asked at once and the weights of those flagging the
address are added up. At required-score: 1.5 a single strong provider is enough, or any two weaker
ones, or one weak provider plus a reverse DNS hit. Raise it to 2.5 if you would rather miss a VPN
than kick a real player; lower it to 1.0 to block on any single hit.
This does not multiply your quota the way it looks. Answers are cached (IPv6 folded to its /64),
simultaneous logins from one address share one lookup, the fan-out stops the moment the score is
reached, the cache survives restarts and reloads, and a provider that starts failing is dropped from
the rotation until it recovers.
A service the catalog does not know can be described directly in config.yml with a URL and dotted
field paths - see the commented example at the bottom of the providers section.
Country filtering
country:
enabled: true
mode: whitelist # only these countries may connect
codes: ["DE", "AT", "CH"]
block-unknown: false
Set mode: blacklist to invert it. Country data comes from the lookup provider, so country.enabled
triggers a provider query even when detection.use-api is off.
Silent mode
notifications:
silent: true
Suppresses the staff broadcast and the console line. The log file and the webhook still record every
detection, so you keep the data without announcing to everyone online that the filter fired.
Commands on a detection
Not every server wants a flagged player gone. To mark them instead, run whatever you would have run
by hand:
detection:
dry-run: true
actions:
on-flag:
- "lp user {player} permission set myserver.vpnflagged true"
- "webhook {player} flagged {reason} from {ip}"
delay-seconds: 3
run-when: always
With dry-run on, the detection still fires, the alert and the webhook still go out and these
commands still run, but the player stays connected. That is the flag-instead-of-kick setup: put them
in a restricted group, make them verify through Discord, hand the name to another plugin.
Commands run as the console, with or without a leading slash. Available placeholders are
{player}, {uuid}, {ip}, {reason}, {reason_id}, {country}, {isp}, {asn}, {score},
{sources}, {action} and {platform}.
delay-seconds matters more than it looks. A connection is judged before the player is on the
server, so at 0 the commands run while they are still connecting. That is fine for a permission
grant or a webhook, but anything that needs them actually online, such as messaging them or
prompting them to link an account, needs a few seconds here.
run-when accepts always, kicked or allowed when the commands should only fire for players
who were disconnected, or only for those who were not.
Discord webhook
discord:
enabled: true
webhook-url: "https://discord.com/api/webhooks/..."
show-ip: true
show-ip: false posts hidden instead of the address. Only https:// URLs are accepted.
The message layout is yours to write. By default it is a title and six inline boxes; clear the
fields and write a description instead:
discord:
embed:
title: "`{player}`"
description: |
```ansi
IP: `{ip}`
Country: {country}
Action: {action}
```
thumbnail: "https://your-server.example/alert.gif"
fields: {}
Placeholders: {player} {uuid} {ip} {reason} {country} {isp} {asn} {score}
{sources} {platform} {version} {action} {action_id}. Fields are named entries and appear
in the order written.
Values go in exactly as written, so you place the backticks. Discord parses embed text as Markdown
and an underscore is a legal Minecraft name character, so without a code span Some_Name shows up
italic and __Name__ underlined with the underscores gone. Deleting the whole embed section
keeps the layout from before 2.4.
Storage on a network
One server needs no setup - verdicts and trust live in two files. A network of several proxies
should share them, so each address is looked up once for the whole network instead of once per
proxy:
storage:
type: redis # or mysql, mariadb, postgresql, sqlite, h2, file, memory
redis:
host: "127.0.0.1"
port: 6379
password: ""
Redis also pushes invalidations: whitelisting an address or running /proxyshield clearcache on one
proxy takes effect on the others immediately, rather than when the entry expires.
ProxyShield bundles no database driver and no Redis library, so nothing is relocated into a server
that did not ask for it. Most Bukkit servers already have a MySQL and a SQLite driver; if yours does
not, drop the driver jar into the ProxyShield folder and name it under storage.sql.driver-path. If
the store cannot be reached, the plugin says so once and falls back to file storage - a database
outage never becomes a login outage.
PlaceholderAPI
Available on the Bukkit builds when PlaceholderAPI is installed. Every placeholder reads the cache,
so none of them can stall the main thread:
| Placeholder |
Shows |
%proxyshield_blocked% / %proxyshield_checked% |
Counters since start-up |
%proxyshield_blocked_proxy% / %proxyshield_blocked_hosting% / %proxyshield_blocked_country% |
Blocks by reason |
%proxyshield_country% / %proxyshield_isp% / %proxyshield_asn% |
The player's own address |
%proxyshield_is_proxy% / %proxyshield_is_hosting% / %proxyshield_score% |
The verdict on it |
%proxyshield_sources% |
Which services flagged it |
%proxyshield_trusted% |
Whether the player has earned an exemption |
%proxyshield_mode% / %proxyshield_providers% / %proxyshield_storage% |
How the plugin is set up |
%proxyshield_cache_size% / %proxyshield_trusted_players% / %proxyshield_uptime% |
Live state |
Metrics
Anonymous statistics through bStats: server count, platform, Java version and which ProxyShield
settings are in use. No addresses and no player data. Public at
bstats.org, and switched off with
metrics.enabled: false.
API for other plugins
if (ProxyShieldApi.isAvailable() && ProxyShieldApi.isProxy(address)) {
// cache-only, safe on the main thread
}
LookupResult result = ProxyShieldApi.lookup(address); // blocking, async only
boolean regular = ProxyShieldApi.isTrusted(uuid);
de.lucasthcr.bridgesave.proxyshield.api.ProxyShieldApi is read-only: it answers questions, it never
changes a verdict or disconnects anybody.
Language
All player facing text lives in messages_en.yml and messages_de.yml. Point settings.language at
the one you want. For another language, copy a file to messages_<code>.yml, translate it and set
settings.language: <code>. Any key you delete falls back to the built-in English, so a message file
from an older version keeps working after an update.
Commands
All of these need proxyshield.admin. Aliases: /ps, /antivpn.
| Command |
Does |
/proxyshield info |
Version, active mode, lookup mode and list status |
/proxyshield providers |
Every enabled service with its weight, health and latency |
/proxyshield stats |
Detection counters, cache and webhook state |
/proxyshield check <player|ip> |
Runs the full pipeline and explains the verdict |
/proxyshield lookup <player|ip> |
Fresh provider lookup, ignoring the cache |
/proxyshield whitelist <add|remove|info|list|purge> [entry] [time] [reason] |
Manage the never-block list |
/proxyshield blacklist <add|remove|info|list|purge> [entry] [time] [reason] |
Manage the always-block list |
/proxyshield alts <player|ip> |
Every account seen on the same address |
/proxyshield refresh |
Re-download the feeds |
/proxyshield recheck |
Re-check everyone online, disconnect whoever fails |
/proxyshield clearcache |
Drop cached lookup results |
/proxyshield reload |
Re-read config.yml and the message file |
Entries added in game are stored in whitelist.txt and blacklist.txt and survive restarts.
Entries that came from config.yml have to be removed there.
/proxyshield check is the tool for a false-positive report: it walks the whole pipeline and prints
what each stage decided, so you can see exactly which rule fired.
Permissions
| Node |
Default |
Grants |
proxyshield.bypass |
op |
Skip every check |
proxyshield.notify |
op |
Receive live block alerts |
proxyshield.admin |
op |
Use /proxyshield |
On Paper, BungeeCord and Sponge no permission data exists yet during the login handshake, so
proxyshield.bypass only resolves for operators there. For reliable exemptions on those platforms
use whitelist.players or whitelist.ips. On Velocity the player object is available at
LoginEvent and the permission works normally.
How a connection is decided
Strictly top to bottom, first match wins. Everything that can allow a player is evaluated before
anything that can block one, so an operator can always whitelist their way out of a false positive.
| # |
Check |
Result |
Cost |
| 1 |
proxyshield.bypass permission |
allow |
none |
| 2 |
Name in whitelist.players |
allow |
none |
| 3 |
IP in whitelist.ips |
allow |
none |
| 4 |
Bedrock player via Floodgate |
allow |
none |
| 5 |
Loopback or private address |
allow |
none |
| 6 |
Bogon address |
block |
none |
| 7 |
IP in blacklist.ips |
block |
none |
| 8 |
IP in a downloaded feed |
block |
~0.6 µs |
| 9 |
Network (ASN) or ISP rule |
allow or block |
one HTTP request per uncached IP |
| 10 |
Provider reports proxy |
block |
same request |
| 11 |
Provider reports hosting |
block |
same request |
| 12 |
Country not permitted |
block |
same request |
| 13 |
Over the connection limit |
block |
none |
Steps 1 to 8 never touch the network. Step 9 onwards costs one provider request per address that is
not in the cache, which is why the cache TTL matters more than the rate limit on most servers.
Performance
Measured with the four default feeds (62,555 entries compiled into 35,161 merged ranges):
|
|
| Memory held |
1.3 MB |
| Startup parse |
259 ms, on an async thread |
| Feed check per login |
589 ns |
| 1000 logins |
0.59 ms total, about 1/85th of one tick |
The provider lookup is the only part with real latency: typically 50 to 200 ms, capped by
api.timeout-seconds. It runs off the main thread on every platform, so it delays that one player's
login and never the server tick. Set detection.use-api: false for a pure feed setup with zero
network traffic per login.
Building
Requires JDK 21 and Maven.
mvn clean package
The five plugin jars land in proxyshield-*/target/. Tests run as part of the build.
Module layout
proxyshield-common detection core, no platform APIs, 124 tests
proxyshield-paper Bukkit adapter -> AsyncPlayerPreLoginEvent, Paper/Folia/Spigot
proxyshield-folia same sources as proxyshield-paper, own descriptor and jar name
proxyshield-bungee Bungee adapter -> LoginEvent with intents
proxyshield-velocity Velocity adapter -> LoginEvent with EventTask.async
proxyshield-sponge Sponge adapter -> ServerSideConnectionEvent.Auth
Each platform module shades proxyshield-common, so every jar is self-contained. The Velocity and
Sponge builds also bundle a relocated SnakeYAML, because neither exposes a YAML config API and both
read the same config.yml as the others.
proxyshield-folia adds no Java sources of its own. It pulls in proxyshield-paper/src/main/java
with build-helper-maven-plugin, so both jars are compiled from one copy of the code and a fix can
never land in only one of them.
Tests
mvn -pl proxyshield-common test
Beyond the unit tests, two of them are worth knowing about: ShieldConfigTest parses the
config.yml that actually ships in the jar and asserts every value the reader expects, and
MessagesTest asserts that both bundled message files define exactly the keys the code looks up and
that no key or value is swallowed by YAML's boolean coercion. Both of those caught real defects
during development.
Changes from 1.1
See CHANGELOG.md. The short version: the IP feeds never matched anything in v1
because the CIDR prefix was thrown away, proxy detection was a substring test, the webhook payload
was injectable, and BungeeCord and Velocity did blocking work on the wrong thread.
The original 1.1 sources are kept under legacy-1.1/ and the raw decompiler output under
decompiled/ for reference.
Licence
GPL-3.0, see LICENSE.
评论 0
登录后参与评分
还没有评论,来抢沙发吧