pt-tools

command module
v1.0.0-rc.34 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 1 Imported by: 0

README

pt-tools

pt-tools

PT 站点自动化:RSS 下载、签到、保号、刷流与数据统计

CI Release Docker Pulls Codecov License

文档站 · 功能 · 安装 · 快速开始 · 用法 · 文档 · 开发

简体中文 · English


按 RSS 订阅自动下载免费种子,每天签到、在封号前提醒保号,按规则刷流,汇总各站点的数据并发每日战报,统一管理 qBittorrent 和 Transmission,并可以在 QQ 和 Telegram 里查看和控制。内置 66 个站点,支持 Docker、Linux 和 Windows。完整文档在 firlab.app/pt-tools。

站点列表与手机界面

功能

  • 站点与数据:66 个内置站点,覆盖 NexusPHP、mTorrent、Gazelle、HDDolby 和 Rousi 等架构,支持 Cookie、API Key 和 Passkey。在一个页面查看所有站点的上传量、分享率、做种、积分和等级进度;跨站点搜索的结果可以直接推送到下载器;长期未登录导致封号之前会提醒(保号),可以按站点开启每日签到。每天存一份数据快照,按日、周、月看增量,并可以把当天的增量发成每日战报,见数据统计与每日战报。
  • RSS 自动下载:定时拉取订阅,用关键词、通配符或正则过滤标题来追剧;免费期结束时尚未下载完成的种子自动暂停。
  • 刷流:从站点的免费列表里按优惠、体积、做种与下载人数挑新种,按做种时长、分享率、上传速度删除,限定同时下载数与体积;收益按天统计并进每日战报。见刷流任务。
  • 下载器:可以添加多个 qBittorrent 和 Transmission,按 RSS 订阅、站点、默认下载器的顺序决定推送到哪一个。推送前检查剩余空间,按做种时长、分享率等条件清理旧种子,并保护 H&R 种子。
  • 通知与 ChatOps:在 QQ(OneBot)和 Telegram 里查看状态、暂停或删除种子、增删 RSS 订阅,每条命令都记入操作审计;RSS 上新通知支持静默时段、合并摘要、失败重试和每小时配额。企业微信与通用 Webhook 是实验性的出站通道。
  • 浏览器扩展:PT Tools Helper 一键同步站点 Cookie,并采集脱敏后的页面数据,用于申请新增站点。
  • 部署与维护:Docker 镜像(amd64、arm64)与 Linux、Windows 二进制;二进制部署可以在 Web 界面升级;日志、暂存种子和旧备份先预览再清理;访问站点和下载器可以走 HTTP、HTTPS 或 SOCKS5 代理。

[!WARNING] RSS 未关联任何过滤规则时,pt-tools 只会下载免费种子。追剧或下载特定的非免费资源时,请创建过滤规则并按需关闭「仅免费」。

安装

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
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

保存为 compose.yml 后运行 docker compose up -d。镜像同时发布在 Docker Hub(sunerpy/pt-tools)和 GHCR(ghcr.io/sunerpy/pt-tools),都包含 amd64 与 arm64。

[!IMPORTANT] 必须持久化 /app/.pt-tools。这个目录里有数据库、配置和用来加密站点凭证的 secret.key;密钥丢失后,已保存的 Cookie 无法恢复。

安装脚本
# Linux
curl -fsSL https://raw.githubusercontent.com/sunerpy/pt-tools/main/scripts/install.sh | sh
# Windows PowerShell
irm https://raw.githubusercontent.com/sunerpy/pt-tools/main/scripts/install.ps1 | iex

脚本会下载最新版本的压缩包和同一版本的 checksums.txt,SHA-256 不一致时拒绝安装。用 TOOL_VERSION 指定版本(例如 TOOL_VERSION=v0.48.0),Linux 上用 TOOL_INSTALL_DIR 指定安装目录(默认 ~/.local/bin)。

预编译二进制

从 Releases 下载。每个版本都附带 checksums.txt 和构建来源证明,gh attestation verify 的用法写在每个 Release 的说明里:

系统 架构 文件
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

解压后运行 pt-tools web --host 0.0.0.0 --port 8080。没有 macOS 二进制,macOS 请使用 Docker。systemd 服务、Windows 与更多 Docker 示例见安装、二进制运行指南和Docker 示例。

从源码构建

需要 Go 1.26.9、Node.js 25.2.0 和 pnpm 10.25.0,运行 make build-local,详见开发指南。

快速开始

  1. 打开 http://localhost:8080,用初始账号 admin / adminadmin 登录,并立即修改密码。
  2. 在「下载器设置」中添加 qBittorrent 或 Transmission,并检查连通性。
  3. 添加站点认证:Cookie 站点用 PT Tools Helper 同步,API Key 和 Passkey 站点按获取 Cookie 与 API Key 填写。
  4. 添加 RSS 订阅,选好下载器、保存目录和免费结束后的处理方式。默认只下免费种子,不需要过滤规则。
  5. 备份 secret.key,并确认数据目录已有外部备份。

逐步说明见文档站的快速开始。

用法

  • Web 界面:站点、RSS、过滤规则、下载器、自动清理和通知都在 Web 界面里配置。
  • ChatOps:QQ 和 Telegram 支持 /help、/status、/tasks、/sites、/torrents、/pause、/resume、/delete、/addrss、/delrss、/bind 和 /unbind。通道的两栏名单决定谁能与机器人对话;用绑定码完成绑定的账号都能执行管理命令,所以绑定码只发给信任的人。见 ChatOps 快速开始。
  • 命令行:pt-tools web 启动服务,pt-tools secret 导出、导入加密密钥,pt-tools clean 预览并清理已轮转的日志、暂存种子和旧备份,见命令行。

文档

文档站 firlab.app/pt-tools(中文,English)的内容来自本仓库的 docs/ 目录,在 GitHub 上也可以从文档中心按主题浏览。

文档 内容
安装 Docker、二进制、systemd 与首次登录
配置说明 环境变量、代理、下载器、持久化与日志
RSS 订阅 订阅、下载器选择、免费结束策略
过滤规则与追剧 关键词、通配符与正则规则
自动删种与磁盘保护 清理条件、H&R 保护与剩余空间检查
站点登录监控 登录探测、保号提醒与密钥备份
ChatOps QQ、Telegram、绑定与 RSS 上新通知
升级与备份 各安装方式的升级、备份与恢复
数据与安全 数据位置、加密范围、外连与部署建议
支持站点 66 个内置站点及认证方式
请求新增站点 用扩展采集并脱敏提交站点数据
常见问题 认证、RSS、下载器与数据库排障

每个版本的功能、修复和升级说明见 Releases 与 CHANGELOG。

开发

仓库固定使用 Go 1.26.9、Node.js 25.2.0 和 pnpm 10.25.0。克隆后运行完整的本地门禁:

make check

常用目标:

make fmt             # Go 与前端格式化
make lint            # Go、前端 lint 与类型检查
make test            # 前端构建与单测,Go race 测试
make docs-check      # 仓库内 Markdown 的相对链接与锚点
make build-local     # 构建前端和当前平台的二进制
make build-extension # 校验站点并打包浏览器扩展

贡献前请阅读开发指南和仓库根目录的 AGENTS.md。提交与 PR 标题遵循 Conventional Commits;新增站点只在 site/v2/definitions/ 添加定义,并补齐 fixture 测试。文档站的写作约定与上线流程见 docs/README.md。

社区

许可证

MIT License


免责声明:本工具仅供学习和研究使用。请遵守各 PT 站点的规则,并自行评估自动化访问的风险。

Documentation

Overview

Copyright © 2024 sunerpy <nkuzhangshn@gmail.com> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Directories

Path Synopsis
apitoken
Package apitoken 管理 API 令牌(路线图 M12):给 App、MCP 与 qB 兼容入口用,网页登录仍然只认 session。
Package apitoken 管理 API 令牌(路线图 M12):给 App、MCP 与 qB 兼容入口用,网页登录仍然只认 session。
app
assistant
Package assistant 是 pt-tools 内置的 AI 助手(路线图 M19):经 OpenAI 兼容的 Chat Completions 接口(官方 openai-go) 调大模型,工具是每次运行在进程内连上的 MCP 服务(internal/mcp 的同一套工具,经 App API v1 执行)。
Package assistant 是 pt-tools 内置的 AI 助手(路线图 M19):经 OpenAI 兼容的 Chat Completions 接口(官方 openai-go) 调大模型,工具是每次运行在进程内连上的 MCP 服务(internal/mcp 的同一套工具,经 App API v1 执行)。
cloakdriver
Package cloakdriver provides Go bindings for CloakBrowser-Manager REST API and CDP automation.
Package cloakdriver provides Go bindings for CloakBrowser-Manager REST API and CDP automation.
cloakdriver/gazelle
Package gazelle implements the Gazelle-schema CloakBrowser driver (T13).
Package gazelle implements the Gazelle-schema CloakBrowser driver (T13).
cloakdriver/mtorrent
Package mtorrent implements the mTorrent (M-Team) CloakBrowser driver.
Package mtorrent implements the mTorrent (M-Team) CloakBrowser driver.
cloakdriver/nexusphp
Package nexusphp implements the NexusPHP-schema CloakBrowser driver.
Package nexusphp implements the NexusPHP-schema CloakBrowser driver.
cloakdriver/transport
Package transport 把 CloakBrowser 的各架构驱动接成登录探测的后备通道(sitelogin.Transport)。
Package transport 把 CloakBrowser 的各架构驱动接成登录探测的后备通道(sitelogin.Transport)。
cloakdriver/unit3d
Package unit3d implements the Unit3D-schema CloakBrowser driver.
Package unit3d implements the Unit3D-schema CloakBrowser driver.
cookiecloud
Package cookiecloud 从自建的 CookieCloud 服务取回加密的 Cookie,在本地解密,按站点地址挑出 pt-tools 已配置站点的 Cookie。
Package cookiecloud 从自建的 CookieCloud 服务取回加密的 Cookie,在本地解密,按站点地址挑出 pt-tools 已配置站点的 Cookie。
dlassistant
Package dlassistant 是下载器助手:给缺站点标签的种子补标签、批量替换 tracker 地址、找出 tracker 报告 未注册或不存在的失效种子。
Package dlassistant 是下载器助手:给缺站点标签的种子补标签、批量替换 tracker 地址、找出 tracker 报告 未注册或不存在的失效种子。
extension
Package extension implements the pending-actions queue for browser extension polling.
Package extension implements the pending-actions queue for browser extension polling.
filter
Package filter provides pattern matching and filtering functionality for RSS items.
Package filter provides pattern matching and filtering functionality for RSS items.
iyuu
Package iyuu 是 IYUU 辅种接口的客户端。
Package iyuu 是 IYUU 辅种接口的客户端。
maintenance
MIT License Copyright (c) 2025 pt-tools
MIT License Copyright (c) 2025 pt-tools
mcp
Package mcp 是 pt-tools 的 MCP(Model Context Protocol)服务(路线图 M14):工具定义、权限检查与写操作的审计。
Package mcp 是 pt-tools 的 MCP(Model Context Protocol)服务(路线图 M14):工具定义、权限检查与写操作的审计。
media/douban
Package douban 从豆瓣取电影与剧集(一季)的简介和评分,刮削时补充 TMDB 的数据。
Package douban 从豆瓣取电影与剧集(一季)的简介和评分,刮削时补充 TMDB 的数据。
media/meta
Package meta 解析 PT 种子的标题与副标题:中英文名、年份、类型、季与集(含范围、「全 N 集」「第 1-10 集」)、 分辨率、来源、编码、HDR、音轨、制作组、版本,以及中字、国语、粤语等标记。
Package meta 解析 PT 种子的标题与副标题:中英文名、年份、类型、季与集(含范围、「全 N 集」「第 1-10 集」)、 分辨率、来源、编码、HDR、音轨、制作组、版本,以及中字、国语、粤语等标记。
media/organize
Package organize 是整理入库服务:种子下载完成后识别出电影或剧集,按媒体库的模板与整理方式放进库里, 写 NFO 与图片,通知媒体服务器扫描,发入库通知。
Package organize 是整理入库服务:种子下载完成后识别出电影或剧集,按媒体库的模板与整理方式放进库里, 写 NFO 与图片,通知媒体服务器扫描,发入库通知。
media/recognize
Package recognize 是媒体识别服务:套用识别词、解析标题,再到 TMDB 找对应的条目 (有 IMDb 编号时直接查找,否则按中英文名和年份搜索打分),支持按 TMDB 编号手动纠正。
Package recognize 是媒体识别服务:套用识别词、解析标题,再到 TMDB 找对应的条目 (有 IMDb 编号时直接查找,否则按中英文名和年份搜索打分),支持按 TMDB 编号手动纠正。
media/scrape
Package scrape 为整理进媒体库的电影与剧集写 Kodi 格式的 NFO(Emby、Jellyfin、Plex 的 NFO 插件都认), 并下载海报、背景、季海报与集截图。
Package scrape 为整理进媒体库的电影与剧集写 Kodi 格式的 NFO(Emby、Jellyfin、Plex 的 NFO 插件都认), 并下载海报、背景、季海报与集截图。
media/server
Package server 是媒体服务器的客户端:Emby、Jellyfin 与 Plex。
Package server 是媒体服务器的客户端:Emby、Jellyfin 与 Plex。
media/subscribe
Package subscribe 是订阅:按电影或剧集的一季找资源(RSS 拉到的种子与定时主动搜索),按质量档案挑、推送到下载器, 剧集按 TMDB 的分集找缺的集;洗版时接着找更好的版本,入库后替换旧文件;豆瓣想看定时建订阅。
Package subscribe 是订阅:按电影或剧集的一季找资源(RSS 拉到的种子与定时主动搜索),按质量档案挑、推送到下载器, 剧集按 TMDB 的分集找缺的集;洗版时接着找更好的版本,入库后替换旧文件;豆瓣想看定时建订阅。
media/tmdb
Package tmdb 是 TMDB v3 接口的客户端:搜索电影与剧集、按 IMDb 编号查找、取详情。
Package tmdb 是 TMDB v3 接口的客户端:搜索电影与剧集、按 IMDb 编号查找、取详情。
media/transfer
Package transfer 是整理入库的文件操作:从种子的文件里挑出要整理的视频与字幕、按模板算出库里的路径, 再用硬链接、复制、软链接或移动放进媒体库。
Package transfer 是整理入库的文件操作:从种子的文件里挑出要整理的视频与字幕、按模板算出库里的路径, 再用硬链接、复制、软链接或移动放进媒体库。
media/words
Package words 套用识别词:解析标题之前屏蔽或替换文字,解析之后按规则偏移集数。
Package words 套用识别词:解析标题之前屏蔽或替换文字,解析之后按规则偏移集数。
notify/adapter/bark
Package bark 是 Bark(iOS 推送)出站通道:POST {server}/push,JSON 里带 device_key;返回 code 为 200 才算成功。
Package bark 是 Bark(iOS 推送)出站通道:POST {server}/push,JSON 里带 device_key;返回 code 为 200 才算成功。
notify/adapter/dingtalk
Package dingtalk 是钉钉群自定义机器人出站通道。
Package dingtalk 是钉钉群自定义机器人出站通道。
notify/adapter/feishu
Package feishu 是飞书(Lark)群自定义机器人出站通道。
Package feishu 是飞书(Lark)群自定义机器人出站通道。
notify/adapter/ntfy
Package ntfy 是 ntfy 出站通道:按 JSON 发布,POST 到服务器根地址 {topic, title, message, priority, click}; 可选 access token(Bearer)或用户名密码(Basic)。
Package ntfy 是 ntfy 出站通道:按 JSON 发布,POST 到服务器根地址 {topic, title, message, priority, click}; 可选 access token(Bearer)或用户名密码(Basic)。
notify/adapter/outbound
Package outbound 是只出站的通知适配器(Bark、Server 酱、ntfy、钉钉、飞书、企业微信群机器人)共用的发送工具。
Package outbound 是只出站的通知适配器(Bark、Server 酱、ntfy、钉钉、飞书、企业微信群机器人)共用的发送工具。
notify/adapter/serverchan
Package serverchan 是 Server 酱出站通道。
Package serverchan 是 Server 酱出站通道。
notify/adapter/telegram
Package telegram implements the notify.Channel adapter for Telegram bots using mymmrac/telego with long-polling.
Package telegram implements the notify.Channel adapter for Telegram bots using mymmrac/telego with long-polling.
notify/tmpl
Package tmpl 是通知的模板引擎:Go 的 text/template,加上一组受控的函数与防护。
Package tmpl 是通知的模板引擎:Go 的 text/template,加上一组受控的函数与防护。
redact
Package redact 遮住要交给外部的文本里可能带的凭证:App API 的错误信息、AI 助手存下来与发给各入口的会话内容。
Package redact 遮住要交给外部的文本里可能带的凭证:App API 的错误信息、AI 助手存下来与发给各入口的会话内容。
remote
Package remote 是远程访问(路线图 M15)的协议与主机端:手机 App 扫码配对以后,经直连 WebSocket 或 relay 调用这台 pt-tools 的 App API v1。
Package remote 是远程访问(路线图 M15)的协议与主机端:手机 App 扫码配对以后,经直连 WebSocket 或 relay 调用这台 pt-tools 的 App API v1。
remote/relayserver
Package relayserver 是 relay 的 Go 自建版(路线图 M16):只做转发,看不到明文。
Package relayserver 是 relay 的 Go 自建版(路线图 M16):只做转发,看不到明文。
remote/relaytest
Package relaytest 是 relay 的一致性测试(黑盒):Go 自建版与 Cloudflare 版跑同一套用例, 对着一个已经起好的 relay(ws:// 或 wss:// 地址)连主机与客户端,只看线上的行为。
Package relaytest 是 relay 的一致性测试(黑盒):Go 自建版与 Cloudflare 版跑同一套用例, 对着一个已经起好的 relay(ws:// 或 wss:// 地址)连主机与客户端,只看线上的行为。
remote/testhost command
Command testhost 是手机 App(apps/mobile)互通测试用的主机:真正的 internal/remote 主机端(直连入口与 relay 客户端), App API 换成固定的回应,加一台进程内的 Go relay(relayserver)。
Command testhost 是手机 App(apps/mobile)互通测试用的主机:真正的 internal/remote 主机端(直连入口与 relay 客户端), App API 换成固定的回应,加一台进程内的 Go relay(relayserver)。
reseed
Package reseed 实现 IYUU 辅种:把下载器里已经下完的种子的 info hash 交给 IYUU 查询,找出其他站点上数据相同的种子, 从站点下载种子文件、核对 info hash 与文件列表后,暂停加入同一台下载器(保存路径用原种子的),校验到 100% 才开始做种。
Package reseed 实现 IYUU 辅种:把下载器里已经下完的种子的 info hash 交给 IYUU 查询,找出其他站点上数据相同的种子, 从站点下载种子文件、核对 info hash 与文件列表后,暂停加入同一台下载器(保存路径用原种子的),校验到 100% 才开始做种。
transfer
Package transfer 实现转移做种:把下载器里已经下完的种子搬到另一个下载器继续做种,数据不动。
Package transfer 实现转移做种:把下载器里已经下完的种子搬到另一个下载器继续做种,数据不动。
site
v2
Package v2 provides caching utilities for performance optimization
Package v2 provides caching utilities for performance optimization
thirdpart
httpclient
Package httpclient 提供基于 github.com/sunerpy/requests 的 HTTP 客户端连接池管理
Package httpclient 提供基于 github.com/sunerpy/requests 的 HTTP 客户端连接池管理
web
Package web provides HTTP server and API handlers
Package web provides HTTP server and API handlers
middleware
Package middleware 放请求主体(路线图 M12):谁发起的请求、有哪些权限范围。
Package middleware 放请求主体(路线图 M12):谁发起的请求、有哪些权限范围。
qbitcompat
Package qbitcompat 是 qB 兼容入口(路线图 M13):在单独的端口上实现 qBittorrent WebUI API v2 的一个子集, 让 MoviePilot、IYUU、autobrr、Sonarr/Radarr 这类只认 qB 的工具把 pt-tools 当成下载器。
Package qbitcompat 是 qB 兼容入口(路线图 M13):在单独的端口上实现 qBittorrent WebUI API v2 的一个子集, 让 MoviePilot、IYUU、autobrr、Sonarr/Radarr 这类只认 qB 的工具把 pt-tools 当成下载器。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL