pt-tools

pt-tools

pt-tools 是一个功能强大的 PT（Private Tracker）站点自动化管理工具，提供 RSS 订阅自动下载、多站点种子搜索、用户信息统计、下载器管理等功能，帮助用户高效管理多个 PT 站点。

🤖 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 上新通知

功能特性

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

数据截图分享

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

功能特点：

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

免费结束自动暂停

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

工作原理：

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

功能特点：

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

启用方式：在添加或编辑 RSS 订阅时，开启「免费结束时暂停」开关即可。

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

一键自动升级

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

支持环境：

升级流程：

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

Docker 用户升级方式：

# 拉取最新镜像
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：

  图形界面创建的容器，多数版本未开放日志驱动配置。两种处理方式：

  1. 长期方案（推荐）：改用 Docker Compose 部署并按上方配置 logging（GUI 已创建的可 SSH 到 NAS 改用 Compose 重建容器，数据目录已持久化不会丢失）。

  2. 即时补救：手动清理已堆积的容器日志 —— SSH 登录后截断对应日志文件：

     # 找到容器日志文件并清空（不会影响容器运行）
     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 命令启动服务。

使用指南

初次配置流程

1. 启动服务：使用 Docker 或二进制启动 pt-tools
2. 登录管理界面：访问 http://localhost:8080，使用默认账号 admin / adminadmin 登录
3. 修改密码：首次登录后建议修改默认密码
4. 配置下载器：添加 qBittorrent 或 Transmission
5. 配置站点认证（二选一）：
   • 推荐：安装 PT Tools Helper 浏览器扩展，在 PT 站点登录后一键同步 Cookie
   • 手动方式：参考 获取 Cookie / API Key 手动复制粘贴
6. 配置 RSS 订阅：添加 RSS 订阅实现自动下载
7. 配置过滤规则（可选）：创建过滤规则实现精准下载

浏览器扩展

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

安装方式

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

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

从 GitHub Release 手动安装：

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

直接安装签名版 .crx：从 Releases 下载 pt-tools-helper.crx，拖入 chrome://extensions/（需开启「开发者模式」）。注意 Chrome 现在默认禁止 .crx 直接安装，浏览器可能会提示已停用；如不可用，请改用上面的 zip + 加载已解压扩展程序方式。

详细使用说明见 扩展 README。

文档

站点登录管理（防封号）

通过浏览器扩展 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 刷新

每站点配置项

合规免责声明

本功能通过用户自身已登录的 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 站点的规则，合理使用。