配置说明

本文档详细介绍 pt-tools 的所有配置选项，包括环境变量、全局设置、下载器配置和 RSS 订阅配置。

环境变量

通过环境变量可以配置 pt-tools 的运行参数，适用于 Docker 部署场景。

变量	说明	默认值	示例
PT_HOST	Web 监听地址	0.0.0.0	127.0.0.1
PT_PORT	Web 监听端口	8080	8888
PT_ADMIN_USER	管理员用户名	admin	myadmin
PT_ADMIN_PASS	管理员密码	adminadmin	MySecurePass123
PT_ADMIN_RESET	重置管理员密码	-	1 (启用)
PT_QBIT_COMPAT_ADDR	qB 兼容入口的监听地址，不设时不开	-	0.0.0.0:8081
PUID	容器用户 ID	1000	1001
PGID	容器组 ID	1000	1001
TZ	时区	Asia/Shanghai	America/New_York

环境变量使用示例

Docker 命令行：

docker run -d \
  -e PT_HOST=0.0.0.0 \
  -e PT_PORT=8080 \
  -e PT_ADMIN_USER=admin \
  -e PT_ADMIN_PASS=your_password \
  -e TZ=Asia/Shanghai \
  sunerpy/pt-tools:latest

Docker Compose：

environment:
  PT_HOST: "0.0.0.0"
  PT_PORT: "8080"
  PT_ADMIN_USER: "admin"
  PT_ADMIN_PASS: "your_password"
  TZ: "Asia/Shanghai"

重置管理员密码

如果忘记密码，可以通过环境变量重置：

docker run -d \
  -e PT_ADMIN_RESET=1 \
  -e PT_ADMIN_USER=admin \
  -e PT_ADMIN_PASS='新密码' \
  -v ~/pt-data:/app/.pt-tools \
  -p 8080:8080 \
  sunerpy/pt-tools:latest

重置完成后，移除 PT_ADMIN_RESET 环境变量重新启动容器。

代理配置

有两种设法：在「全局设置」里给站点设代理，保存后立即生效，不用重启；或者用标准环境变量，Docker、systemd 和本地二进制运行都适用，改了要重启。两种可以一起用：开了站点代理以后，站点请求按全局设置，其他请求按环境变量。

在全局设置里按站点设代理

在「全局设置」页的「站点代理」一段：

1. 打开「站点请求走代理」，填代理地址，例如 http://192.168.1.2:7890 或 socks5://用户名:密码@主机:1080。支持 http、https、socks5、socks5h。
2. 在「哪些站点走代理」里选：全部站点、只有选中的站点、除了选中的站点。后两种在下面的列表里选站点，列表里是 pt-tools 支持的全部站点，没启用的标着「未启用」。「除了选中的站点」一个都不选，等于全部站点。
3. 点「保存设置」。保存后立即生效，不用重启。

说明：

• 管的是 pt-tools 发给站点的请求：搜索与种子列表、取 RSS、下载种子（RSS、辅种和手动下载都算）、签到、取用户信息、站点图标。RSS 订阅按它所属的站点判定。
• 开启时站点请求只看这里：选中的站点经这个代理，其余站点直连，环境变量里的代理不再管站点。关闭时和以前一样按环境变量。
• 不管下载器、IYUU、通知通道、TMDB 与其他媒体数据来源、AI 助手等，它们按各自的设置或环境变量；CloakBrowser 在它自己的配置里设代理。
• 代理地址加密保存在数据库里，页面上显示时密码换成 ***，不改就原样保留。
• 走代理的站点看到的是代理出口的 IP。站点规则对 IP 有要求的（例如 HDSky 的盒子规则），先确认再让它走代理。
• 这个设置只能在网页上改，App API 与 MCP 读不到也改不了。

用环境变量设代理

变量	说明	示例
HTTP_PROXY / http_proxy	HTTP 请求代理	http://127.0.0.1:7890
HTTPS_PROXY / https_proxy	HTTPS 请求代理	http://127.0.0.1:7890
ALL_PROXY / all_proxy	通用代理（作为回退）	socks5://127.0.0.1:1080
NO_PROXY / no_proxy	不走代理的地址列表（逗号分隔）	localhost,127.0.0.1,.lan

说明：

• 建议同时设置 HTTP_PROXY 和 HTTPS_PROXY。
• 如果未设置 HTTP_PROXY/HTTPS_PROXY，站点访问和下载器连接会改用 ALL_PROXY；RSS 拉取和 Telegram 通道目前只读取 HTTP_PROXY/HTTPS_PROXY，需要代理时请设置这两个变量（Telegram 也可以在通道里单独填写代理 URL）。
• RSS 任务下载种子文件以前一直直连，现在和站点访问一样按这些变量走（包括 ALL_PROXY）。
• NO_PROXY 对内网地址非常有用，可避免本地服务或局域网请求走代理。
• 在「全局设置」里开了站点代理以后，站点请求不再看这些变量，见上一节。
• 修改环境变量后要重启 pt-tools。

代理配置示例

Docker 命令行：

docker run -d \
  --name pt-tools \
  -p 8080:8080 \
  -v ~/pt-data:/app/.pt-tools \
  -e HTTP_PROXY=http://127.0.0.1:7890 \
  -e HTTPS_PROXY=http://127.0.0.1:7890 \
  -e ALL_PROXY=socks5://127.0.0.1:1080 \
  -e NO_PROXY=localhost,127.0.0.1,.lan \
  sunerpy/pt-tools:latest

Docker Compose：

environment:
  HTTP_PROXY: "http://127.0.0.1:7890"
  HTTPS_PROXY: "http://127.0.0.1:7890"
  ALL_PROXY: "socks5://127.0.0.1:1080"
  NO_PROXY: "localhost,127.0.0.1,.lan"

全局设置

在 Web 管理界面的「全局设置」页面可配置以下选项：

配置项	说明	默认值	建议值
默认间隔(分钟)	RSS 任务的默认执行间隔	10	15-30 分钟
种子下载目录	保存 .torrent 文件的目录	downloads	根据需求设置
启用下载限速判断	用于判断种子是否能在免费期内完成	关闭	按需开启
预估下载速度(MB/s)	实际平均下载速度	-	根据实际带宽设置
最大种子大小(GB)	超过此大小的种子将被跳过	无限制	50-100 GB
最短免费时间(分钟)	免费剩余时间少于此值的种子将被跳过	30	20-60 分钟
自动启动 RSS 任务	程序启动（包括重启容器）时是否自动运行 RSS 任务，见下一节	否	是
站点代理	让选中的站点经代理访问，保存后立即生效，见在全局设置里按站点设代理	关闭	有站点连不上时再开

RSS 任务的启动与停止

RSS 任务按检查间隔拉取已启用站点下的 RSS 订阅，按下载模式和过滤规则把种子推送到下载器，RSS 上新通知也来自它。刷流、辅种、转移做种、自动删种、免费到期处理、签到、登录提醒和媒体库整理各自运行，不受它的启停影响；媒体订阅的定时搜索照常进行，只是「RSS 里出现时也下载」要等 RSS 任务在运行。

• 在哪里操作：底部状态栏左端的「RSS 任务」，点开是一个面板（手机上在底部「我的」里，底栏状态行也显示状态）。面板显示是否在运行、几个订阅在运行；没在运行时写明原因，例如没开自动启动、手动停止过、没有默认下载器、默认下载器连不上。
• 启动与停止：「启动」按当前配置运行全部 RSS 订阅；「停止」让它们停下，直到再次启动。停止只在这一次运行中有效，程序重启后按自动启动的设置决定是否运行。
• 自动启动：面板里的「程序启动时自动运行」和「全局设置」页的「自动启动 RSS 任务」是同一个开关，默认关闭。关着时，每次程序启动（包括重启容器、升级）后都要手动启动一次，页面顶上会提示「RSS 任务没有运行」。打开后马上按配置运行（手动停止过的除外），以后程序启动时也会自动运行。
• 修改配置以后：修改站点、RSS 订阅或全局设置等配置后，正在运行的 RSS 任务按新配置重新开始，手动停止的不会被拉起来。重新开始和程序启动时一样要先连上默认下载器，连不上就不运行，状态栏会写明原因；下载器恢复后点「启动」。

限速与免费期计算

启用下载限速判断后，pt-tools 会根据以下公式判断种子是否能在免费期内完成：

预计完成时间 = 种子大小 / 预估下载速度
如果 预计完成时间 > 免费剩余时间，则跳过该种子

最短免费时间

即使不启用限速判断，pt-tools 也会检查免费剩余时间。当种子的免费剩余时间小于「最短免费时间」阈值（默认 30 分钟）时，会自动跳过该种子，避免出现"刚下载就被暂停"的情况，浪费下载配额和带宽。

设置为 0 表示不限制（关闭此检查）。

免费结束管理

配置项	说明	默认值	建议值
免费期结束前提前处理(分钟)	提前 N 分钟暂停/删除未完成种子，规避删除延迟与汇报滞后	新安装 5	≥5 分钟

免费期结束时没下完的种子暂停还是删除，在每条 RSS 订阅的「免费结束时没下完」里选（不处理、暂停或删除，见 RSS 订阅）。以前这是全局的「免费结束自动删除」：升级时开着它的，开着免费结束暂停的订阅都换成「删除」，已经在等到期处理的种子照升级前处理。

「免费期结束前提前处理」用于设置一个安全余量：系统会在 免费结束时间 - N 分钟 触发暂停或删除，规避删除动作本身的延迟以及下载器到 tracker 的汇报滞后，避免免费期已过仍在产生非免费下载量。

• 取值范围 [0, 60] 分钟，超出范围会被自动截断。
• 0 表示到点处理。升级前已经设好的值不变，新安装默认 5；设成 0 时设置页会提示可能多出计费下载量。
• 要求免费的推送（免费通道、开了「仅免费」的过滤规则、质量档案要求免费的订阅、只收免费优惠的刷流任务、等免费）还要求免费剩余时间超过这个值，至少 5 分钟，不够的不推送。
• 由于周期巡检兜底粒度为 5 分钟，建议设置为 ≥5 分钟；独立定时器精确到秒，主路径不受此粒度限制。
• 该提前量仅影响免费结束的触发时刻，不影响重试调度（重试触发时刻保持不变）。

下载器配置

基本配置

pt-tools 支持以下下载器：

下载器	支持版本	推荐程度
qBittorrent	4.x+	推荐
Transmission	3.x+	支持

配置字段说明：

字段	说明	示例
名称	下载器标识名称	家里qBit、NAS主力
类型	下载器类型	qBittorrent / Transmission
地址	WebUI 地址	http://192.168.1.10:8080
用户名	登录用户名	admin
密码	登录密码	password
设为默认	是否作为默认下载器	是/否
自动开始	推送任务后是否自动开始	是/否

下载目录配置

每个下载器可配置多个下载目录：

字段	说明	示例
路径	下载目录的实际路径	/data/downloads/movies
别名	目录的显示名称	电影
设为默认目录	是否为默认下载目录	是/否

注意事项：

• 路径必须是下载器所在机器上的有效路径
• Docker 环境下需要确保路径已正确映射
• 填了路径的地方（RSS 订阅、刷流任务、追剧、推送种子、转移做种的路径映射、媒体库的路径映射与整理范围）点开就列出这台下载器的目录，可以直接选，也可以输入别的路径；有别名时显示别名和路径

目录配置示例：

路径: /data/downloads/movies    别名: 电影     默认: 否
路径: /data/downloads/tv        别名: 剧集     默认: 是
路径: /data/downloads/anime     别名: 动漫     默认: 否
路径: /data/downloads/music     别名: 音乐     默认: 否

RSS 订阅配置

RSS 订阅是 pt-tools 的核心功能，配置字段如下：

字段	说明	是否必填	示例
名称	订阅标识名称	是	HDSky电影、MT电视剧
链接	RSS 订阅 URL	是	https://site.com/rss?...
分类	下载器中的分类标签	否	PT-Auto
标签	任务标签，便于管理	否	hdsky,movie
检查间隔(分钟)	执行间隔	是	5-1440 分钟
下载器	指定下载器	否	不指定则用默认
下载路径	指定下载目录	否	不指定则用默认
过滤规则	关联的过滤规则	否	可多选
免费结束时没下完	不处理、暂停或删除	否	暂停

RSS 配置建议

场景	建议间隔	免费结束时没下完
日常刷流	15-30 分钟	暂停或删除
追更剧集	10-15 分钟	视情况
新资源抢种	5-10 分钟	不处理

详细的 RSS 配置指南请参考 RSS 订阅配置指南。

数据持久化

pt-tools 的所有数据存储在数据目录中：

内容	Docker 路径	本地路径	说明
数据目录	/app/.pt-tools	~/.pt-tools	所有数据的根目录
数据库	torrents.db	torrents.db	SQLite 数据库文件
种子文件	downloads/	downloads/	下载的 .torrent 文件
日志文件	logs/	logs/	运行日志

日志管理

pt-tools 的日志由两部分组成，需分别管理：

1. 应用日志文件（~/.pt-tools/logs/）

应用通过 lumberjack 自动滚动切割，无需手动清理：

项目	默认值	说明
单文件上限	10 MB	超过后自动切割为带时间戳的备份
保留天数	30 天	超过天数的备份在下次切割时删除
保留备份数	10 个	每个日志流最多保留 10 个旧备份
压缩	开启	旧备份以 gzip 压缩存储

日志按级别分文件：all.log、info.log、error.log、debug.log。四个文件合计上限约 440 MB，不会无限增长。

启动时会额外做一次清理，删除超出保留策略的历史备份（针对频繁重启、单文件未达切割阈值导致旧备份滞留的场景）。

可通过环境变量调整启动期行为：

环境变量	默认值	说明
PT_TOOLS_LOG_LEVEL	info	日志级别：debug/info/warn/error
PT_TOOLS_LOG_CONSOLE	true	是否同时输出到控制台（stdout）。默认开启，便于通过 docker logs / NAS 控制台查看；设为 false 可彻底关闭 stdout 输出

2. 容器 stdout 日志（Docker 用户必读）

注意

Docker 日志膨胀：应用日志会同时写到 stdout（便于 docker logs / NAS 控制台查看），而 Docker 的 json-file 日志驱动默认无大小上限，长期运行可能累积到数 GB（曾出现 8GB）。这部分日志位于 /var/lib/docker/containers/<id>/<id>-json.log，不受应用 lumberjack 控制，必须由 Docker 侧限制。

控制台输出默认开启（PT_TOOLS_LOG_CONSOLE=true），以便在飞牛/群晖等 NAS 的容器控制台直接查看日志；因此务必为容器配置日志上限，否则 stdout 会被 Docker 无限累积。如确实不需要控制台日志，可设 PT_TOOLS_LOG_CONSOLE=false 关闭。

按部署方式选择对应配置：

Docker Compose（推荐，所有平台通用）：在服务下添加 logging 块。

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

docker run：追加参数。

docker run -d \
  --name pt-tools \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  ... \
  sunerpy/pt-tools:latest

飞牛 NAS（fnOS）/ 群晖 DSM Container Manager / Unraid / Portainer： 图形界面创建的容器，多数版本未开放日志驱动（log driver）配置。两种处理方式：(1) **长期方案（推荐）**改用 Docker Compose 部署并按上述方式配置 logging（GUI 已创建的可 SSH 到 NAS 改用 Compose 重建容器，数据目录已持久化不会丢失）；(2) 即时补救手动清理已堆积的容器日志（见下方「清理已堆积的旧容器日志」）。不建议为单容器去改 daemon.json。

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

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

然后执行 sudo systemctl restart docker。⚠️ 该配置仅对重新创建的容器生效，已存在的容器需重建后才会应用。

清理已堆积的旧容器日志：docker logs 无法直接清空，有两种方式：

• 截断日志文件（不影响容器运行）：

  truncate -s 0 $(docker inspect --format='{{.LogPath}}' pt-tools)

• 或重建容器（docker rm 后重新创建，数据目录已持久化不会丢失）。

数据备份

备份内容：torrents.db（全部配置和历史记录）和 secret.key（加密站点 Cookie、通知凭证和各类 API Key 的密钥）。两者必须作为一个整体备份和恢复：只恢复数据库、没有原来的密钥时，已保存的 Cookie、通知凭证和 API Key 都无法解密。

数据库运行时启用了 WAL 模式，最近的写入可能还在 torrents.db-wal 中，因此请先停止 pt-tools 再复制：

# Docker 环境（数据目录挂载在 ./data）
docker compose stop
tar -czf pt-tools-backup.tar.gz -C ./data torrents.db secret.key
docker compose start

# 本地环境（systemd）
sudo systemctl stop pt-tools
tar -czf pt-tools-backup.tar.gz -C ~/.pt-tools torrents.db secret.key
sudo systemctl start pt-tools

恢复方法：停止 pt-tools，把备份中的 torrents.db 和 secret.key 放回数据目录覆盖现有文件，再启动。只备份了 base64 形式的密钥时，用 pt-tools secret import --force 写回。完整步骤见升级与备份。

配置示例

完整 Docker Compose 配置

services:
  pt-tools:
    image: sunerpy/pt-tools:latest
    container_name: pt-tools
    environment:
      PT_HOST: "0.0.0.0"
      PT_PORT: "8080"
      PT_ADMIN_USER: "admin"
      PT_ADMIN_PASS: "your_secure_password"
      TZ: "Asia/Shanghai"
      PUID: "1000"
      PGID: "1000"
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/.pt-tools
      - /path/to/downloads:/downloads # 可选：映射下载目录
    restart: unless-stopped

典型使用场景配置

场景 1：纯刷流

• RSS 间隔：15-30 分钟
• 只下载免费种子
• 免费结束时没下完选暂停（或删除）
• 设置最大种子大小限制

场景 2：追剧 + 刷流

• RSS 间隔：10 分钟
• 创建追剧过滤规则，允许非免费
• 创建通用规则，只下载免费
• 免费结束时没下完选暂停（或删除）

场景 3：多站点管理

• 每个站点单独配置 RSS
• 配置多个下载器（如家里、公司）
• 设置不同的下载目录
• 使用标签区分来源

---

相关文档：

• RSS 订阅配置指南
• 获取认证信息指南
• 过滤规则与追剧指南