Flarum 论坛

官方为 Flarum 打造的 ProxyTracer 集成扩展。该扩展为您的社区引入企业级 IP 威胁情报，自动识别已知的 VPN、代理、数据中心机房及 Tor 节点，支持在注册、登录或全站访问层面精准拦截恶意流量。

完整源码可在 Github 查看。该扩展通过 Packagist 进行包管理分发。

功能特性

细粒度控制，允许管理员在新用户注册、现有用户身份验证时强制执行 IP 验证，或对所有站点访问者全局执行。
利用 Flarum 原生 Laravel Cache API 内置缓存，存储最近的 IP 地址评估结果，大大减少外部 API 调用并确保零延迟。
在 API 超时或网络故障时，该扩展优先放行用户访问以防止大规模误封。可以在设置中切换此行为。
内置支持精确 IP 及 CIDR 子网白名单（例如 192.168.1.0/24）。

安装指南

通过 SSH 连接至服务器并进入 Flarum 根目录（即 composer.json 所在目录）：
```
cd /var/www/flarum
```

通过 Composer 安装扩展：


composer require proxytracer/flarum-proxytracer

清除 Flarum 缓存以编译新的前端静态资源：
```
php flarum cache:clear
```

配置说明：

从 ProxyTracer Dashboard 获取标准 API 密钥凭据。
进入 Flarum 管理面板：Admin → Features → ProxyTracer 找到扩展设置项。
将您的 API 密钥填入 API Key 字段。
通过勾选 Block Signups、Block Logins 和/或 Block All Visitors 启用防护参数。
将受信任的 IP 或 CIDR 网段添加至 IP Whitelist（每行一个）。
（可选）根据服务器的具体流量需求，调整 API 超时时间与缓存过期限制。
（可选）自定义向被拦截用户展示的拦截提示消息。例如，您可以添加联系站点管理员的操作指引，以便用户在认为拦截有误且未通过代理/VPN 访问时发起申诉。

Settings Screenshot

网络配置：Cloudflare 与反向代理

为了让 ProxyTracer 有效运行，Flarum 应用必须接收到真实的客户端 IP 地址。 如果您的基础设施使用了 Cloudflare 或其他反向代理，Flarum 可能会默认记录代理节点的 IP 地址，从而使 ProxyTracer 的检测失效。

请遵循下方与您的服务器架构相匹配的配置指南，以确保正确的 IP 转发。

直连 Cloudflare 架构（标准安装）

如果您的 Flarum 服务器直连互联网，且仅使用 Cloudflare 进行 DNS 解析和边缘代理：

在 ProxyTracer 的 Flarum 设置中，直接开启 Enable Cloudflare Direct Mode 开关。

ProxyTracer 将自动从经过验证的 Cloudflare 请求头中提取真实客户端 IP，无需修改任何服务器配置文件！

多层代理架构（Cloudflare + 本地反向代理）

适用于 Flarum 部署在本地反向代理（如 CloudPanel、Nginx Proxy Manager、Traefik、Plesk）之后且最外层接入了 Cloudflare 的多层代理场景。

您必须配置本地反向代理从 CF-Connecting-IP 请求头提取真实客户端 IP，但仅限来自受信任 Cloudflare 官方 IP 地址的流量。在不验证来源的情况下盲目传递此请求头，会使恶意用户能够通过伪造其 IP 地址来绕过速率限制和封禁。

Nginx 示例： 首先在 server 块配置中（location 块之外），将 Cloudflare 的 IP 范围定义为受信任代理。在 Nginx 层面硬编码这些 IP 能提供最高水平的速度与安全性。


# Cloudflare IPv4 地址段，参见 [https://www.cloudflare.com/ips/](https://www.cloudflare.com/ips/)
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
set_real_ip_from 103.31.4.0/22;
set_real_ip_from 141.101.64.0/18;
set_real_ip_from 108.162.192.0/18;
set_real_ip_from 190.93.240.0/20;
set_real_ip_from 188.114.96.0/20;
set_real_ip_from 197.234.240.0/22;
set_real_ip_from 198.41.128.0/17;
set_real_ip_from 162.158.0.0/15;
set_real_ip_from 104.16.0.0/13;
set_real_ip_from 104.24.0.0/14;
set_real_ip_from 172.64.0.0/13;
set_real_ip_from 131.0.72.0/22;
 
# Cloudflare IPv6 地址段
set_real_ip_from 2405:b500::/32;
set_real_ip_from 2405:8100::/32;
set_real_ip_from 2803:f800::/32;
set_real_ip_from 2c0f:f248::/32;
set_real_ip_from 2a06:98c0::/29;
 
real_ip_header CF-Connecting-IP;

接下来找到您的 location / 指令。得益于上述配置，现在 Nginx 只有在请求实际通过 Cloudflare 时，才会安全地将 $remote_addr 解析为真实的客户端 IP。修改您的 IP 转发请求头如下：


location / {
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 
    ...    
}

保存配置并重新加载 Nginx 服务 (systemctl reload nginx)。

紧急访问恢复

💡

意外被拦截？ 若在配置 ProxyTracer 时因自身连接了 VPN 导致管理员账号被阻断（例如启用了“全部拦截”），可通过 SSH 登录服务器直接禁用扩展以恢复访问：


cd /var/www/flarum
php flarum extension:disable proxytracer-proxytracer
php flarum cache:clear

(如果您使用的是 Docker，请在 PHP 容器内运行这些命令)。或者也可以通过数据库禁用：打开 settings 表，找到 proxytracer.block_all 键，将其值更改为 0，并执行 php flarum cache:clear。

开源协议

本项目基于 GNU Affero General Public License v3.0 (AGPLv3) 开源协议发布。详情请参阅 LICENSE 文件。