后台“运行设置 → 页脚 → 支持按钮”可添加、删除和排序最多 12 个按钮,并编辑跳转链接、按钮图片地址和
中英文图片说明。前台直接显示原图,不叠加文案;多个按钮并排显示,空间不足时换行。图片说明用于
无障碍访问,不作为可见按钮文案。图片支持 SVG,链接和图片地址支持站内绝对路径或 HTTP(S) URL。
默认使用爱发电官方 support me on afd-发电紫.svg,跳转到 https://ifdian.net/a/Ghost_chu。
支持按钮对所有访客可见,不受页脚链接分栏可见范围影响;删除全部按钮后隐藏该区域。
GET/PUT /api/admin/footer-config 的 supportButtons 为按展示顺序排列的数组,每项包含
labelZh、labelEn(图片说明)、href 和 iconUrl(完整按钮图片地址)。
GET /api/ui/footer 返回同名数组。配置保存在现有页脚配置中,无需数据库迁移;旧配置缺少该字段时
使用默认爱发电按钮,显式空数组表示不展示按钮。后台保存后立即更新配置,已打开页面在下一次页脚刷新时生效。
后台“BTN 管理 → 服务根地址”可调整主根地址、优化根地址、自动路由开关及运营商/省份关键词。 默认保留原规则:运营商包含“移动”,或省份包含福建、江苏、浙江、四川、重庆、河南、湖北时选择优化根地址。 关键词使用包含匹配(区分大小写),以英文逗号或换行分隔;清空列表会停用对应条件。任一条件命中即可, 未命中或 IP 地理资料缺失时使用主根地址。关闭自动路由后默认使用主根地址。 客户端的 forceRoute=chinamainland/global 继续优先选择对应地址,不受自动路由开关影响。
配置键为 sparkle.auto-route-enabled、sparkle.chn-route-isps、sparkle.chn-route-provinces, 使用现有数据库配置,无需新增迁移;后台保存后热更新,其他实例在约一秒内刷新。 命令行和环境变量覆盖继续优先于后台保存的值。
客户端配置的 ip_query 能力声明详细查询、评论和批量计数地址。客户端使用现有 BTN 应用凭据,
在能力要求时为每次请求提交独立的 PoW 挑战解答。
GET /ping/queryIp/lookup?query=...支持单 IP 和 CIDR,返回查询详情及当前 BTN 账户的canComment。 查询统计保留labels字符串数组,并通过label_details提供可本地化的标签。规则标签包含与查询范围 相交的 IP 黑名单和允许列表规则,命中 BTN Bypass 时另有同名标签。单 IP 的 BTN 用户昵称遵循公开 资料的可见性和审核结果,CIDR 仅显示通用 BTN 用户标签。GET /ping/queryIp/comments?scope=...分页获取评论。POST /ping/queryIp/comments发表评论或回复,PUT/DELETE /ping/queryIp/comments/{id}编辑或删除本人评论。POST /ping/queryIp/commentCounts接收包含 1 至 50 个单 IP 的 JSON 数组,返回以输入地址为键的计数。 计数包括覆盖该 IP 的网段中已审核通过且未删除的评论。评论区关闭展示时返回零。
后台“BTN 管理 → IP 查询与评论控制”可设置 IP 查询及评论操作的 PoW 开关,以及独立的计数 PoW、频率上限和 Redis TTL。计数默认每个 BTN 应用每 60 秒可请求 12 次,Redis 默认缓存 300 秒,包括零结果。 TTL 更新后,新请求使用新 TTL 的缓存,旧条目按原有效期自动过期。
数据库使用 Flyway 管理,应用启动时会自动检查并执行 classpath:db/migration 中尚未应用的
迁移。全新数据库从 V1__initial_schema.sql 建库;已经有数据的生产库会在
FlywayMigrationConfig 中识别当前结构版本并建立基线,不会重新执行旧版建表或大表迁移。
生产环境需要 PostgreSQL、TimescaleDB、pg_trgm 扩展,以及具备创建 schema 对象、
索引和 TimescaleDB policy 权限的数据库账号。timescaledb 扩展需由数据库管理员预装,
应用迁移只会执行 CREATE EXTENSION IF NOT EXISTS。
升级顺序如下:
- 备份数据库,确认
timescaledb扩展可用。 - 先部署一次新版本。Flyway 会在 PostgreSQL advisory lock 保护下自动建立/更新
flyway_schema_history,无需手工执行 SQL。 - 查看启动日志。已有库接管会记录
Adopting existing Sparkle3 schema into Flyway at legacy version ...;之后的增量迁移由 Flyway 正常记录。 - 后续 schema 变更只需新增
V<version>__<description>.sql,禁止修改已经发布的迁移文件 checksum。
如果旧库还未完成 TimescaleDB 转换(ban_history 不是 hypertable),应用会拒绝自动
接管并给出提示。此时需要先使用 db_sql/ 中保留的历史脚本完成一次
v20_convert_to_timescaledb.sql 到 v22_fuck_index.sql 的升级,再启动新版本。
前端使用 Vue 3、TypeScript、Vue Router、Pinia 与 Arco Design Vue。依赖管理统一使用 pnpm:
cd frontend
pnpm install
pnpm dev开发服务器默认监听 http://localhost:5173,并将 /api、OAuth 与头像请求代理到
http://localhost:7799。前端支持简体中文和英文,可在导航栏实时切换,语言选择会保存在浏览器本地。
主前端支持跟随系统、亮色和暗色三种外观,默认跟随系统。可在导航栏的外观菜单或 “个人资料 → 设置 → 个性化”中切换,立即生效并保存在当前浏览器,多个标签页同步。 主题覆盖登录页、用户页面、后台、弹层及统计图表;不影响独立安装的 Flarum 扩展主题。
生产构建由 Gradle 自动调用 pnpm,并把 Vite 产物打入 Spring Boot jar:
pnpm --dir frontend build
./gradlew build单独验证前端可运行:
pnpm --dir frontend typecheck
pnpm --dir frontend build角色为 admin 的用户可从右上角用户菜单进入 /admin/dashboard。角色为 moderator
的协管用户可从右上角进入受限后台;管理员自动继承协管的全部权限。后台包含:
- 仪表盘:主机 CPU、内存、磁盘实时指标,7 天趋势,JVM 信息及功能模块统计。
- 用户管理:搜索、创建、编辑、停用/恢复和删除用户。删除用户前必须先删除其用户应用。
- 用户资料:支持通过
/user/profile/<uid>查看其他用户;头像、用户名与积分分别遵循对方独立隐私选项。 - 站内信:导航栏头像左侧的收件箱集中展示用户消息和系统通知。用户间的普通站内信以对话列表展示,包含已发送与已接收的消息,支持分页查看历史和站内回复;系统通知与群发消息独立展示。删除收到的消息仅影响本人收件箱,发送方仍可查看其发送记录。普通用户每天最多发起 15 次站内信发送;管理员和协管可向全站群发或指定 UID 发送,支持 Sparkle BTN 系统身份与强制邮件提醒。
- 通知提醒:用户可分别控制每个通知类别的站内信和邮件提醒。法律合规与账户安全通知不可关闭;一般通知、更新日志和日常公告默认关闭邮件提醒,其余类别默认开启。所有类别默认开启站内信,已保存的个人选择不受默认值调整影响。
- 用户联系邮件:原有纯文本联系邮件审核能力保留;后台可配置邮件标题/正文模板并查询发送人、目标人、时间、IP 和 User-Agent 审计记录。
- 用户应用管理:搜索、创建、转移所有者、停用、恢复、重置密钥和删除。可按最近 7、3 或 1 天的封禁记录数降序排列,查看应用归属并在操作列停用应用。统计窗口按封禁发生时间滚动计算,窗口内无记录的应用显示为 0。管理接口
GET /api/admin/userapps传入banDays=7、3 或 1时按该口径返回排行,banCount为十进制字符串。 - 手动规则:维护
rules表中的 IP 黑名单、Peer ID、客户端名称、端口和脚本规则,并可预览生成的 IP 黑名单。 - 功能模块:集中维护自动分析模块的开关、Cron、统计窗口、流量阈值和投票阈值,保存后动态重建调度任务。
- 任务状态与计划:按计划任务、触发任务和启动任务查看运行结果,调整受模块管理的 Cron,并即时启用或停用对应模块。接入方式见 后台任务系统使用与接入指南。
- 运行设置:热更新协议版本、IP 查询 PoW、客户端发现开关,以及最近 7 日流量统计的启用状态、刷新间隔、统计窗口和手动刷新。
- 公告管理:支持“全局最顶公告区”和“首页 Hero 公告区”两个位置,提供绿、黄、蓝、红四种 Arco 警告样式、中英文内容、定时生效、排序和用户关闭。默认不发送站内信;编辑器中开启“同时发送站内信”后,保存已启用的公告时会立即按重大/日常公告类别发送一次通知,不随公告展示时间延后。管理 API 的可选请求字段
sendInbox默认false,仅对本次保存生效,不存储为公告属性;列表中的直接发布操作不发送站内信。 - IP 评论管理:检索、编辑、通过、拒绝、隐藏和恢复 IP / CIDR 评论区评论,并可手动重新提交 AI 审核;计划任务会自动补审待审核和审核失败的评论。
- 站内信群发:管理员和协管可选择全部活跃用户或指定 UID、通知类别、发送身份及是否强制邮件提醒。
- Navbar 导航管理:内置项可启停、改名、选择图标和排序;自定义项支持中英文名称、站内路径或外部链接。
- 首页统计:使用 ECharts 展示 Peer ID、客户端、GeoIP 城市、IPv4/IPv6 趋势,以及 BTN 客户端版本和地址栈分布。后台“首页数据刷新”的各模块开关统一控制自动刷新与首页显示,关闭后重新加载首页即可隐藏对应统计卡片或图表,并停止自动刷新。仍可手动刷新。
GET /api/ui/home的enabledModules返回各模块的启用状态,不包含后台运行详情。 - 存储与策略:查看普通表与 TimescaleDB hypertable 占用,显示压缩/列存前后大小和 chunk 状态,管理自动压缩、列存和自动淘汰策略。
ban_history维护:按 cutoff 预览并删除完整旧 chunks;删除需要输入确认文本,避免误操作。- 版本提醒:基于客户端产品名、User-Agent 和 NPM 语义化版本范围配置邮件通知,支持启停、编辑、匹配测试、真实测试邮件和发送记录。
- 会员平台与许可证:在“捐赠支持”页统一配置爱发电、Patreon、Ko-fi、面包多的官方接入凭据, 查看同步运行记录、远端缺失对账、交易账本和已签发许可证,并维护所有平台共用的 PBHLicense 签发规则。
主机指标每分钟采样一次并保存到 Redis key sparkle:admin:metrics:host:history,保留 8 天。
后台运行设置保存在 PostgreSQL 表 app_config_entries,并保留 application.yaml 中的值作为默认值。
数据库、Redis、OAuth、邮件、Sentry 和令牌等敏感配置不会暴露在后台。
管理 API 位于 /api/admin/**,除 Spring Security 的 admin / moderator authority 校验外,
还会在每次请求时重新检查数据库中的最新角色与停用状态。协管仅能访问任务状态与计划、公告管理、
站内信群发、应用管理、GitHub 规则同步、BTN 管理、封禁模块管理和手动规则模块。
存储统计会自动识别 TimescaleDB 2.18 以前的 hypertable_compression_stats 和 2.18+ 的
hypertable_columnstore_stats。hypertable 使用 hypertable_detailed_size 汇总 chunk、
索引和 TOAST 占用;普通 PostgreSQL 表使用系统目录和统计信息计算占用。TimescaleDB 会按
chunk 删除历史数据,因此手动 cutoff 的实际边界可能早于所选时间。
原先写死在 UserappServiceImpl 中的 PeerBanHelper 9.3.0 安全提醒已迁移为版本提醒规则。
首次启动会在 Redis 中创建对应的默认规则,之后可在后台自由修改或删除。规则保存在
sparkle:admin:version-alerts:rules,发送记录保存在
sparkle:admin:version-alerts:deliveries。
积分不再发放“一次性积分”和“新 IP 地址”奖励。升级到 Flyway V58 会删除这两类积分来源的
配置和历史分类计数,并移除 point_known_ips、point_daily_ips 及对应去重函数。
“命中规则的 IP”改为每条有效命中直接计奖,仍受每日上限约束,不再按 IP 去重;
point_claims 继续用于活跃应用每日领取。
爱发电、Patreon、Ko-fi、面包多都是“捐赠支持”的组成部分,统一写入 member_transactions
账本,用户通过 member_platform_bindings 关联账号。用户设置中只有一个“捐赠支持与许可证”
入口,后台也只有一个“捐赠支持”页,不再单独展示爱发电。
许可证槽位由 PbhLicenseService 按同一套规则计算:商品交易按订单产生槽位,捐赠/订阅按
结算货币累计,每达到配置金额产生一个槽位;签发规则由所有平台共用。
各平台接入方式:
- 爱发电:在后台“捐赠支持”页填写用户 ID 和 Access Key。订单通过
product_type自动区分商品与赞助方案,不需要再手工维护 Plan ID 列表;商品订单直接产生 许可证槽位。 - 爱发电备注邮箱自动绑定:已完成订单同步时,若爱发电账号尚未绑定,会优先将整段备注按邮箱 解析,失败后提取备注中的邮箱(支持中文说明、换行、尖括号及重复出现的同一地址)。忽略大小写, 不折叠加号别名;多个不同邮箱、匹配不到用户、同一邮箱对应多个用户、封禁用户或已有绑定冲突 时不自动关联。成功时原子写入两套账号绑定记录,不覆盖任何已有归属,重复同步不会重复绑定。 新购买在下一次订单同步时生效;历史订单全量重同步也会重试。操作日志仅记录 BTN 用户 ID, 不记录备注或邮箱。
- Patreon:填写 Patreon 开发者门户中的 Creator Access Token(需要
campaigns.members权限)。Campaign ID 留空时自动发现,可按 Campaign 币种结算。Patreon 公开 API 只有会员订阅,没有商品接口,因此会员的累计支持金额(campaign_lifetime_support_cents)计入捐赠累计。可选填写 Webhook Secret 接收members:*实时事件;不配置时依靠定时全量同步。 - Ko-fi:Ko-fi 没有公开的历史查询 API,只提供支付 Webhook。后台填写 Ko-fi “API/Webhooks → Advanced”中的 Verification Token,并把页面给出的 Webhook 地址填到 Ko-fi。启用后收到的捐赠、订阅付款和商品订单会实时入账;启用前的历史交易无法补拉。
- 面包多:填写“编辑资料 → 开发设置”中的开发者 Key。定时任务通过
https://x.mbd.pub/api/order-list同步全部作品订单。面包多 API 不返回买家标识,因此用户 按订单号认领:每笔订单单独绑定,同一个 Sparkle 用户可以认领多个订单(FlywayV59仅对 面包多放宽了“每个平台只能绑定一个账号”的唯一约束)。 - 链动小铺:没有公开的订单或销售 API,后台保留该平台的说明但不提供自动同步与绑定。
平台的商品与捐赠会分别计数,但“累计已捐赠”汇总该账号全部已完成交易。同步任务每 6 小时 运行一次,也可在后台按平台立即同步;每次同步都会记录运行结果、远端缺失和交易变更审计。
管理员在“捐赠支持”页使用“爱发电消息记录许可证启发式导入”。先同步爱发电交易,再输入
爱发电网站会话的 auth_token(与 Open API Access Key 不同),按需选择临时校验私钥文件。
工具只在内存中使用会话凭据;私钥只用于派生公钥,不写入业务配置。默认同时使用 PBH 官方公钥
和已配置的签发私钥所对应的公钥。后台异步分页读取所有对话和历史消息,从消息任意位置及嵌套
文本中提取 Base64(含换行),按 RSA 分块验签、检查 verifyMagic 和 v1/v2 格式。
v2 优先按 paymentOrderId 匹配同一爱发电账号的已完成交易。没有支付订单号时,优先关联聊天
中该许可证之前最近的发电系统卡片(type=receive、消息类型 2),读取其中的 out_trade_no、
金额及 SKU/方案。按消息顺序跨页关联,同一笔发电后发送的多个不同许可证会全部登记;同一
许可证后来被重发时使用其最早出现位置对应的卡片,不归入后一次发电。卡片订单尚未同步到
本地时也能登记,后续同步该订单后不会重新提供槽位。金额按 CNY 换算为当前结算货币。
扫描每张发电系统卡片时,也会从卡片备注尝试按上述邮箱规则绑定 BTN 账号;即使该对话没有
许可证,或许可证已经导入但买家尚未绑定,也会执行此步骤。无需清空旧许可证,重新扫描即可。
没有可用卡片时,才在许可证创建前 7 天内恰好存在一笔已完成交易的情况下使用时间启发式匹配。
其他情况保留为待匹配记录,管理员可在
同页输入同一爱发电账号的订单号完成匹配。待匹配记录存在时,相关账号暂不能生成新许可证。
匹配成功的整笔商品或捐赠交易不再提供许可证额度,不额外扣减一次捐赠槽位;绑定账号前也能
导入,用户后续绑定相同爱发电账号后可直接查看历史许可证,并按扣除历史交易后的余额签发。
每份许可证按规范化密文的 SHA-256 去重,并使用数据库唯一索引和事务锁防止并发重复登记。 同一许可证重复出现在多条消息、重复全量扫描、中途中断后重扫都不会重复扣减订单。后续扫描 会重新尝试匹配待处理记录,也可用系统卡片纠正旧的时间启发式匹配;明确订单、系统卡片及手动 匹配结果保持不变,跨账号重复许可证不会转移归属。进度保存在 当前进程内存中,重启后需重新扫描;已提交的许可证及匹配结果持久保存。任务也会出现在后台 任务列表中,导入与手动匹配保留不含凭据或消息正文的操作日志。
接口均限管理员:GET/POST /api/admin/afdian/message-license-import 查询进度或启动扫描,
GET .../pending 返回前 100 条待匹配许可证,POST .../match 接收 licenseId 和 orderId。
用户许可证可用性响应新增 historicalReviewRequired,表示需由管理员核对历史记录。
Flyway V60 允许许可证在尚未绑定 Sparkle 用户时保存,并新增导入来源、匹配状态和索引。
升级会短暂锁定 pbh_licenses 并扫描该表创建索引;许可证数量较多的部署应预留维护窗口。
不回填或重写历史交易,现有签发记录及凭据配置保持原有语义。
Flyway V67 将许可证的平台账号统一为 pbh_licenses.userid,由 provider 区分平台;
迁移保留通用账号值,缺失时使用旧爱发电账号补齐,随后移除重复的 afdian_user_id。
现有平台账号联合索引继续有效。升级需要短暂的表级排他锁,并可能扫描许可证表,
请预留维护窗口,停止旧版本实例后再升级,避免旧版本继续访问已更名的列。
仓库内的 flarum/extensions/sparkle-btn
提供 Flarum 2 + FoF OAuth 插件,以及 Sparkle 端的 GitHub UID 查询接口。插件会在
GitHub 登录和计划任务中缓存 BTN UID、7 日流量、Bytes 积分及两类排行榜,并按权限
在 Flarum 用户资料页和头像悬浮卡中展示;绑定用户同时自动加入专用权限组。
在 Sparkle 后台“Flarum 集成”页面保存集成密钥即可;配置会写入数据库敏感项并立即生效。
邮件发件人和显示名可通过以下配置修改:
sparkle:
version-alert:
from-address: "sparkle@pbh-btn.com"
from-name: "SparkleBTN 系统通知"统计任务默认每 60 分钟检查一次是否到期,统计窗口为最近 7 天。管理员可在
/admin/settings 调整开关、刷新间隔与窗口天数,并点击“立即刷新全部用户”触发一次后台重算。
页面会显示最近完成时间、耗时、更新用户数、触发方式、失败原因和数据是否过期。
关闭统计功能后会停止自动与手动刷新,同时隐藏顶部流量条和排行榜入口,排行榜 API 也会拒绝访问。
统计按 last_time_seen 而非 first_time_seen 判断窗口,避免漏掉最近仍活跃、但首次出现时间较早的
Peer。每次刷新只扫描一次 swarm_tracker,先将最近窗口按用户和 Peer IP 聚合到物化快照,
再从同一快照计算自主汇报与授权确认流量。心跳 IP 是单个 host 地址,因此使用等值连接让
PostgreSQL 选择 hash join,避免重复 CIDR 嵌套循环。
相关迁移已经纳入 Flyway,启动时会自动执行,不再需要手工运行 psql -f。首次为大型生产库
创建 hypertable 索引或连续聚合仍可能产生较多 I/O,建议在维护窗口部署。上线前建议
先在测试库使用 EXPLAIN (ANALYZE, BUFFERS) 检查 refreshUserSwarmStatistics 的执行计划与索引命中情况。
首页网络统计默认查询最近 7 天的封禁数据。Flyway V26 会创建 Peer ID、客户端和
GeoIP/IP 协议栈三个 TimescaleDB continuous aggregate,并启用列存压缩与每小时的增量刷新策略;
首页查询优先读取聚合结果,迁移尚未执行或聚合不可用时自动回退原始表。查询结果在 Redis 中缓存
5 分钟,并支持 1、7、14、30 天以及“仅封禁”与“封禁 + 种群”数据源切换。
三个首页聚合默认只保留最近 35 天,TimescaleDB retention policy 会自动删除更早的 chunks。
BTN 同伴 GeoIP 分布使用 userapps_heartbeat.geoip,统计最近 24 小时地址的心跳 IP 城市归属。
新增列完成后,历史地址会在下一次心跳上报时补全 GeoIP,活跃客户端通常会在数秒内恢复覆盖。
个人资料页的 BTN 生涯统计沿用独立隐私选项,默认仅自己可见。四项流量继续使用十进制字符串。 V61、V62 仅建立结构,不回填历史。统计由应用服务在种群、封禁和新特征写入的同一事务内更新, 不使用本功能的数据库触发器或存储函数。首次观测会话使用当前总量减本次增量建立基线,只计本次增量; 之后通过行锁和计数高水位处理重试、乱序下降。原始明细清理不删除去重检查点。 V63 建立心跳 IP 索引;仍会扫描心跳表,但不会扫描或回填种群、封禁明细。
本次按部署方确认“旧 V61 尚未成功完成”的状态更换了 V61/V62 内容。部署时先停止旧进程, 确认迁移事务已回滚,再启动新版。不要与旧版本同时写入。若某环境已经成功执行旧 V61/V62, 其 checksum 与新版不同,不能直接升级,也不要自动 repair 或手改历史记录;需要单独制定兼容迁移。
应用启动时会自动扫描 classpath 和工作目录中的 application.yaml、application.yml
及当前激活 profile 对应的 YAML 文件,将缺失的非数据源配置项写入 PostgreSQL 表
app_config_entries。已有数据库值不会被后续 YAML 扫描覆盖。
启动期配置加载顺序为:
- 命令行参数。
- 环境变量。
app_config_entries数据库值。- YAML 配置默认值。
数据源连接配置 spring.datasource.* 与数据库迁移配置 spring.flyway.* 永远不会迁移到
该表,避免后台配置绕过启动期结构升级。敏感项会迁移,但后台 API 只返回隐藏状态,不允许
读取或修改。普通配置修改在重启后生效;当前运行设置与流量统计开关
仍可在“运行设置”中立即应用。后台入口为 /admin/database-config,也可手动触发一次
YAML 扫描。旧版保存在 Redis sparkle:admin:runtime-config 中的热更新值会在首次数据库
迁移时自动兼容导入。
运行期批量读取非敏感业务配置时会优先使用 Redis 缓存,未命中再读取 app_config_entries
并回填缓存,缓存有效期为 5 分钟。数据库仍是配置事实源;配置写入提交后会失效对应缓存,
Redis 不可用时直接回退数据库。敏感配置不会写入这份缓存。
app_config_entries 表由 Flyway V23 创建。数据库账号只有 DML 权限时,需要数据库管理员
提前授予 schema DDL 权限,否则应用会按设计拒绝启动,避免运行在结构不完整的数据库上。
首次启用后台时,可由数据库管理员为已有账户授予角色:
UPDATE "user" SET role = 'admin' WHERE id = <user-id>;
UPDATE "user" SET role = 'moderator' WHERE id = <user-id>;隐私设置自 Flyway V46 起保存在独立的 user_privacy_settings 表,支持原始/模糊/隐藏头像、
完整/模糊用户名以及显示/隐藏积分。旧 privacy_level 列只用于迁移已有用户,不再参与新界面或公开资料计算。
用户菜单中“积分”下方的“提交记录”进入 /user/submissions。页面按封禁记录、发现的客户端、
种群检视分类,默认查询最近 3 天,也可切换最近 1 天或 7 天,时间范围为滚动的 24 小时倍数。
登录后可通过 GET /api/ui/submissions?type=bans&days=3&page=1&size=20 查询。
type 支持 bans、clients、swarm,默认 bans;days 仅支持 1、3、7,默认 3;
页码从 1 开始,每页默认 20 条,最大 100 条。响应沿用 records/current/size/total/pages。
接口始终根据登录身份限定应用所有者,不接受用户身份或来源应用作为授权依据。
记录包含来源应用,以及与封禁记录、种群检视页面对应的 Peer 地址和端口、客户端、进度、流量、
连接标记、封禁规则与描述、归属地、结构化详情和观测时间。编号和流量以十进制字符串传输,
不返回应用凭据。只有当前用户名下应用的记录可见。
查询先按当前用户查询应用 ID,再在各记录表内直接按应用 ID 和时间范围过滤。封禁记录使用
TimescaleDB 分区列 populate_time 筛选和排序,便于 chunk 裁剪;种群检视使用 last_time_seen,
可利用现有应用 ID 与时间的联合索引。没有应用时直接返回空分页,不扫描记录表。
此功能直接查询现有数据,不额外保存提交日志,也不改变原有保留策略:封禁记录按产生时间筛选; 发现的客户端仅包含名下应用首次发现的客户端,按首次发现时间筛选;种群检视按最后观测时间筛选, 显示当前保存的观测状态。已清理的记录和已删除应用的记录不会显示。无需新增数据库迁移。
V68 保留已部署的原始增量迁移和校验值,V69 接续执行删除,不需要 repair 或关闭校验。V69 移除首页 BitTorrent 流量承载及 PeerID/客户端流量排行,删除专用刷新任务、配置和 API。升级会永久删除十二张旧流量及共享增量统计表、旧城市流量连续聚合及其触发器函数(包括原始 Swarm 表上的三个增量触发器);历史 Flyway 文件保留校验,不再提供该模块。升级前停止旧实例,避免旧进程继续查询已移除的表;删除连续聚合和表时需要数据库锁,建议在维护窗口备份后升级。
首页按上报次数统计的 PeerID、客户端、城市和 IPv4/IPv6 分布继续保留,其连续聚合不删除,并恢复 V68 停用的每小时自动刷新策略。原始封禁、Swarm、用户最近七天流量、个人累计流量和生涯统计也保持原有用途。旧 Redis 流量缓存不再读取,可在维护时按原模块的精确缓存键清理。
封禁 Peer 的 IPv4/IPv6 分布按封禁发生时间(ban_history.populate_time)计算最近 1、3、7 天的去重 IP 数。升级后下一次刷新发布新口径的快照,空窗口显示为 0。
GitHub 的固定 redirect-uri 指向统一回调域名。其他域名会先跳到该域名发起授权,完成后通过 Redis 中两分钟有效、只能使用一次的凭据回到原域名,并校验发起浏览器的会话。所有入口必须连接同一 Redis 和 Spring Session 存储,反向代理必须正确保留外部协议和主机信息。跨域回跳不传递会话 ID。新用户会返回原域名继续注册。使用包含占位符的动态 redirect-uri 时保留原有流程。
设置 sparkle.web.allow-alternate-domains=false 可关闭非主域名页面访问(默认 true);主域名来自固定 GitHub redirect-uri,非主域名页面请求将跳转到主站,/ping/** 和 /api/** 保持可用。该设置可通过启动环境提供。
可关闭分类的站内信邮件提醒和客户端版本提醒会附带退订链接。页面无需登录,只列出可关闭的分类,用户勾选并确认后仅关闭所选分类的邮件通知,不改变站内信及其他分类。法律合规、账户安全、邮箱验证和账户删除确认邮件不提供退订。管理员强制邮件提醒仍遵循原有的强制投递规则。
链接使用 90 天有效的随机凭据,通过 Redis 保存摘要并绑定账户和收件邮箱;账户删除、邮箱变更、凭据过期或 Redis 数据清除后失效。凭据只允许关闭邮件提醒,打开页面不会自动退订。链接地址使用现有主站地址设置(BTN 配置的 rootUrls/rootUrl),部署时应确保其为可访问的 HTTPS 地址。
公开页面为 /mail-unsubscribe;GET /api/ui/mail-unsubscribe 返回可退订分类及邮件开关状态,POST 同路径接收 categories 字符串数组。两者均要求 X-Unsubscribe-Token 请求头;POST 保留 SPA CSRF 校验。凭据通过邮件链接的 fragment 传递,避免进入 HTTP URL 和访问日志。
退订接口不返回账号身份资料,也不能开启任何通知;重复确认同一分类不会影响其他偏好。已关闭邮件的分类在退订页中不可重复勾选,仍可登录账户设置重新开启。
V62 复用 V61 累计流量,增加贡献事件、UTC 按日汇总和每种子活动区间;新统计只处理升级后的提交。 近七天指 UTC 今天及前六天。Peer 按会话去重;其它用户观测按不同会话观测时间或封禁事件计数, 共用 IP 的多个应用不重复计算。时长按同一种子连续采样累计,失联间隔按后台种群汇报间隔与随机浮动范围之和限制,历史时长不推算。 GET /api/ui/user/career/{uid} 沿用生涯统计隐私选项,最近观测者昵称使用公开资料隐私及审核策略。 应用归档、积分流水各有不同业务维度,保留原用途;新统计与 V61 共享同一流量累计来源。 用户注销会清理相关统计和检查点。
生涯统计快照缓存于 Redis,TTL 为五分钟;键包含 UTC 日期,避免沿用上一日的七天统计窗口。 隐私权限和观测者昵称不缓存,每次返回前重新应用当前隐私策略。界面统计最多延迟五分钟。 相同统计提交批次使用五分钟 Redis 去重标记,标记仅在数据库事务提交后发布;回滚不发布标记。 Redis 丢失或不可用时回退数据库,数据库仍负责最终去重与累计准确性。 种群、封禁、新特征统计按每批最多 500 条执行一条 SQL,批量计算事件、日计数与 IP 归属; 种群统计同一语句还原子更新检查点、流量及每种子活动采样。V65 的两个增量列用于原子返回本批次增量, 避免每个 Peer 先查询检查点再更新。时长查询只扫描一次用户种子活动表。 V64 删除本功能表的外键和 CHECK,保留 ON CONFLICT 所必需的主键/唯一索引。 不新增存储过程或触发器,不回填历史,也不修改已执行迁移。
统计采样窗口统一从 BtnRuntimeConfigService 读取:种子活动与 IP 查询并发种子窗口采用 syncSwarm.interval + syncSwarm.randomInitialDelay;确认流量和其它用户观测的心跳匹配窗口采用 heartbeat.interval + heartbeat.randomInitialDelay。后台调整后跟随运行配置缓存刷新生效;已累计历史不重算。缓存 TTL 和近七天统计周期不属于客户端汇报间隔。
管理员可在会员管理页对已签发许可证执行“吊销许可证”,或粘贴完整密钥吊销不在列表中的独立许可证。 必须填写原因并确认;吊销记录永久保存字段摘要、原因、操作时间和管理员 UID,不保存独立许可证明文。 独立许可证必须可由官方公钥或当前配置的签发密钥验证。重复吊销保留首次吊销记录,不提供撤销操作。
POST /api/admin/memberships/license-revocations:接收licenseId或licenseKey(二选一),以及reason(最多 500 字符)。仅管理员可用,保留 SPA CSRF 校验。GET /api/admin/memberships/license-revocations?page=1&size=20:分页查询吊销记录,最大每页 100 条。GET /peerbanhelper/v1/licenses/checkRevoke:匿名客户端查询,直接返回{"revoked":true}或{"revoked":false},没有响应包装。
客户端按原始 UTF-8 字段计算小写 SHA-256,参数为 licenseTo、description、orderId、
paymentOrderId、paymentGateway、sku、source、type;null 字段省略,空字符串仍参与校验。
服务端精确匹配完整字段摘要集合,兼容 V1 的默认 type=afdian 和 V1 不提供的订单字段。
没有匹配吊销记录时始终返回未吊销,包括不在签发列表中的许可证;缺失授权对象或摘要格式不合法时也返回未吊销。
协议不包含密钥本身、签发时间和隐藏字段,因此具有相同校验字段的多份许可证无法单独区分,会一并失效。
PeerBanHelper 将检查结果缓存 24 小时,并周期检查;吊销不会立即推送到客户端。部署须确保
api.pbh-btn.com 上述固定路径转发到本应用,不能要求登录,也不能重写为 SPA 页面。
Flyway V66 新建独立吊销表,不修改签发记录结构、不回填历史吊销状态,不扫描已有大表,通常无需维护窗口。
现有许可证的吊销状态和新增吊销记录在同一事务内写入;独立许可证不消耗签发名额、不新增签发记录。
后台停用用户或用户应用时,必须填写停用理由,可选择预设后再编辑。自动恢复时间可留空, 留空时由管理员手动恢复。填写时间后,到期的新请求按已恢复处理。管理员可以调整仍在生效的停用, 也可以提前恢复。
V81 为用户和用户应用追加可空的 unban_at 列,不回填历史,已有停用仍需手动恢复。
管理端停用接口接收 unbanAt(带时区的 ISO 8601 时间或 null),理由去除首尾空白后最多
500 字符。用户接口传 banned: false 恢复;应用接口同样支持 banned: false,省略该字段仍
表示停用。更新应用基本信息时省略 banned 会保留当前停用设置。
管理员可以在「后台管理 → 重复封禁」按应用、事件类型、状态和最近出现时间查询。目标按应用、规范化 IP、端口、
种子、模块和规则区分。页面显示 IPv4 /24 或 IPv6 /64 网段、端口、模块、规则和计数。「清空记录」会删除
全部事件并重置相关目标的检测状态,保留精确去重指纹和封禁历史。
上方的应用重传排行独立于明细筛选,汇总当天及之前 29 个 UTC 日的数据。一次上报只要发现重传就计一次,
批内每条重传日志单独累计。先按捕捉到重传次数倒序,再按重传日志数量倒序,显示前 100 个应用。
后台接口 GET /api/admin/ban-submissions/ranking 返回 appId、replayBatches 和 replays。
V79 新增按应用和 UTC 日期汇总的表,从升级后开始统计,不回填历史。清空记录时同时清空排行。
通过现有上报校验的封禁日志按目标和 UTC 封禁时间去重。过滤发生在种子登记、地理信息查询、封禁入库及其积分、 生涯和流量累计之前。被过滤的上报仍返回成功。同一批中的多条新日志最多计入一个窗口,计入后续窗口需要服务器 接收时间和客户端封禁时间均推进至少一个 BTN 封禁上报间隔。
持续重复封禁默认以 5 个窗口为阈值,先记录供管理员观察。可在「后台管理 → BTN 配置 → 封禁历史上报」 调整阈值并启用拦截。启用后拦截达到阈值的近期新日志。超过 1 小时或 3 个上报间隔(取较长值)没有新的合格窗口时, 下一轮从头计数。旧批次补报仍按事件指纹去重。
V74 创建独立检测表及索引,V75 初始化默认配置。现有 ban_history 无结构变更,也不扫描或回填历史。升级前已入库的旧日志
如果仍在七天接收范围内,升级后首次重传可能再写入一次。清理任务按日丢弃完整过期指纹块。普通目标状态在静默期
后清理,事件摘要按最近一次上报保留 30 天。部署前按新上报峰值评估指纹、目标状态、WAL 和备库容量。
导航栏用户下拉菜单及移动端菜单的“流量统计”进入 /user/traffic。
GET /api/ui/user/traffic?page=1&size=20 仅返回当前登录用户的数据,按 UTC 日期倒序分页,
返回 records/current/size/total/pages;每页最多 100 条,不限制历史查询时长。
没有汇报且没有采样活动的日期不创建记录。字节数、秒数和百分比以十进制字符串返回。
V70 新建 user_traffic_daily,每个用户每天一行,只保存四项流量、两项活动秒数、封禁损失及损失百分比的最终结果。
写入与业务汇报同事务提交,复用现有会话检查点和封禁事件去重,不新增后台扫描任务。
种群流量使用非负增量,封禁流量在封禁记录首次计入时累计;确认流量按现有心跳连接匹配方向反转。
两种来源分别去重,不代表逐笔核验双方数据,也不承诺识别两种来源中同一传输的重叠。
活动时间按种子采样,与生涯统计共用时段;跨 UTC 午夜拆分到各日,失联间隔仍受当前汇报窗口限制。
损失为封禁记录已上传量,占比为损失除以同日汇报上传总量乘以 100,分母为零时为 0。
当天结果随新汇报更新;迟到汇报仍按事件日期入账,不额外保留原始明细或检查点到本表。
V70 只建新表,不回填历史,也不扫描或锁定现有业务大表,通常无需维护窗口。
导航栏蓝条使用相同的每日记录,汇总含当天在内的最近 7 个 UTC 自然日。
首页 BitTorrent 流量承载通过 GET /api/ui/user/traffic/network 汇总最近 30 个 UTC 自然日内「我的流量统计」使用的同一批每日记录。没有记录的日期不生成数据点。接口按请求者当前角色只返回有权查看的指标,五张图均不可见时返回 403。
后台“运行设置”可切换首页 BitTorrent 流量承载,保存后重新加载首页即可看到变化。V72 为 sparkle.homepage.network-traffic-enabled 写入启用默认值,保留已有设置,通常无需维护窗口。
后台“运行设置”可分别配置汇报流量、确认流量、活动时长、日均拦截损失、总计拦截损失的可见范围,选择所有登录用户或仅管理员和协管。前四张图分别使用 sparkle.homepage.reported-staff-only、sparkle.homepage.confirmed-staff-only、sparkle.homepage.activity-staff-only 和 sparkle.homepage.average-loss-staff-only,未单独配置时继承原有的 sparkle.homepage.network-traffic-staff-only。总计拦截损失沿用 sparkle.homepage.total-loss-staff-only。
首页支持 30、14 和 7 天范围。汇报流量、确认流量、活动时长和总计拦截损失按 UTC 日求和,再在所选范围内逐日累计。日均拦截损失按 UTC 日分别对个人损失流量和损失比例排序,每项剔除最高和最低各 1% 的样本后计算平均值。每端剔除条数向下取整,当天不足 100 条时使用全部样本。
V71 创建日期索引以支持该查询。索引构建期间每日流量表可读取,写入会等待。如果表中已有大量记录,请在维护窗口升级。
V80 新增按 UTC 日分割的种群 IP 标志统计。种群记录按最后观测时间归属,历史初始化对每个 UTC 日 只读取当天零点(含)至次日零点(不含)的记录。同一 IP 当天的总数和每个观测到的标志各计一次。 同一 IP 可出现在多个指标中。无标志的记录只计入 IP 总数。 有标志的观测未标出 DHT、PeX 或 LSD 时计入「Tracker 或其他来源」,未标出 uTP 时计入「推定 TCP」。
后台「首页数据刷新」可热切换「种群 IP 标志统计」并设置刷新间隔,默认开启、每分钟刷新。
关闭时暂停采集和定时发布,隐藏首页图表,已生成的统计保留。重新开启后继续累计,关闭期间的上报不回填。
任务可在「任务状态与计划」中查看,开启时支持手动刷新。
上报事务按批合并日内去重状态,后台分批发布新增计数,并在确认发布后清理 14 天前的去重分区。
每日结果表只保存日期、指标和 IP 数,清理去重分区不会删除已发布结果。
登录后的 GET /api/ui/home/ip-flags?from=YYYY-MM-DD&to=YYYY-MM-DD 仅查询每日结果,
支持首尾均包含的最多 90 个 UTC 日期。V80 会在升级时按日读取一次现存种群记录并写入结果。
已被覆盖或清理的观测无法从现存记录恢复。初始化时间取决于种群表大小,建议在维护窗口停止旧实例后升级。
依赖 PostgreSQL 18 的写入前后值返回语法。升级前应完成备份及专用 TimescaleDB 测试库验证。
删除账户时同步清除此表的数据;原始明细清理不影响已累计的每日结果。
升级到 V77 会创建独立的词库设置表,默认关闭。管理员可在「记录内容审核」粘贴词库、
切换开关并保存。每行一个词,空白行和以 # 开头的行会被忽略。匹配区分大小写,
使用精确子串,词库文本最多 100 万个 UTF-16 代码单元。开启时至少需要一个有效词条。
保存实例在数据库提交后应用新版,其他实例约每 15 秒检查一次版本。后台显示数据库 版本和当前实例生效版本。BTN Ping 每个批次使用同一份内存词库,跳过命中的 Swarm 或封禁记录,其余记录照常处理。审核字段包括 Swarm 上报的下载器名和客户端名, 以及封禁上报的客户端名、模块、规则、说明和结构化 JSON 中的文本键和值。
GitHub 昵称在注册和登录同步时审核,命中后昵称不公开,用户仍可登录。IP 查询评论 在新建和编辑时审核,待审及重新送审的评论在提交 AI 前再次检查。启用和更新词库 不会批量回扫历史数据。关闭开关后停止新的词库检查,已有审核结果不会自动更改。
V78 补齐 BTN IP 查询的六个数据库配置默认值。已有配置保留,默认行为与 YAML 一致。