qBittorrent Enhanced Edition 增强特性全解析：自动封禁吸血 Peer 与黑白名单机制的实现与应用

qBittorrent Enhanced Edition 增强特性全解析：自动封禁吸血 Peer 与黑白名单机制的实现与应用

【免费下载链接】qBittorrent-Enhanced-Edition[Unofficial] qBittorrent Enhanced, based on qBittorrent项目地址: https://gitcode.com/gh_mirrors/qb/qBittorrent-Enhanced-Edition

qBittorrent Enhanced Edition（增强版）是基于官方 qBittorrent 的非官方分支，它在保留原版全部能力的同时，内置了一套自动识别并封禁"吸血"（leech）Peer 的增强机制，涵盖迅雷、QQ、百度、Xfplay、DLBT 等常见国内客户端的自动屏蔽，以及 Peer 白名单/黑名单、Shadow Ban 等精细化控制手段。本文以仓库 README.md 为主线，结合 peer_blacklist.hpp、peer_filter_session_plugin.hpp 等核心源码，从特性、实现原理、安装方式到私有 Tracker 注意事项，完整讲解这一增强分支的技术全貌，帮助你在实际部署中正确配置并安全使用这些功能。

项目定位：官方 qBittorrent 之上的增强分支

按照 README.md 的项目说明，qBittorrent 本身是一个使用 C++ / Qt 编写、底层基于 Arvid Norberg 开发的 libtorrent（又称 libtorrent-rasterbar）的 BitTorrent 客户端，目标是成为其他 BT 客户端的优质替代品，具备快速、稳定、良好的 Unicode 支持以及丰富的功能特性。

qBittorrent Enhanced Edition 则在官方版本之上增加了针对恶劣 Peer 的自动防御能力，其核心特性在 README 中被明确归纳为以下四项：

特性	默认状态	作用
自动封禁迅雷、QQ、百度、Xfplay、DLBT 及离线下载器等吸血客户端	始终启用	识别常见吸血/下载器 Peer 并主动断开连接
自动封禁来自中国的 Unknown Peer	关闭（OFF）	对客户端标识为 Unknown 且 IP 归属地为中国的 Peer 自动断开
自动封禁 BitTorrent 媒体播放器 Peer	关闭（OFF）	识别 StellarPlayer、Elementum 等基于 BT 协议做点播的播放器 Peer
Peer 白名单 / 黑名单	默认启用（文件存在时生效）	通过外部规则文件精确控制允许/禁止的 Peer

其中"自动封禁未知 Peer"与"自动封禁 BT 媒体播放器 Peer"两项均提供开关选项，默认关闭，用户可按需在设置中开启。

特性一：自动封禁国内吸血客户端（始终启用）

这是增强版最核心、默认全程生效的一项能力，其判定逻辑全部集中在 peer_blacklist.hpp 的is_bad_peer()函数中。该函数维护了三组正则规则，对每个 Peer 的 peer_id 前缀与客户端标识（User-Agent）进行匹配：

static const std::regex id_filter("-(XL|SD|XF|QD|BN|DL|TS|DT|HP)(\\d+)-"); static const std::regex ua_filter(R"((\d+.\d+.\d+.\d+|cacao_torrent))"); static const std::regex consume_filter(R"(((dt|hp|xm)/torrent|Gopeed dev|Rain 0.0.0|(Taipei-torrent( dev)?)))", std::regex_constants::icase);

从正则结构可以推断其识别思路：

• peer_id 特征匹配（id_filter）：匹配形如-XLxxxx-、-XFxxxx-、-DLxxxx-等-(前缀)(数字)-格式的 Peer ID 段。这些前缀对应 README 中列出的迅雷（Xunlei）、Xfplay、DLBT 等客户端的常见标识约定；其中\d+代表客户端版本号。
• UA 特征匹配（ua_filter）：匹配纯数字点分版本号（\d+.\d+.\d+.\d+）以及cacao_torrent这类特征 UA，用于识别伪装成普通下载器的客户端。
• 流量消耗型客户端（consume_filter，忽略大小写）：匹配dt/torrent、hp/xm/torrent、Gopeed dev、Rain 0.0.0、Taipei-torrent等标识，并且只有当 Peer 的 IP 归属国为CN（中国）时才判定命中。源码注释也指出，这类客户端的判定比较保守（例如GT0003难以确认是否为合法客户端），因此先针对特定 UA 大小写进行拦截。

一旦 Peer 命中任意规则，增强版会调用drop_connection()以connection_refused（连接被拒绝）语义主动断开该 Peer 连接：

void drop_connection(lt::peer_connection_handle ph) { ph.disconnect(boost::asio::error::connection_refused, lt::operation_t::bittorrent, lt::disconnect_severity_t{0}); }

值得注意的是，离线下载器（Offline Downloader）的识别逻辑同样内嵌于该头文件中。is_offline_downloader()通过两条路径判断：其一，IP 归属国为 CN 且端口号大于等于 65000、同时 UA 含Transmission的"伪 Transmission"客户端；其二，IP 归属国为 NL（荷兰）或 CN、且 peer_id 命中-LT1220-/-LT2070-前缀的"伪 libtorrent"客户端。源码注释揭示了这背后的原因：PikPak 等离线服务租用 Worldstream 服务器并以 LT1220/LT2070 版本号通告，迅雷同样在使用 LT2070，因此通过"国家 + 版本号"的组合来识别这些离线下载行为。

特性二：自动封禁来自中国的 Unknown Peer（默认关闭）

该功能由 README 中标注为"Auto Ban Unknown Peer from China Option (Default: OFF)"的开关控制，判定函数为is_unknown_peer()：

bool is_unknown_peer(const lt::peer_info& info) { QString country = Net::GeoIPManager::instance()->lookup(QHostAddress(info.ip.data())); return info.client.find("Unknown") != std::string::npos && country == QLatin1String("CN"); }

其逻辑非常简洁：Peer 客户端标识中包含Unknown字符串，且其 IP 归属国为中国。由于国内网络环境下存在大量不规范的未知客户端，该判定默认关闭，避免误伤正常但未正确通告客户端信息的 Peer。需要开启时，只需在设置中启用"Auto Ban Unknown Peer from China"即可。

特性三：自动封禁 BitTorrent 媒体播放器 Peer（默认关闭）

该功能对应 README 中的 "Auto Ban BitTorrent Media Player Peer Option (Default: OFF)"，判定函数为is_bittorrent_media_player()：

if (info.client.find("StellarPlayer") != std::string::npos || info.client.find("Elementum") != std::string::npos) { return true; } static const std::regex player_filter("-(UW\\w{4}|SP(([0-2]\\d{3})|(3[0-5]\\d{2})))-"); return !!std::regex_match(info.pid.data(), info.pid.data() + 8, player_filter);

它同时覆盖两种场景：一是直接匹配客户端名称中含StellarPlayer（星光播放器）或Elementum（Kodi 的 BT 插件）的 Peer；二是通过 peer_id 正则匹配-UWxxxx-以及-SPxxxx-前缀段，识别基于 BitTorrent 协议实现视频点播的播放器类客户端。这类 Peer 往往"只看不下"、长期占用上传带宽，因此被归类为需要自动断开的目标。由于涉及用户主观偏好，该特性同样默认关闭，由用户自行决定是否开启。

特性四：Peer 白名单 / 黑名单（规则文件驱动）

相比前面几个写死在代码中的规则，白名单/黑名单是增强版提供的可扩展的规则文件机制，其实现位于 peer_filter.hpp 与 peer_filter_session_plugin.hpp。

规则文件的位置与格式

在 sessionimpl.cpp 中，peer_filter_session_plugin会以会话级插件形式被注册，插件构造时会读取数据目录下的两个文件：

