ProxyShield

插件

· 作者 LucasTHCR

带有国家过滤功能的反 VPN 和反代理保护、Discord 警报、静默模式和试运行模式。原生支持 Paper、Folia、BungeeCord、Velocity 和 Sponge 构建。

0 本站下载 0 关注 更新于 2 周前

最新 3.0.1+universal · 26.3 · Bukkit / BungeeCord

一键开服(送7天)

Built with Java 21 Available for Paper Available for Purpur Available for Spigot Available for Bukkit Available for Folia Available for Sponge Available for BungeeCord Available for Waterfall Available for Velocity

Chat with us on Discord Available on Codeberg

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 补全
  • 开箱即用支持英语和德语,复制一个文件即可添加任意语言

快速开始

  1. 将对应平台的 jar 文件放入 plugins/ 目录,然后启动服务器一次。
  2. 编辑 plugins/ProxyShield/config.yml。
  3. 运行 /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。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源