PeerBanHelper Documentation

Automatically block unwanted, leeches and abnormal BT peers with support for customized and cloud rules.| BT 反吸血工具 - 自动封禁不受欢迎、吸血和异常的 BT 客户端，并支持自定义规则。支持...

6,155 stars Java Java 1 file · ~3,983 tokens #biglybt#bitcomet#bittorrent#deluge#dt-torrrent#dt0001#gt0002#gt0003
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy PeerBanHelper on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name peerbanhelper --restart always pbh-btn/peerbanhelper:latest
docker-compose.yml
yaml (docker-compose.yml) 
version: "3.9"
services:
  peerbanhelper:
    image: @IMAGE@
    restart: unless-stopped
    container_name: "peerbanhelper"
    volumes:
      - /var/packages/peerbanhelper/shares/peerbanhelper:/app/data
    network_mode: host
    environment:
      - PBH_USER_LOCALE=zh-CN
      - PBH_PKG_SYNOLOGY=true
    stop_grace_period: 30s

File: README.md

PeerBanHelper

English

自动封禁不受欢迎、吸血和异常的 BT 客户端，并支持自定义规则。

在安装前试用 PeerBanHelper：前往演示站

PeerBanHelper 是一个开放源代码的个人网络防火墙安全软件。通过连接支持的应用程序（如：BitTorrent 客户端软件）的 Web API 接口获取受保护应用的连接信息，识别其中可能包含潜在安全威胁的连接并通知对应的应用程序主动断开其连接。

功能介绍

PeerBanHelper 主要由以下几个功能模块组成：

此外，PeerBanHelper 会在启动时下载 GeoIP 库，成功加载后支持以下功能：

  • 在封禁列表中查看 IP 归属地，AS 信息（ASN、ISP、AS 名称等），网络类型信息（宽带、基站、物联网、数据中心等）
  • 基于 GeoIP 信息按国家/地区、城市、网络类型、ASN 等封禁 IP 地址
  • 查看 GeoIP 统计数据

[!TIP]
为获得最佳效果，建议配合我们维护的 IP 规则库 PBH-BTN/BTN-Collected-Rules 和 BTN 网络 一起食用，不过这是完全可选的。

支持的客户端

[!CAUTION]
所有安装在 Docker 中的下载器，必须使用 host 网络驱动程序。PBH 需要下载器能获得 Peer 的真实 IP，不能使用 bridge 桥接模式！

  • qBittorrent/qBitorrent，4.5.0 或更高版本，不支持 XDown
  • BiglyBT（需要安装插件）
  • Deluge（需要安装插件）
  • Transmission (4.1.0-beta2 或更高版本)
  • BitComet v2.18 或更高版本 (不支持 P2SP LTSeed 长效种子反吸血，因为 BitComet 暂时无法封禁长效连接)

PeerBanHelper 仅支持对传统 IPv4 或 IPv6 地址的反吸血，如遇 I2P 或者 Tor 连接将主动忽略。

截图

主界面 封禁列表 封禁日志 封禁统计 规则统计 规则订阅

安装 PeerBanHelper

查看 PeerBanHelper 文档

常见问题

在报告问题前，请先检查 常见问题列表

需要帮助？

考虑加入我们的 QQ 群！

1 群：932978658

或者：Telegram

声明

使用本软件意味着你同意以下声明：

违法网站和黑灰产请勿向我组织开发或支持人员发起任何形式的人工服务请求；严禁使用 PBH-BTN 团队的任何成果（包括但不限于代码，镜像，程序，BTN规则集等）从事任何违法违规、危害国家安全、实施或帮助他人实施电信犯罪等非法活动。
用户不得通过 PBH-BTN 团队的任何成果（包括但不限于代码，镜像，程序，BTN规则集等）进行任何损害其它个人或组织的利益的活动。在任何违反个人或组织权益的情况下使用 PBH-BTN 团队的任何服务、产品均不被允许。
用户使用本软件造成的任何后果，由用户自行承担，与本软件开发者无关。

Star History

Tools

在 PeerBanHelper 的开发过程中，我们使用到了许多优秀的专业工具。感谢下面的公司或项目慷慨的提供开源许可证：

Install4j

PeerBanHelper 使用 Install4j multi-platform installer builder 打包多平台安装程序。感谢 ej-technolgies 的开放源代码许可证。点击链接或者下面的图片下载 install4j。

JProfiler

PeerBanHelper 使用 JProfiler all-in one Java profiler 对程序进行性能分析与优化。感谢 ej-technolgies 的开放源代码许可证。点击链接或者下面的图片下载 JProfiler。

纯真 CZ88.NET 社区版 IP 库

纯真(CZ88.NET)自2005年起一直为广大社区用户提供社区版IP地址库，只要获得纯真的授权就能免费使用，并不断获取后续更新的版本。如果有需要免费版IP库的朋友可以前往纯真的官网进行申请。

纯真除了免费的社区版IP库外，还提供数据更加准确、服务更加周全的商业版IP地址查询数据。纯真围绕IP地址，基于 网络空间拓扑测绘 + 移动位置大数据 方案，对IP地址定位、IP网络风险、IP使用场景、IP网络类型、秒拨侦测、VPN侦测、代理侦测、爬虫侦测、真人度等均有近20年丰富的数据沉淀。

Credit

Backend

WebUI

File: pkg/synopkg/PeerBanHelperPackage/README.md

Synology Example Package.

This package is depend on Synology toolkit framework.
This package is a template package, users can modify this package to generate their own packages.

Please setup the toolkit by following pkgscripts-ng

Build package.

After setup toolkit environment, you can create package by command:

bash
pkgscripts-ng/PkgCreate.py [-p {platforms}] -c -v 7.0 ExamplePkg
bash
pkgscripts-ng/PkgCreate.py -p avoton -c -v 7.0 ExamplePkg
pkgscripts-ng/PkgCreate.py -c -v 7.0 ExamplePkg # will generate package for all platforms in build_env

You can find generated packages in result_spk directory.

File: webui/src/views/custom-script/components/editor/aviatorscript/README.md

AviatorScript

the avaitorscript support is original developed by OpenDSL and rewritten in ts by @Gaojianli

File: webui/README.md

pbh-fe

This is a alternative WebUI of the PeerBanHelper, based on modern front-end stacks.

Quick preview: https://pbh.u2b.eu

API Doc: https://apifox.com/apidoc/shared-b24f42a4-67f5-402a-900d-9fad3ae9917b

Feature

  • Custom Endpoint
  • Ban List
  • Ban Logs
  • Auto Refresh
  • Client Status
  • Max-ban list with search
  • Manage rule subscription

Screenshots

How to contribute

This project using Vue 3 + Arco Design

Project Setup

You are supposed to use pnpm to manage the dependencies.

sh
pnpm install

Compile and Hot-Reload for Development

sh
pnpm run dev

Type-Check, Compile and Minify for Production

sh
pnpm run build

Lint with [ESLint](https://eslint.org/)

sh
pnpm run lint

File: README.EN.md

PeerBanHelper

简体中文

Automatically ban unwelcome, leeching, and abnormal BT clients with support for custom rules.

Try PeerBanHelper before install to your device: Demo Site

Features

PeerBanHelper consists of the following core modules:

Additionally, PeerBanHelper downloads the GeoIP database on startup. Once loaded, it supports:

  • Viewing IP geolocation, AS info (ASN, ISP, AS Name), and network type (Broadband, Cellular, IoT, Data Center, etc.) in ban lists
  • Banning IPs by country/region, city, network type, ASN, etc.
  • GeoIP statistics visualization

[!TIP]
For optimal performance, we recommend using our maintained IP rule repository PBH-BTN/BTN-Collected-Rules and BTN Network, though this is entirely optional.

Supported Clients

[!CAUTION]
All Docker-based downloaders must use host network driver. PBH requires real peer IPs - bridge mode is unsupported!

  • qBittorrent/qBittorrent v4.5.0 or newer (XDown not supported)
  • BiglyBT (requires plugin)
  • Deluge (requires plugin)
  • Transmission (v4.1.0-beta2 or newer required)
  • BitComet v2.18 or newer (LTSeed anti-leech unsupported due to BitComet's limitation)

PeerBanHelper only supports traditional IPv4/IPv6 anti-leech. I2P/Tor connections are ignored.

Screenshots

Main UI Ban List Ban Logs Ban Statistics Rule Statistics Rule Subscriptions

Installation

See PeerBanHelper Documentation

FAQ

Before reporting issues, check FAQ

Need Help?

Join our QQ Group or Telegram Group!

Disclaimer

By using this software, you agree to:

Illegal websites and black/grey industries shall not request any form of manual service from PBH-BTN developers/supporters. Strictly prohibited to use any PBH-BTN assets (including but not limited to code, images, programs, BTN rulesets) for illegal activities, endangering national security, telecom fraud, or assisting others in such acts.
Users shall not use PBH-BTN assets to harm other individuals/organizations. Any usage infringing rights of others is prohibited.
Users bear full responsibility for consequences arising from software usage. Developers assume no liability.

Star History

Tools

We use these excellent tools during development. Thanks to the companies/projects for providing open-source licenses:

Install4j

PeerBanHelper uses Install4j multi-platform installer builder. Thanks to ej-technologies for the OSS license. Click the link or image below for install4j.

JProfiler

PeerBanHelper uses JProfiler all-in one Java profiler for performance analysis. Thanks to ej-technologies for the OSS license. Click the link or image below for JProfiler.

Credit

Backend

WebUI

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#biglybt Browse biglybt catalog → #bitcomet Browse bitcomet catalog → #bittorrent Browse bittorrent catalog → #deluge Browse deluge catalog → #dt-torrrent Browse dt-torrrent catalog → #dt0001 Browse dt0001 catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →