Merge pull request #23 from PBH-BTN/webui-refactor

新增文档内容
PBH-BTN · Dec 8, 2024 · 31eec0a · 31eec0a
2 parents 5e6fb53 + 90692a3
commit 31eec0a
Show file tree

Hide file tree

Showing 90 changed files with 578 additions and 101 deletions.
diff --git a/docs/btn/_category_.json b/docs/btn/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "BTN 威胁防护网络",
-  "position": 6,
+  "position": 70,
   "link": {
     "type": "generated-index",
     "description": "连接你我，互联共通的情报分享网络"

diff --git a/docs/downloader/_category_.json b/docs/downloader/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "下载器配置",
-  "position": 3,
+  "position": 30,
   "link": {
     "type": "generated-index",
     "description": "将 PeerBanHelper 连接到各个下载器"

diff --git a/docs/faq.md b/docs/faq.md
@@ -1,4 +1,4 @@
-# 常见问题
+# [必看]常见问题
 
 ## 升级后 WebUI 出现白屏、黑屏或无限数据加载
 

diff --git a/docs/hook/_category_.json b/docs/hook/_category_.json
@@ -1,6 +1,6 @@
 {
 	"label": "Hook",
-  "position": 8,
+  "position": 80,
   "link": {
     "type": "generated-index",
 		"description": "外部Hook"

diff --git a/docs/misc/_category_.json b/docs/misc/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "杂项",
-  "position": 99,
+  "position": 999,
   "link": {
     "type": "generated-index",
     "description": "不好归类的内容"

diff --git a/docs/module/_category_.json b/docs/module/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "功能模块",
-  "position": 4,
+  "position": 40,
   "link": {
     "type": "generated-index",
     "description": "PeerBanHelper 的各个功能模块"

diff --git a/docs/module/active-monitoring.md b/docs/module/active-monitoring.md
@@ -17,7 +17,7 @@ Transmission, BitComet 用户因 API 限制可能缺失部分数据。
 
 转到 设置 -> 首选项，向下找到 “主动监控”，打开流量告警并配置每日流量告警阈值。
 
-![traffic-capping](./assets/traffic-capping.jpg)
+![traffic-capping](./assets/active-monitoring.png)
 
 配置完成后，点击页面底部的 “保存” 按钮即可生效。
 
@@ -37,35 +37,3 @@ Transmission, BitComet 用户因 API 限制可能缺失部分数据。
 * 此会话最后一次见到时的 Peer Flags
 * 会话开始时间
 * 会话最后更新时间
-
-## 配置文件 
-
-```yaml
-  # 主动监测 - Active Monitoring
-  # 此功能允许 PeerBanHelper 主动记录每次请求下载器时获取到的数据到本地 SQLite 数据库中
-  # Allow PBH records all data that fetched from downloader and save them into SQLite database
-  # 其产生的数据可被其它模块调用（如：生成图表报表等）
-  # The data produced by this module can be re-used by other modules
-  # 注意：使用 SD 卡或者 EMMC 的设备【不建议】开启此功能，此功能对于存储设备的读写压力较高，可能加快 Flash 存储芯片磨损或导致存储设备过热
-  # NOTE: It is not recommended to enable this module if PBH running on SDCard or EMMC Flash chip.
-  # 另请注意：此功能可能还会导致本地数据库文件大小快速变大，不建议在存储空间不充足的存储设备上使用此功能
-  # NOTE: This may lead database size increase quickly
-  active-monitoring:
-    # 是否启用此功能
-    enabled: true
-    # 清理周期
-    # Retention time
-    # 请注意：由于 SQLite 的特性，记录被删除后不会释放磁盘空间，但后续新数据记录会重新利用此部分空间
-    # Note: Deleted records won't free the disk space, but new data will reuse those parts of space due SQLite internal design
-    # 因此请选择一个合理的记录周期
-    # 时间单位：ms；默认值：5184000000 (60 天) ; default: (60 days)
-    data-retention-time: 5184000000
-    # 清理检查周期
-    # Cleanup check interval
-    # 每 interval 毫秒后，将进行一次数据清理任务
-    # Period of cleanup task will be run
-    # 建议不要设置的太频繁，SQLite 是单线程数据库，无法同时执行多个 SQL 查询，慢查询可能导致 PBH 数据写入延迟/耗尽运行 RAM
-    # Do not set it run too frequently
-    # 时间单位：ms；默认值：604800000 (7 天); default: (7 days)
-    data-cleanup-interval: 604800000
-```
diff --git a/docs/module/assets/active-monitoring.png b/docs/module/assets/active-monitoring.png
diff --git a/docs/module/assets/auto-range-ban.png b/docs/module/assets/auto-range-ban.png
diff --git a/docs/module/assets/btn-profile.png b/docs/module/assets/btn-profile.png
diff --git a/docs/module/assets/client-name.png b/docs/module/assets/client-name.png
diff --git a/docs/module/assets/expression-engine-2.png b/docs/module/assets/expression-engine-2.png
diff --git a/docs/module/assets/expression-engine.png b/docs/module/assets/expression-engine.png
diff --git a/docs/module/assets/ip-blocker.png b/docs/module/assets/ip-blocker.png
diff --git a/docs/module/assets/ip-query.png b/docs/module/assets/ip-query.png
diff --git a/docs/module/assets/multi-dial.png b/docs/module/assets/multi-dial.png
diff --git a/docs/module/assets/pcb.jpeg b/docs/module/assets/pcb.jpeg
diff --git a/docs/module/assets/peer-id.png b/docs/module/assets/peer-id.png
diff --git a/docs/module/assets/region-rule-management.png b/docs/module/assets/region-rule-management.png
diff --git a/docs/module/assets/sub-rules-logs.png b/docs/module/assets/sub-rules-logs.png
diff --git a/docs/module/assets/sub-rules.png b/docs/module/assets/sub-rules.png
diff --git a/docs/module/auto-range-ban.md b/docs/module/auto-range-ban.md
@@ -3,23 +3,5 @@
 由于[进度检查器](./progress-cheat-blocker.md)的滞后性，用户封禁对应 IP 时已经被吸血了一部分流量。此功能的设计是为了帮助用户及时止损。
 当一个 IP 被封禁时，ARB 会扫描所有连接的 Peers。如果有任何 Peer 的 IP 地址和已封禁的任意 IP 地址处于同一子网内，则该 Peer 会被连锁封禁。
 
-## 配置文件
 
-```yaml
-  # 范围 IP 段封禁
-  # 在封禁 Peer 后，被封禁的 Peer 所在 IP 地址的指定前缀长度内的其它 IP 地址都将一同封禁
-  # Range Ban
-  # After a peer got banned, other connected peers that in same range with banned peers will also get banned.
-  auto-range-ban:
-    # 是否启用
-    # Enable?
-    enabled: true
-    # 封禁时间，单位：毫秒，使用 default 则跟随全局设置
-    ban-duration: 604800000
-    # IPV4 前缀长度
-    # IPV4 prefix length
-    ipv4: 30
-    # IPV6 前缀长度
-    # IPV6 prefix length
-    ipv6: 60
-```
+![Auto Range Ban](./assets/auto-range-ban.png)
diff --git a/docs/module/btn.md b/docs/module/btn.md
@@ -2,6 +2,10 @@
 
 使用来自 BTN 网络的云端规则。需要提前[配置 PBH 接入 BTN](../btn/connect.md)。
 
+如果只接入了 BTN 而未启用 BTN 规则模块，则只提交上传数据，不会使用 BTN 云端规则。
+
+![BTN-Profile](./assets/btn-profile.png)
+
 ## 配置文件
 
 ```yaml

diff --git a/docs/module/client-name.md b/docs/module/client-name.md
@@ -8,7 +8,9 @@ ClientName 是 BitTorrent 的一个[扩展协议](https://www.bittorrent.org/bep
 
 ## 配置文件
 
-规则使用[JSON规则引擎](../misc/json-engine.md)语法。
+规则使用[JSON规则引擎](../misc/json-engine.md)语法。你可以通过编写 JSON 规则来控制封禁行为。但如果只是简单的封禁和例外排除，则可以通过 WebUI 完成。
+
+![Client Name](./assets/client-name.png)
 
 ```yaml
   # 客户端名称封禁

diff --git a/docs/module/expression-engine.md b/docs/module/expression-engine.md
@@ -9,7 +9,14 @@ AviatorScript 允许用户加载一个用户脚本，以便在 PBH 检测 Peer
 
 ## 安装 AviatorScript 脚本
 
-AviatorScript 脚本以 `.av` 结尾。将其放入 `data/scripts/` 目录即可加载。
+AviatorScript 脚本以 `.av` 结尾。将其放入 `data/scripts/` 目录即可加载。  
+如果你是本地安装，则可以直接通过 WebUI 管理脚本。
+
+![expression-engine](./assets/expression-engine.png)
+
+特别的，如果你是在内网环境下，则还可以直接上传和编辑脚本文件。
+
+![expression-engine-2](./assets/expression-engine-2.png)
 
 ## 制作 AviatorScript 脚本
 

diff --git a/docs/module/ip-address-blocker-rules.md b/docs/module/ip-address-blocker-rules.md
@@ -2,9 +2,19 @@
 
 PeerBanHelper 的重要模块之一，默认订阅来自 [PBH-BTN/BTN-Collected-Rules](https://github.com/PBH-BTN/BTN-Collected-Rules) 的规则。  
 当有规则内的 IP 连接下载器时，PeerBanHelper 会立刻封禁它。
+
 :::tip
-不建议通过配置文件配置此功能，您可以直接使用 WebUI 的可视化编辑。
+不建议通过配置文件配置此功能，您可以直接使用 WebUI 的可视化编辑
 :::
+
+![rules-sub](./assets/sub-rules.png)
+
+默认情况下，规则订阅模块会在每次 PeerBanHepler 启动时，或者每隔 4 个小时更新一次所有的订阅规则。您可以点击齿轮小标记更改订阅规则的更新频率。
+
+如果需要查看规则的变动情况或者更新是否成功，可点击“查看历史记录”按钮，查看历史更新记录。
+
+![rules-sub-logs](./assets/sub-rules-logs.png)
+
 ## 制作规则
 
 PeerBanHelper 可以加载由以下内容组成的 IP 规则集：

diff --git a/docs/module/ip-address-blocker.md b/docs/module/ip-address-blocker.md
@@ -8,18 +8,26 @@
 
 IP 黑名单，支持输入一个或多个 IP 地址或者 CIDR 地址。列出的 IP 或者被 CIDR 包含的 IP 将在连接下载器时被封禁。
 
+该模块接受 IPV4 地址或者 IPV6 地址，同时也支持 IPV4 和 IPV6 的 CIDR。
+
+![ip-blocker](./assets/ip-blocker.png)
+
 ## Ports
 
 端口黑名单，支持输入一个或多个端口。任意 IP 使用列出的端口连接到您的下载器时即会被封禁。
 
+该功能通常情况下没人用，此处不做解释。
+
 ## ASNs
 
 ASN 黑名单。需要配合 Maxmind GeoLite2 ASN 数据库使用。ASN 数据库应该会在启动 PBH 时伴随 IPDB 一起下载。  
 支持输入一个或者多个 [ASN](https://zh-hans.ipshu.com/asn_list)，所有在给定的 ASN 内的 IP 地址在连接到您的下载器即会被封禁。
 
+不建议中国大陆地区使用 ASN 封禁，因为 AOE 范围可能过大。
+
 ## Regions
 
-国家/地区黑名单。可以输入一个或者多个 [ISO 3166-1 国家二字母码](https://www.rr78.com/World/postal/)。需要配合 Maxmind GeoLite2 City 数据库。 City 数据库应该会在启动 PBH 时伴随 IPDB 一起下载。  
+国家/地区黑名单。可以输入一个或者多个 [ISO 3166-1 国家二字母码](https://www.rr78.com/World/postal/)。需要配合 Maxmind GeoLite2 City 数据库。 City 数据库应该会在启动 PBH 时伴随 IPDB 一起下载。 
 
 ## Cities
 
@@ -34,12 +42,23 @@ ASN 黑名单。需要配合 Maxmind GeoLite2 ASN 数据库使用。ASN 数据
 * `北京` - 封禁北京直辖市
 * `上海` - 封禁上海直辖市
 
+
+![Region](./assets/region-rule-management.png)
+
+如图所示：第一条规则精准匹配辽宁省大连市沙河口区（其它区不受影响），第二条匹配辽宁省大连市（整个市都会被封禁）。
+
+如果你不清楚对方处于哪里（或者该怎么填写），可以使用 “数据透视” 菜单下的 [IP 查询](../statistic/ip-query.md)功能查询其地理位置。
+
+![IP Query](./assets/ip-query.png)
+
 ## Net Type
 
 网络类型黑名单。需要配合 GeoCN 数据库。 GeoCN 数据库应该会在启动 PBH 时伴随 IPDB 一起下载。  
 
 如果 IP 的网络类型被 GeoCN 数据库收录，则可以封禁对应网络类型的 IP 地址。
 
+目前只能通过配置文件编辑此设置。
+
 ## 配置文件
 
 ```yaml

diff --git a/docs/module/multi-dial.md b/docs/module/multi-dial.md
@@ -5,6 +5,14 @@ ARB（自动范围封禁）虽然与本模块具备几乎一致的功能，但
 
 当同一子网范围内的IP数量超过指定阈值，并且这些IP同时连接到同一种子时，系统将启动子网封禁操作。
 
+![multi-dial](./assets/multi-dial.png)
+
+## 追猎
+
+如果某 IP 已判定为多拨，无视缓存时间限制继续搜索其相同子网内的所有其他 Peer。
+
+启用此功能会占用一部分额外运行内存。
+
 ## 配置文件
 
 ```yaml

diff --git a/docs/module/peer-id.md b/docs/module/peer-id.md
@@ -1,9 +1,13 @@
 # PeerID 过滤器
 
-PeerID 过滤器会使用由 Peer 主动汇报的 PeerID 来检测。对于内置 PeerID 过滤器的客户端（例如 qBittorrent Enhanced Edition），建议优先使用其内置的 PeerID 过滤功能。
+PeerID 过滤器会使用由 Peer 主动汇报的 PeerID 来检测。对于内置 PeerID 过滤器的客户端（例如 qBittorrent Enhanced Edition），建议优先使用其内置的 PeerID 过滤功能。  
+
 :::warning
 PeerID 是由 Peer 主动汇报的（可以被随意修改），因此不能作为判定对方客户端的依据。
 :::
+
+![peer-id](./assets/peer-id.png)
+
 ## 配置文件
 
 规则使用[JSON规则引擎](../misc/json-engine.md)语法。

diff --git a/docs/module/progress-cheat-blocker.md b/docs/module/progress-cheat-blocker.md
@@ -1,6 +1,6 @@
 # 进度检查器
 
-进度检查器（ProgressCheatBlocker）（有时也称为 PCB 或者启发式检测算法）是由 PeerBanHelper 创建的基于下载进度的一种启发式的反吸血检测算法。  
+进度检查器（ProgressCheatBlocker）（有时也称为 PCB 或者启发式检测算法）是由 PeerBanHelper 创建的基于下载进度的一种启发式的反吸血检测算法。 
 
 ## 概述
 
@@ -19,6 +19,30 @@ PeerBanHelper 会持续追踪所有活动种子上的活跃 Peers，实时追踪
 
 PBH 持续追踪 Peer 的下载进度，并计算其上传量和上传增量。当 Peer 的统计数据由于某种原因重置了(例如更换端口和PeerID)，PBH 会通过之前记录的数据为 Peer 修正进度以避免进度欺骗。  
 
+![PCB](./assets/pcb.jpeg)
+
+## 进度差异
+
+PeerBanHelper 会根据下载器数据、本地记录数据和 Peer 汇报数据，综合计算 Peer 当前最少进度。如果 Peer 的进度比最少进度还要少（虚报进度），则 PeerBanHelper 将会封禁 Peer。
+
+## 过量下载
+
+恶意 Peer 的目的是尽可能多的从受害者处下载数据，因此 PeerBanHelper  会根据下载器数据、本地记录数据和 Peer 汇报数据，综合计算 Peer 已经下载的量。
+
+该计算的下载量不完全依赖下载器，因为攻击者可以轻松欺骗和重置下载器的统计信息。
+
+如果 Peer 下载的数据量超过整个当前用户拥有的数据总大小一定比例（也就是下载了比拥有的种子的总体积还要多的数据），PeerBanHelper 将对其执行封禁操作。
+
+## 持久化记录
+
+关闭状态下，数据全部保存在内存中。当内存不足或者一段时间没有使用后，数据将会被清空删除。此时 PeerBanHelper 会 “忘记” 之前记录的数据。
+
+启用持久化记录后，在从内存删除前，数据将被保存到数据库中，并在未来需要（且数据未过期时）重新读取载入。可以有效避免攻击者打游击战，避免攻击者进行缓存遗忘攻击。
+
+## 快速 PCB 测试
+
+一种快速检测算法，当 Peer 的下载进度（计算的）达到 “快速 PCB 测试启动阈值” 后，PeerBanHelper 会短暂封禁对方（默认是 30 秒）以便断开连接，并在稍后解除封禁。一部分恶意客户端在断开连接后，其汇报进度将归零，PCB 反作弊将能够立刻捕捉这种异常情况，加快异常、恶意客户端的封禁速度。减少流量损失。
+
 ## 配置文件
 
 ```yaml
@@ -90,4 +114,5 @@ PBH 持续追踪 Peer 的下载进度，并计算其上传量和上传增量。
 
 ## 缺陷
 
-* 如果没有关闭下载器的 “允许来自同一 IP 地址的多个连接”，则可能导致统计数据出错，成倍增加快速增长。这个选项默认是关闭的。
+* 如果对方使用 “超级做种”，那么这可能会导致意外封禁。
+* 如果没有关闭下载器的 “允许来自同一 IP 地址的多个连接”，则可能导致统计数据出错，成倍增加快速增长。这个选项对于 qBittorrent 来说默认是关闭的。
diff --git a/docs/network/_category_.json b/docs/network/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "网络和 HTTP 服务器",
-  "position": 5,
+  "position": 60,
   "link": {
     "type": "generated-index",
     "description": "PeerBanHelper 的网络和内置 HTTP 服务器设置"

diff --git a/docs/network/assets/proxy-server.png b/docs/network/assets/proxy-server.png
diff --git a/docs/network/assets/webui-settings.png b/docs/network/assets/webui-settings.png
diff --git a/docs/network/http-server.md b/docs/network/http-server.md
@@ -13,6 +13,10 @@ server:
   http: 9898
 ```
 
+或者通过 WebUI 直接修改：
+
+![webui-settings](./assets/webui-settings.png)
+
 ## 限制 WebUI 监听本地网络
 
 为了提升安全性，您可以将 WebUI 的监听地址配置为仅允许本地访问。
@@ -27,6 +31,12 @@ server:
   address: "0.0.0.0"
 ```
 
+或者通过 WebUI 直接修改 “地址” 配置项。
+
+`0.0.0.0`：监听所有网卡的端口  
+`127.0.0.1`：监听本地回环端口（仅本机可以访问）  
+`网卡 IP 地址`：只有对应网卡的流量可以访问
+
 将 `address` 设置为 `"127.0.0.1"` 可以确保只有本地机器能够访问 WebUI 和下载器封禁列表的端点。
 
 ## 使用自定义 WebUI
@@ -58,9 +68,11 @@ server:
   allow-cors: false
 ```
 
-将 `allow-cors` 设置为 `true` 可以允许跨域访问，但请注意这可能会带来安全风险。
+或者在 WebUI 中直接切换 “允许 CORS” 开关。
+
+注意：将 `allow-cors` 设置为 `true` 可以允许跨域访问，但请注意这可能会带来安全风险。
 
-## 修改 WebUI 访问令牌
+## 修改 WebUI Token
 
 如果您忘记了 WebUI 的访问令牌，或者希望更改令牌，可以在配置文件中进行更新：
 
@@ -76,6 +88,7 @@ server:
 
 ## 开发自定义 WebUI/WebAPI
 
+
 我们鼓励开发者为 PeerBanHelper 创建或改进 WebUI。
 
 自 v6.0.1 版本起，您可以在以下链接查看完整的 API 文档：

diff --git a/docs/network/proxy-server.md b/docs/network/proxy-server.md
@@ -2,6 +2,13 @@
 
 尽管修改 JVM 参数也能让 PBH 使用代理服务器，但我们推荐您通过配置文件修改相关配置。
 
+![proxy-server](./assets/proxy-server.png)
+
+不使用代理：不使用任何代理服务器，包括系统代理。  
+系统代理：自动使用系统代理服务器（也就是俗称的 IE 代理）  
+HTTP 代理：指定 HTTP 代理服务器的 IP 和端口号，暂不支持需要登陆的 HTTP 代理  
+Socks5 代理：目前不可用
+
 ## 配置文件
 ```yaml
 # 代理服务器设定

diff --git a/docs/platform/Windows.md b/docs/platform/Windows.md
@@ -4,6 +4,10 @@
 
 在 Windows 11 的 22H2 版本或更高版本中，如果系统 BIOS 和 CPU 均支持，PeerBanHelper（PBH）将自动启用 [EcoQoS](https://devblogs.microsoft.com/performance-diagnostics/introducing-ecoqos/) 节能功能。此功能旨在缓解 PBH 在执行检测任务时因瞬时计算量增加导致的 CPU 睿频及电量消耗，同时降低 PBH 的运行优先级，以便将更多系统资源分配给其他应用程序。
 
+在更旧版本的 Windows 或者平台上，此功能将仅降低自身的进程优先级。
+
+在其他操作系统上则什么都不做。
+
 当 EcoQoS 成功启用时，PBH 的图形用户界面（GUI）窗口将显示一个叶子图标，以作为启用状态的视觉提示：
 
 ![EcoQoS 图标](./assets/ecoqos.png)

diff --git a/docs/platform/_category_.json b/docs/platform/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "平台特定功能",
-  "position": 7,
+  "position": 80,
   "link": {
     "type": "generated-index",
     "description": "在不同平台上的专有功能"

diff --git a/docs/platform/assets/ecoqos.png b/docs/platform/assets/ecoqos.png
diff --git a/docs/prefandlang/_category_.json b/docs/prefandlang/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "外观和语言",
-  "position": 8,
+  "position": 90,
   "link": {
     "type": "generated-index",
     "description": "PeerBanHelper 的界面和日志行为设置"