Skip to content
PBH-BTNPublic

About

The sparkle3

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

Sparkle 3

页脚支持按钮

后台“运行设置 → 页脚 → 支持按钮”可添加、删除和排序最多 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 自动路由

后台“BTN 管理 → 服务根地址”可调整主根地址、优化根地址、自动路由开关及运营商/省份关键词。 默认保留原规则:运营商包含“移动”,或省份包含福建、江苏、浙江、四川、重庆、河南、湖北时选择优化根地址。 关键词使用包含匹配(区分大小写),以英文逗号或换行分隔;清空列表会停用对应条件。任一条件命中即可, 未命中或 IP 地理资料缺失时使用主根地址。关闭自动路由后默认使用主根地址。 客户端的 forceRoute=chinamainland/global 继续优先选择对应地址,不受自动路由开关影响。

配置键为 sparkle.auto-route-enabled、sparkle.chn-route-isps、sparkle.chn-route-provinces, 使用现有数据库配置,无需新增迁移;后台保存后热更新,其他实例在约一秒内刷新。 命令行和环境变量覆盖继续优先于后台保存的值。

BTN IP 查询与评论

客户端配置的 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。

升级顺序如下:

  1. 备份数据库,确认 timescaledb 扩展可用。
  2. 先部署一次新版本。Flyway 会在 PostgreSQL advisory lock 保护下自动建立/更新 flyway_schema_history,无需手工执行 SQL。
  3. 查看启动日志。已有库接管会记录 Adopting existing Sparkle3 schema into Flyway at legacy version ...;之后的增量迁移由 Flyway 正常记录。
  4. 后续 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 继续用于活跃应用每日领取。

捐赠支持与 PBHLicense

爱发电、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 用户可以认领多个订单(Flyway V59 仅对 面包多放宽了“每个平台只能绑定一个账号”的唯一约束)。
  • 链动小铺:没有公开的订单或销售 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 2 集成

仓库内的 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 系统通知"

最近 7 日流量统计

统计任务默认每 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 扫描覆盖。

启动期配置加载顺序为:

  1. 命令行参数。
  2. 环境变量。
  3. app_config_entries 数据库值。
  4. 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。

OAuth 多域名登录

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 和访问日志。

退订接口不返回账号身份资料,也不能开启任何通知;重复确认同一分类不会影响其他偏好。已关闭邮件的分类在退订页中不可重复勾选,仍可登录账户设置重新开启。

BTN 生涯统计

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 和近七天统计周期不属于客户端汇报间隔。

PBH Plus 许可证吊销

管理员可在会员管理页对已签发许可证执行“吊销许可证”,或粘贴完整密钥吊销不在列表中的独立许可证。 必须填写原因并确认;吊销记录永久保存字段摘要、原因、操作时间和管理员 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 会保留当前停用设置。

BTN 重复封禁

管理员可以在「后台管理 → 重复封禁」按应用、事件类型、状态和最近出现时间查询。目标按应用、规范化 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 创建日期索引以支持该查询。索引构建期间每日流量表可读取,写入会等待。如果表中已有大量记录,请在维护窗口升级。

首页 IP 标志统计

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 一致。

About

The sparkle3

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages