pt-tools

!Example

🤖 ChatOps & 机器人（v0.31+）

pt-tools 现支持通过 QQ 或 Telegram 机器人远程管理：

• 🇨🇳 QQ OneBot via NapCat（reverse-WebSocket，私聊命令，已端到端验证）
• 🌍 Telegram Bot via BotFather（long-poll，私聊命令，支持代理，已端到端验证）
• 🛠️ 内置 13 个命令：/help /status /version /tasks /sites /torrents /pause /resume /delete /bind /unbind /addrss /delrss
• 📥 互动管理 RSS：/addrss 文本向导或单行快捷格式添加订阅，/delrss 先列出后按名称/ID/序号删除（均限管理员）
• 📡 RSS 上新通知：QQ/Telegram 推送站点新种，支持全量/规则匹配双模式 + 静默时段 + digest 合并
• 🔐 安全：管理员白名单、绑定码 TTL（5min/1h/1d/30d/永久）、AES-GCM 加密落库、HMAC 签名 webhook、操作审计日志

实验性出站通道（暂未端到端验证）：企业微信群机器人 / 自定义 Webhook（HMAC-SHA256）— 代码已实现，欢迎贡献测试反馈。

详见：

• 快速开始 → ChatOps
• QQ OneBot (NapCat) 配置
• Telegram Bot 配置
• RSS 上新通知

功能特性

| 功能 | 描述 | | -------------------- | ------------------------------------------------------------------ | | RSS 自动订阅 | 自动解析 RSS 订阅，智能识别免费种子并自动下载推送 | | 多站点种子搜索 | 跨站点搜索，支持批量下载和批量推送到下载器,或者下载种子文件到本地 | | 用户信息统计 | 聚合展示所有站点的上传量、下载量、分享率、魔力值、等级进度等 | | 数据截图分享 | 一键生成用户数据卡片截图，支持导出分享到社交平台 | | 下载器管理 | 支持多个下载器实例，可配置不同的下载目录和启动策略 | | 过滤规则 | 对 RSS 订阅进行精细化筛选，支持关键词/通配符/正则表达式 | | 免费结束自动暂停 | 监控种子免费状态，免费期结束时自动暂停未完成的下载任务 | | 免费结束自动删除 | 可选开启，免费期结束时自动删除未完成的种子及数据，无需手动操作 | | 自动删种 | 按做种时间/分享率/不活跃时间自动清理种子，支持 H&R 保护和磁盘保底 | | 登录态保号 | 周期探测站点活跃时间，剩余天数不足时循环提醒，Web/扩展一键刷新登录 | | 代理支持 | 支持 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY 环境变量代理 | | 版本更新检查 | 自动检测新版本，支持代理设置，在 Web 界面展示更新日志 | | 一键自动升级 | 二进制部署支持 Web 界面一键升级，自动下载替换，无需手动操作 | | Web 管理界面 | Web UI 管理后台，方便配置和监控 |

[!WARNING]

关于 RSS 订阅与过滤规则：在未启用任何过滤规则的情况下，RSS 订阅默认只会下载免费种子。如果您只是刷流，无需设置过滤规则，直接添加 RSS 订阅即可。只有在需要追剧或下载特定资源（即便种子非免费也要下载）时，才需要创建过滤规则并关闭规则中的「仅免费」开关。

数据截图分享

在用户信息页面，支持将站点数据生成精美的卡片截图，方便分享到社交平台或群组。

功能特点：

• 一键截图：点击按钮即可生成当前数据的截图
• 卡片样式：精心设计的卡片布局，展示上传量、下载量、分享率等关键数据
• 隐私保护：自动隐藏敏感信息（如用户名、站点地址等）
• 导出保存：支持导出为 PNG 图片保存到本地

免费结束自动暂停

针对 PT 站点免费种子的智能管理功能，帮助用户在免费期结束前避免产生不必要的下载量消耗。

工作原理：

1. RSS 订阅下载免费种子时，系统自动记录种子的免费结束时间
2. 为每个种子创建独立定时器，在免费结束时刻精确触发检查
3. 免费期结束时，自动检测下载进度，暂停未完成的任务
4. 已完成的种子不受影响，继续正常做种

• 精确定时：独立定时器 + 周期检查双重机制，支持应用重启后自动恢复监控
• 智能判断：仅暂停未完成任务，已完成任务继续做种
• 手动恢复：支持在 Web 界面手动恢复暂停的任务（不再受免费限制）
• 批量管理：支持批量删除暂停任务，可选是否同时删除数据文件
• 历史归档：查看历史暂停记录和处理结果
• 自动删除：可在系统设置中开启「免费结束自动删除」，免费期结束时自动删除未完成的种子及数据文件，无需手动操作

[!TIP]

默认行为为暂停，如需自动删除，请在「系统设置 → 免费结束管理」中开启「免费结束自动删除」开关。此功能默认关闭，需用户手动开启并保存。

一键自动升级

针对二进制部署用户的便捷升级功能，无需手动下载替换文件，在 Web 界面即可完成版本升级。

支持环境：

| 部署方式 | 支持情况 | 说明 | | ----------- | --------------- | -------------------------------------------------- | | 二进制部署 | ✅ 完全支持 | 自动下载、解压、替换二进制文件 | | Docker 部署 | ⚠️ 需第三方工具 | 推荐使用 Watchtower 自动更新，或手动 docker pull |

升级流程：

1. 在 Web 界面右上角点击版本号，查看可用更新
2. 选择目标版本，点击「升级」按钮
3. 系统自动下载对应平台的安装包并替换当前程序
4. 升级完成后，手动重启服务即可使用新版本

# 拉取最新镜像
docker pull sunerpy/pt-tools:latest
重启容器
docker restart pt-tools

或使用 Docker Compose：

docker compose pull
docker compose up -d

自动更新方案：推荐使用 Watchtower 实现 Docker 容器自动更新：

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup \
  pt-tools

Watchtower 会自动检测并更新 pt-tools 容器到最新版本。

支持站点

已适配站点列表

扩展站点支持：如需支持其他站点，欢迎提交 Issue 或 Pull Request。

快速开始

Docker 部署（推荐）

镜像地址：Docker Hub

docker run -d \
  --name pt-tools \
  -p 8080:8080 \
  -v ~/pt-data:/app/.pt-tools \
  -e PT_HOST=0.0.0.0 \
  -e PT_PORT=8080 \
  -e TZ=Asia/Shanghai \
  sunerpy/pt-tools:latest

Docker Compose（推荐）

services:
  pt-tools:
    image: sunerpy/pt-tools:latest
    container_name: pt-tools
    environment:
      PT_HOST: "0.0.0.0"
      PT_PORT: "8080"
      TZ: "Asia/Shanghai"
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/.pt-tools
    restart: unless-stopped
    # 限制容器日志大小，避免长期运行膨胀到数 GB（见下方「Docker 用户注意」）
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

如需通过代理访问站点，可设置环境变量：HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY。

详细说明见 docs/configuration.md。

启动后访问 http://localhost:8080 进入 Web 管理界面。

默认登录账号：admin / adminadmin

更多部署示例请参考：

> - examples/docker-run.md - Docker 单容器运行详解

- examples/docker-compose.yml - Docker Compose 编排

- examples/binary-run.md - 二进制运行和 systemd 配置

⚙️ Docker 用户注意（日志膨胀）

容器日志（docker logs）默认由 Docker 的 json-file 驱动管理，默认没有大小限制，长期运行可能增长到数 GB。pt-tools 自身的日志文件（~/.pt-tools/logs/）已自动滚动切割，但容器 stdout 日志需由 Docker 侧限制。建议开启日志轮转：

• Docker Compose（推荐，所有平台通用）：在服务下添加 logging 块（见上方示例）

logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "3"

• docker run：追加参数

--log-opt max-size=10m --log-opt max-file=3

• 飞牛 NAS（fnOS）/ 群晖 DSM Container Manager / Unraid / Portainer：

# 找到容器日志文件并清空（不会影响容器运行）
     truncate -s 0 $(docker inspect --format='{{.LogPath}}' pt-tools)

或停止并重建容器（docker rm 后重新创建，数据已持久化）。

• Linux 全局默认（影响此后新建的所有容器）：编辑 /etc/docker/daemon.json

{
    "log-driver": "json-file",
    "log-opts": { "max-size": "10m", "max-file": "3" }
  }

然后 sudo systemctl restart docker。⚠️ 仅对重新创建的容器生效，已有容器需重建。

完整日志说明（应用日志滚动、环境变量 PT_TOOLS_LOG_LEVEL / PT_TOOLS_LOG_CONSOLE）见 docs/configuration.md。

二进制运行

前往 Releases 页面 下载预编译二进制文件。

Linux：

wget https://github.com/sunerpy/pt-tools/releases/latest/download/pt-tools-linux-amd64.tar.gz
tar -xzf pt-tools-linux-amd64.tar.gz
chmod +x pt-tools
./pt-tools web --host 0.0.0.0 --port 8080

Windows (PowerShell)：

# 一键下载、解压并运行（复制整段命令到 PowerShell 执行）
Invoke-WebRequest -Uri "https://github.com/sunerpy/pt-tools/releases/latest/download/pt-tools-windows-amd64.exe.zip" -OutFile "pt-tools.zip"; Expand-Archive -Path "pt-tools.zip" -DestinationPath "." -Force; .\pt-tools.exe web --host 0.0.0.0 --port 8080

或分步执行：

# 下载并解压
Invoke-WebRequest -Uri "https://github.com/sunerpy/pt-tools/releases/latest/download/pt-tools-windows-amd64.exe.zip" -OutFile "pt-tools.zip"
Expand-Archive -Path "pt-tools.zip" -DestinationPath "."
运行
.\pt-tools.exe web --host 0.0.0.0 --port 8080

注意：这是一个命令行工具，双击 exe 文件会提示需要在命令行中运行。请使用上述 PowerShell 命令启动服务。

| 系统 | 架构 | 文件名 | | ------- | ----- | -------------------------------- | | Linux | amd64 | pt-tools-linux-amd64.tar.gz | | Linux | arm64 | pt-tools-linux-arm64.tar.gz | | Windows | amd64 | pt-tools-windows-amd64.exe.zip | | Windows | arm64 | pt-tools-windows-arm64.exe.zip |

使用指南

初次配置流程

1. 启动服务：使用 Docker 或二进制启动 pt-tools
2. 登录管理界面：访问 http://localhost:8080，使用默认账号 admin / adminadmin 登录
3. 修改密码：首次登录后建议修改默认密码
4. 配置下载器：添加 qBittorrent 或 Transmission
5. 配置站点认证（二选一）：

1. 配置 RSS 订阅：添加 RSS 订阅实现自动下载
2. 配置过滤规则（可选）：创建过滤规则实现精准下载

浏览器扩展

PT Tools Helper 是 pt-tools 的配套浏览器扩展，支持 Chrome 和 Edge。

| 功能 | 说明 | | -------------------- | ------------------------------------------------------------- | | Cookie 自动同步 | 在 PT 站点登录后，一键将 Cookie 同步到 pt-tools，无需手动复制 | | 批量同步 | 在扩展设置中勾选多个站点，一键批量同步所有 Cookie | | 一键采集站点数据 | 自动抓取种子列表页、详情页、用户信息页，用于请求适配新站点 | | 自动脱敏 | 采集的页面数据自动移除 Passkey、邮箱、IP 等敏感信息 | | 导出 & 提交 | 将采集数据导出为 ZIP，或一键创建 GitHub Issue 请求新站点支持 | | 中英文支持 | 自动跟随浏览器语言切换中文/英文界面 |

安装方式

Edge Add-ons 扩展商店（推荐）：

• 前往 Edge 扩展商店 搜索 "PT Tools Helper" 直接安装，支持自动更新

1. 前往 Releases 下载最新的 pt-tools-helper.zip
2. 解压到任意目录
3. Chrome → chrome://extensions / Edge → edge://extensions
4. 开启「开发者模式」→「加载已解压的扩展程序」→ 选择解压目录

详细使用说明见 扩展 README。

文档

| 文档 | 说明 | | -------------------------------------------------------------- | -------------------------------------------- | | ChatOps 快速开始 | 机器人功能概览、通道选择与命令清单 | | QQ OneBot (NapCat) 配置 | NapCat Docker 部署、反向 WS 配置、绑定测试 | | Telegram Bot 配置 | BotFather 创建 bot、代理配置、绑定测试 | | RSS 上新通知 | RSS 新种实时推送：双模式、静默、digest、按钮 | | 获取 Cookie / API Key | 详细介绍如何从各站点获取认证信息 | | 浏览器扩展使用指南 | 自动同步 Cookie、采集站点数据 | | RSS 订阅配置指南 | 如何配置 RSS 订阅实现自动下载 | | 过滤规则与追剧指南 | 使用过滤规则自动追剧、筛选资源 | | 自动删种指南 | 自动清理种子策略配置和 H&R 保护 | | 请求新增站点支持 | 无需编程经验，提供页面数据即可请求适配 | | 配置说明 | 环境变量、全局设置、下载器配置详解 | | 常见问题 (FAQ) | 常见问题和解决方案 | | 开发指南 | 从源码构建、技术架构、贡献指南 |

站点登录管理（防封号）

通过浏览器扩展 pt-tools-helper 一次性同步站点 cookie，后端定期探测各站点的权威 last_access / last_login 字段，预警即将触发封号判定的站点，并在阈值期内通过已配置的通知通道循环提醒，直到用户主动刷新登录。

重要：AES 密钥备份（必读）

~/.pt-tools/secret.key 保存着用于 AES-256-GCM 加密所有站点 cookie 的密钥。一旦密钥丢失，已存储的 cookie 将无法解密，必须重新粘贴所有站点的 cookie。

备份密钥：

pt-tools secret export > ~/secret.key.backup && chmod 600 ~/secret.key.backup

从备份恢复密钥：

pt-tools secret import --force < ~/secret.key.backup

[!WARNING]

强烈建议将备份保存到 pt-tools 数据目录之外的安全位置，如密码管理器、加密 USB 等。备份文件本身具有与原始密钥等同的访问权限，请勿明文存放在云盘或代码仓库中。

Docker 部署须知

Docker 容器重建后，容器内的文件系统会重置。必须将 ~/.pt-tools/ 目录（含 secret.key、数据库和备份文件）挂载为持久化 volume，否则每次重建容器都会丢失密钥，已加密的 cookie 将无法使用，需要使用扩展重新同步推送。

[!WARNING]

千万不要误删 ./pt-tools-data 目录。删除该目录等同于同时丢失密钥和数据库，所有已同步的 cookie 将不可恢复。

使用步骤

1. 在 pt-tools 站点管理页面启用目标站点
2. 安装 pt-tools-helper 浏览器扩展，在浏览器中登录各 PT 站点
3. 在扩展 popup 中点击"批量同步 cookie"；可选同时打开站点标签页，用于记录真实访问时间
4. 在 pt-tools 前端 /sites/login 页面查看各站点的剩余天数，并可自定义阈值、cron 表达式和通知通道
5. 当距封禁期限不足设定天数时，系统按 cron（默认 0 10,22 *）通过已配置的通知通道循环提醒，直到 cookie 刷新

每站点配置项

| 配置项 | 默认值 | 说明 | | ------------------------ | --------------- | --------------------------------------------- | | BanThresholdDays | 30 | 站点封号判定天数（不活跃超过此天数将被封号） | | RemindBeforeDays | 10 | 在封号前多少天开始提醒 | | ReminderCron | 0 10,22 * | 提醒发送的 cron 表达式（每天 10:00 和 22:00） | | NotificationChannelIDs | 空 | 用于发送提醒的通知通道 ID 列表 |

合规免责声明

本功能通过用户自身已登录的 cookie / API key，周期性请求站点用户页面或 profile API，以获取最后访问时间。

请在使用前自行评估风险：

• 部分 PT 站点的服务条款（TOS）可能将频繁的脚本化访问视为违规行为
• 默认探测频率为每 6 小时一次（带随机抖动），属于轻量请求，但仍可能被站点管理员注意
• 用户应基于个人风险偏好决定是否启用本功能

贡献

欢迎贡献代码或提交问题！

• 提交 Issue：GitHub Issues
• 提交 PR：GitHub Pull Requests
• 交流群：Telegram

更新日志

查看 Releases 获取完整更新日志。

每个版本的新功能、修复与升级说明，请以 Releases 与 CHANGELOG 为准。本 README 仅介绍核心功能，不再逐版罗列变更详情。

许可证

MIT License

Star History

如果这个项目对你有帮助，请给一个 Star 支持一下！

交流分享

Telegram

QQ群: 274984594

---

免责声明：本工具仅供学习和研究使用，请遵守各 PT 站点的规则，合理使用。