m_blacklist(create_peer_filter(QStringLiteral("peer_blacklist.txt"))) m_whitelist(create_peer_filter(QStringLiteral("peer_whitelist.txt")))

• 文件位于 qBittorrent 的数据目录（specialFolderLocation(SpecialFolder::Data)）下，即 Linux 下通常为~/.local/share/qBittorrent/，Windows 下通常为%LOCALAPPDATA%\qBittorrent\，macOS 下通常为~/Library/Application Support/qBittorrent/。
• 文件不存在或没有任何有效规则时，对应过滤功能自动禁用，并在日志中给出提示（'%1' doesn't exist. The corresponding filter is disabled./has no valid rules）。
• 规则文件为纯文本，每行包含两个以空白分隔的正则表达式：peer_id正则 客户端名称正则。peer_filter构造函数逐行解析并校验正则合法性，非法表达式会被跳过并输出警告日志（记录行号），仅保留合法规则。

例如，要封禁所有 peer_id 匹配-AB1234-且客户端名为BadClient的 Peer，可在peer_blacklist.txt中写入：

-AB1234- BadClient

匹配与断开流程

peer_filter_session_plugin::filter()定义了完整的裁决逻辑，其中蕴含两个重要的行为细节：

1. 黑名单优先：先检查黑名单，黑名单规则要求 peer_id 与客户端名称同时命中才判定为黑名单 Peer（match_peer(info, false)），命中后立即断开；
2. 白名单兜底：若未命中黑名单，再检查白名单——peer_id 必须始终匹配白名单规则，而客户端名称仅在握手阶段要求匹配（match_peer(info, handshake)，即握手之后skip_name生效），以避免握手后客户端信息变化导致误杀；
3. 通过握手即放行：一旦 Peer 在握手阶段通过检查，后续交互阶段便不再重复过滤（*stop_filtering = true），从而避免对正常 Peer 造成持续的性能开销。

if (m_blacklist) { bool matched_blacklist = m_blacklist->match_peer(info, false); if (matched_blacklist) { *stop_filtering = true; return true; } } if (m_whitelist) { bool matched_whitelist = m_whitelist->match_peer(info, handshake); if (!matched_whitelist) { *stop_filtering = true; return true; } } if (!handshake) *stop_filtering = true; return false;

命中黑白名单规则的 Peer 同样以connection_refused语义断开连接。

增强特性的底层实现：libtorrent 插件机制

上述所有增强能力都构建在 libtorrent 的扩展（extension/plugin）体系之上，相关脚手架代码位于 peer_filter_plugin.hpp 中，理解它有助于真正读懂这些功能的工作方式。

• peer_filter_plugin派生自lt::peer_plugin，在on_handshake、on_extension_handshake、on_interested、on_have、on_bitfield、on_request等几乎每一个 Peer 事件回调中都会触发handle_peer()检查；一旦m_filter命中，就执行预设的m_action（即断开连接）。
• peer_action_plugin派生自lt::torrent_plugin，为每个新连接创建对应的peer_filter_plugin，起到"每 torrent 分发过滤器"的作用。
• wrap_filter封装了过滤函数的停止逻辑：*stop_filtering = !handshake && !matched，即非握手阶段若未命中，则该 Peer 后续不再参与过滤，避免无意义的重复计算。

在 sessionimpl.cpp 中可以看到各插件的注册顺序与开关的对应关系：

m_nativeSession->add_extension(&create_drop_bad_peers_plugin); // 特性一：始终注册 if (isAutoBanUnknownPeerEnabled()) { // 特性二开关 m_nativeSession->add_extension(&create_drop_unknown_peers_plugin); m_nativeSession->add_extension(&create_drop_offline_downloader_plugin); } if (isAutoBanBTPlayerPeerEnabled()) // 特性三开关 m_nativeSession->add_extension(&create_drop_bittorrent_media_player_plugin); m_nativeSession->add_extension(std::make_shared<peer_filter_session_plugin>()); // 特性四：规则文件 if (isShadowBanEnabled()) // 附加：Shadow Ban m_nativeSession->add_extension(&create_peer_shadowban_plugin);

所有插件的创建函数（如create_drop_bad_peers_plugin）都会先检查 torrent 是否为私有种子（th.torrent_file()->priv()），私有种子一律不应用增强过滤——这一点对私有 Tracker 用户至关重要，详见下文"使用注意事项"。

附加能力：Shadow Ban（影子封禁）

除 README 明确列出的四项特性外，仓库还提供了 Shadow Ban 机制（peer_shadowban_plugin.hpp）。与直接断开连接不同，Shadow Ban不断开 Peer 连接，而是静默丢弃其请求：on_request与write_request在命中State/ShadowBannedIPs配置项中的 IP 列表时直接返回true表示已处理，从而让被禁 Peer 无法从你这里获取任何数据、又察觉不到被封禁。Shadow Ban 的开关由isShadowBanEnabled()控制，被禁 IP 列表通过设置项持久化。

地理定位：DB-IP 数据库与 GeoIP 管理器

前述多项判定（未知 Peer 必须来自中国、离线下载器必须来自中国/荷兰等）都依赖 Peer IP 的国家归属查询。README 明确说明：增强版使用 DB-IP 及 geoipdatabase.cpp），并将国家简码（如CN、NL）与客户端特征组合成最终判定。

安装与编译

从源码编译

仓库根目录下的 INSTALL 文件给出了官方支持的编译依赖版本与构建步骤。构建前需要准备：

依赖	版本要求	说明
Boost	>= 1.76	基础库
libtorrent-rasterbar	1.2.19–1.2.x 或 2.0.10–2.0.x	注意与 rTorrent 所用的同名库区分
OpenSSL	>= 3.0.2	加密支持
Qt	6.6.0 – 6.x	GUI 框架
zlib	>= 1.2.11	压缩支持
CMake	>= 3.16	仅编译期需要
Python	>= 3.9.0（可选）	仅运行时需要，供内置搜索引擎使用

带 Qt 图形界面的标准构建流程为：

cmake -B build -DCMAKE_BUILD_TYPE=Release cmake --build build cmake --install build qbittorrent

不需要图形界面、只构建 headless 服务端（qbittorrent-nox）时，在配置阶段追加-DGUI=OFF：

cmake -B build -DCMAKE_BUILD_TYPE=Release -DGUI=OFF cmake --build build cmake --install build qbittorrent-nox

需要说明的是，INSTALL 中列出的依赖版本会定期上调，以保持受测配置范围可控；低于最小版本的构建即便能通过编译，也不在官方支持范围内。如需自行拉取源码，可克隆镜像仓库：git clone https://gitcode.com/gh_mirrors/qb/qBittorrent-Enhanced-Edition。

各平台发行渠道

README 针对不同平台提供了社区维护的现成包，免去自行编译的成本：

• 通用 Linux（桌面发行版）：可直接使用 release 页面发布的 AppImage 版本（qBittorrent-Enhanced-Edition-x86_64.AppImage），开箱即用；
• Arch Linux：AUR 提供qbittorrent-enhanced-git（GUI）与qbittorrent-enhanced-nox-git（无界面）两个包；
• Debian：由 Kolcha 维护，通过 openSUSE Build Service 的仓库提供 GUI 与 nox 两种变体；
• openSUSE：openSUSE 中文社区及 itachi-re 分别在 OBS 上维护对应版本；
• Ubuntu：poplite 维护的 Launchpad PPA 提供qbittorrent-enhanced；
• macOS（Homebrew）：执行brew install c0re100-qbittorrent；
• Windows：支持多种包管理器——winget install c0re100.qBittorrent-Enhanced-Edition、choco install qbittorrent-enhanced，以及 Scoop（scoop bucket add extras后scoop install qbittorrent-enhanced）。

使用注意事项：私有 Tracker 与多实例运行

仓库根目录的 NOTE.md 针对增强版用户与 Tracker 运营方给出了两条重要的使用须知，务必在部署前阅读。

对用户：私有 Tracker 需谨慎

增强版不应直接在私有 Tracker（PT）上使用，除非该 PT 明确允许 qBittorrent Enhanced Edition（具体取决于你所使用的 PT）。原因有两点：

1. 增强版会向 Tracker 通告与官方版不同的标识：User-Agent 为qBittorrent Enhanced/LATEST_RELEASE_VERSION（例如qBittorrent Enhanced/5.2.0.10），PeerID 为-qB520[A-Z]-形式（例如-qB460A-）；
2. 若 Tracker 未将该客户端加入白名单，使用增强版可能导致账号被封禁。

NOTE.md 明确建议：应当请 Tracker 运营方将本客户端加入白名单，而不是要求开发者修改 Peer ID 或 User-Agent 来规避检测。

对 Tracker 运营方：增强逻辑不影响私有种子

qBittorrent Enhanced 基于 qBittorrent，其目标是自动封禁吸血客户端。但如前文源码所示，所有增强过滤对私有种子（private torrent）都不生效（见 peer_filter_session_plugin.hpp 中th.torrent_file()->priv()的检查），因此 PT 环境下的正常 Peer 流量不会受到增强过滤的干扰。

多实例运行教程

如果你希望同时运行两个实例（例如一个用于公网种子、一个用于私有种子），NOTE.md 提供了两种方法：

• 方法一：便携模式（Portable mode，最适合 Windows 用户）：在 qBittorrent 可执行文件所在目录下创建 profile 目录，然后运行可执行文件，程序即进入便携模式（注意 AppImage 不支持此方法）；
• 方法二：--configuration参数（最适合 *nix 用户）：在命令行中为不同实例指定独立的配置名：

# Windows qbittorrent.exe --configuration="new_instance_profile_name" # *nix 自编译安装版 qbittorrent --configuration="new_instance_profile_name" # qbittorrent-nox 静态构建版 ./qbittorrent-nox --configuration="new_instance_profile_name" # AppImage 版 ./qBittorrent-Enhanced-Edition.AppImage --configuration="new_instance_profile_name"

使用该方法后，qBittorrent 会为每个配置名创建独立的配置目录，两个实例互不干扰。

结语

从本仓库的 README.md 出发，可以看到 qBittorrent Enhanced Edition 的增强核心全部围绕"自动识别并隔离吸血 Peer"展开：写死在代码中的多组正则规则负责拦截迅雷、QQ、百度、Xfplay、DLBT 及各类离线下载器；两个默认关闭的开关按需扩展对未知客户端和 BT 播放器的封禁；peer_blacklist.txt/peer_whitelist.txt规则文件则提供了无需改代码即可定制的黑白名单能力。所有逻辑都通过 libtorrent 插件机制挂在每个 torrent 的 Peer 连接生命周期上，并在私有种子场景下整体豁免，兼顾了功能性与安全性。

对于想深入研究的读者，建议按以下路径继续阅读源码：peer_blacklist.hpp（各类内置判定规则）→ peer_filter.hpp（规则文件解析与匹配）→ peer_filter_session_plugin.hpp（黑白名单裁决逻辑）→ peer_filter_plugin.hpp（插件机制）→ sessionimpl.cpp（插件注册与开关）。同时，NOTE.md 和 INSTALL 分别是使用规范与构建参考，建议部署前后各读一遍。

【免费下载链接】qBittorrent-Enhanced-Edition[Unofficial] qBittorrent Enhanced, based on qBittorrent项目地址: https://gitcode.com/gh_mirrors/qb/qBittorrent-Enhanced-Edition