pt-tools

简体中文

English

简体中文

English

外观

常见问题 (FAQ) ​

本文档汇总了使用 pt-tools 过程中常见的问题和解决方案。

下载器相关 ​

下载器连接失败 ​

现象：添加下载器后，「连通性」列显示「异常」，悬停可看到「连接失败」等原因。

排查步骤：

  1. 检查 URL 格式

    • 确保包含协议前缀：http:// 或 https://
    • 确保端口号正确
    • 示例：http://192.168.1.10:8080

  2. 检查用户名密码

    • 确认用户名和密码正确
    • 注意密码中的特殊字符是否需要转义

  3. 确认下载器已启用 WebUI

    • qBittorrent：设置 -> Web UI -> 启用 Web 用户界面
    • Transmission：设置 -> Remote -> 允许远程访问

  4. 检查防火墙设置

    • 确保端口已放行
    • 检查是否有安全组限制

  5. Docker 环境特别注意

    • 不要使用 localhost 或 127.0.0.1
    • 使用宿主机 IP 或 Docker 网络名称
    • 示例：http://host.docker.internal:8080 (Docker Desktop)
    • 或使用宿主机实际 IP：http://192.168.1.100:8080

种子推送失败 ​

现象：种子无法推送到下载器，提示「推送失败」。

排查步骤：

  1. 检查下载器连接状态

    • 在下载器设置页面点击该行的「检查连通性」
    • 确保连接正常

  2. 确认下载目录存在

    • 检查配置的下载路径是否存在
    • 确保下载器对该目录有写入权限

  3. 检查磁盘空间

    • 确保目标磁盘有足够的剩余空间

  4. 查看下载器日志

    • 在 qBittorrent/Transmission 中查看错误信息
    • 可能是种子文件损坏或格式问题

暂停任务无法恢复 ​

现象：在「暂停任务」页面点击「恢复」无响应。

排查步骤：

  1. 检查下载器是否在线

    • 确保下载器正常运行
    • 测试下载器连接

  2. 确认任务仍然存在

    • 在下载器中检查该任务是否存在
    • 如果任务已被删除，需要重新添加种子

  3. 检查任务状态

    • 某些情况下任务可能处于错误状态
    • 尝试在下载器中直接操作

站点认证相关 ​

现象：站点列表的「状态」列显示「异常」，点击「立即探测」提示「会话已过期」。

解决方法：

  1. 重新获取 Cookie

  2. 确保复制完整

    • Cookie 通常很长，确保完整复制
    • 不要包含 Cookie: 前缀
    • 避免多余的空格或换行

  3. 检查站点账号状态

    • 确认账号未被封禁
    • 确认账号未被强制下线

  4. 延长 Cookie 有效期

    • 登录时勾选「记住我」选项
    • 定期访问站点保持活跃

API Key 无法使用 ​

现象：M-Team 等站点显示 API Key 无效。

解决方法：

  1. 检查 Key 是否被撤销

    • 登录站点后台，查看 API Key 状态
    • 如已撤销，重新生成

  2. 确认 Key 权限

    • 某些站点的 API Key 有权限范围
    • 确保有足够的权限

  3. 重新生成 Key

    • 在站点后台删除旧 Key
    • 生成新的 API Key
    • 更新 pt-tools 配置

RSS 订阅相关 ​

RSS 订阅无法解析 ​

现象：RSS 订阅一直没有产生任务，「运行日志」中出现「RSS任务失败」或「解析 RSS 失败」。

排查步骤：

  1. 检查 RSS 链接

    • 在浏览器中直接打开 RSS 链接
    • 确认能返回 XML 内容

  2. 确认认证信息有效

    • Cookie 或 API Key 是否失效
    • RSS 链接中的 passkey 是否正确

  3. 检查网络连接

    • pt-tools 是否能访问站点
    • 是否需要代理

  4. 查看日志

    • 检查 pt-tools 日志获取详细错误信息
    • 日志位置：~/.pt-tools/logs/ 或 /app/.pt-tools/logs/

RSS 无法获取免费种子 ​

现象：RSS 正常解析，但没有免费种子被下载。

可能原因：

  1. 站点确实没有免费种子

    • 在站点页面确认是否有免费种子

  2. RSS 返回数量太少

    • 增加 RSS 链接中的 rows 参数
    • 如 rows=50

  3. 过滤规则过于严格

    • 暂时禁用所有过滤规则测试
    • 逐步添加规则排查问题

免费暂停功能相关 ​

免费结束暂停功能不生效 ​

现象：免费期结束后，种子仍在下载，没有被自动暂停。

排查步骤：

  1. 确认功能已开启

    • 编辑 RSS 订阅
    • 检查「免费结束暂停」开关是否启用

  2. 检查种子是否为免费种子

    • 非免费种子不会被监控
    • 在种子详情中确认免费状态

  3. 确认下载器配置正确

    • 下载器连接正常
    • pt-tools 能够控制下载器

  4. 检查免费时间信息

    • 某些种子可能没有免费结束时间
    • 这类种子无法被监控

  5. 查看日志

    • 确认监控器是否正常运行
    • 检查是否有相关错误信息

配置建议：

场景建议配置
带宽充足可不启用此功能，尽快完成下载
带宽有限建议启用，避免免费结束后消耗下载量
硬盘空间紧张启用后定期清理未完成的暂停任务
保号需求启用后手动恢复需要的任务继续做种

种子刚下载就被暂停 ​

现象：免费种子被下载后很快就被 FreeEndMonitor 暂停，进度很低（如 1-2%）。

原因：种子的免费剩余时间太短，来不及下载完就到期了。

解决方案：

在「全局设置」→「下载策略与限制」中设置「最短免费时间」（默认 30 分钟）。免费剩余时间少于此值的种子会被自动跳过，不再下载。这可以避免浪费下载配额和带宽。

同时建议启用「下载限速判断」并填写实际下载速度，pt-tools 会根据种子大小和免费剩余时间自动判断是否来得及下载完成。

系统管理相关 ​

代理环境变量如何配置 ​

现象：站点请求超时、连接失败，怀疑需要代理访问。

配置方法：

pt-tools 支持 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY 环境变量（大小写均可）。其中 ALL_PROXY 只用于站点访问和下载器连接，RSS 拉取和 Telegram 通道需要设置 HTTP_PROXY/HTTPS_PROXY。

详细说明和配置示例请参考 配置说明 - 代理配置。

修改环境变量后需重启服务使新配置生效。

重置管理员密码 ​

方法：通过环境变量重置

Docker 环境：

bash
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

Docker Compose：

yaml
environment:
  PT_ADMIN_RESET: "1"
  PT_ADMIN_USER: "admin"
  PT_ADMIN_PASS: "新密码"

重要提示：

  • 重置完成后，务必移除 PT_ADMIN_RESET 环境变量
  • 重新启动容器使新配置生效

数据库损坏 ​

现象：启动时提示数据库错误或页面无法加载数据。

解决方法：

  1. 尝试恢复备份

    bash
    # 停止服务
docker stop pt-tools

# 备份当前数据库
cp ~/.pt-tools/torrents.db ~/.pt-tools/torrents.db.broken

# 恢复备份
cp ~/backup/torrents.db ~/.pt-tools/

# 重启服务
docker start pt-tools

  2. 如果没有备份，尝试修复

    bash
    # 使用 sqlite3 工具检查和修复
sqlite3 ~/.pt-tools/torrents.db "PRAGMA integrity_check;"
sqlite3 ~/.pt-tools/torrents.db ".recover" | sqlite3 ~/.pt-tools/torrents_recovered.db

  3. 最后手段：重新初始化

    bash
    # 备份旧数据库
mv ~/.pt-tools/torrents.db ~/.pt-tools/torrents.db.old

# 重启服务（会创建新数据库）
docker restart pt-tools

# 需要重新配置所有站点和下载器

其他问题 ​

如果上述内容没有解决你的问题：

  1. 查看日志：~/.pt-tools/logs/ 目录下的日志文件
  2. 提交 Issue：GitHub Issues
  3. 社区求助：描述问题时请提供：
    • pt-tools 版本
    • 部署方式（Docker/二进制）
    • 详细的错误信息或日志
    • 复现步骤

相关文档：

pt-tools 基于 MIT License 发布，是 FirLab 的项目之一。内容来自 pt-tools@57dfb08。

Copyright © 2024–2026 sunerpy