Docs Hub

主题

快速开始（用户指南） ​

本文档面向使用者（不是开发者）。从零到仪表盘出数据，按顺序走完 5 步。 开发/编译/贡献请看 07-开发指南。

你将得到什么 ​

PT 守护神是一个自托管的 PT 工具箱：站点数据仪表、H&R 告警、自动签到、 Cookie 保活、跨站搜索/辅种、RSS 订阅、下载器管理、媒体推荐、AI 助手。

第 1 步：部署服务端（Docker） ​

bash
mkdir ptpatronus && cd ptpatronus
# 下载 docker-compose.example.yml 为 docker-compose.yml
docker compose up -d
  • 默认端口 8088，浏览器打开 http://<NAS的IP>:8088
  • 首次启动自动生成随机密钥（存 ./data/），不要删 data 目录（删了 = 所有站点 Cookie 丢失 + 全员被踢下线）
  • 数据库默认 SQLite，无需配置

⚠ 安全提示：compose 文件里 docker.sock 与宿主目录挂载默认是注释掉的。 只有你需要「运维中心 Docker 管理」或「文件管理器浏览宿主文件」时才手动打开， 并且尽量只挂单个目录（如 /vol1:/hostfs/vol1）而不是整个 /。

第 2 步：登录（好学 APP 专属 VIP） ​

登录有三种方式，从易到难排：

方式 A：账号密码登录（推荐） ​

  1. 登录页选「账号登录」
  2. 输入好学账号 + 密码
  3. 若开启了两步验证（2FA），输入 6 位动态码（和好学 APP 里同一个）
  4. 若出现图形验证码：填入图片里的字符（或点「识别」自动 OCR，需管理员在设置里配好 OCR 服务）
  1. 电脑浏览器打开 www.hxpt.org 并登录
  2. 按 F12 打开开发者工具 → 顶部切到 Network（网络） 标签
  3. 刷新页面，点击第一个请求 → Headers（标头） → 找到 Cookie: 开头的那一行
  4. 复制 Cookie: 后面的整串内容（很长，以 ; 分隔的多段）
  5. 粘贴到登录页「Cookie 登录」框里提交

方式 C：应急通道（好学改版/验证码全挂时） ​

管理员在服务端环境变量设 HXPT_EMERGENCY_ADMIN=user:pass， 登录页会出现「应急登录」入口。日常不要开。

首个通过 VIP 校验的用户自动成为管理员。

第 3 步：添加下载器（qBittorrent 示例） ​

  1. 左侧菜单 → 下载器 → 添加
  2. 填写：
    • 类型：qBittorrent
    • 地址：http://<下载器IP>:8080
    • 用户名/密码：qBittorrent 的 WebUI 账号密码
  3. 点 测试连接 → 显示成功后保存

qBittorrent 需要在 设置 → Web UI 里勾选「对 localhost 之外的请求进行身份验证」， 并建议固定 WebUI 端口。

第 4 步：添加 PT 站点 ​

  1. 左侧菜单 → 站点 → 添加站点
  2. 填写站点地址（如 https://pt.xxx.org）和 Cookie（获取方式同第 2 步方式 B：F12 → Network → 请求头里复制整串 Cookie）
  3. 保存后点 同步，站点数据（上传/下载/做种/魔力值）开始入库
  4. 数据每 30 分钟自动刷新一次；也可手动点刷新

常见问题：加了站点但数据全是 0？ ​

  • 多半是 Cookie 失效：重新按 F12 方式取一次 Cookie 覆盖
  • 或站点改版导致选择器失配：到 设置 → 运行日志 看抓取报错，反馈给开发者

第 5 步：打开仪表盘 ​

顶部 仪表盘 现在应该有数据了：站点上传/下载趋势、H&R 预警、做种列表。

推荐的下一步 ​

想要什么去哪里
H&R 到期前提醒通知中心 → 配置 Telegram/ Bark 等渠道
自动签到站点详情 → 签到设置
Cookie 自动保活安装浏览器扩展（见下）
跨站搜种顶部搜索框，一次搜所有已加站点
RSS 自动下载订阅页 → 添加 RSS
手机上看移动端 APP（设置 → 关于 里有下载入口）
  1. 设置 → 关于 → 下载扩展 zip，Chrome「开发者模式 → 加载已解压的扩展程序」
  2. 扩展选项页用好学账号登录
  3. 点「同步站点白名单」——弹出权限申请时点允许（读取站点 Cookie 必需）
  4. 开启「自动同步」后，浏览器与服务器 Cookie 双向保持新鲜

常见问题（FAQ） ​

Q：升级后想回退版本？ 先备份 ./data/ 整个目录，再改 compose 里镜像 tag 为旧版本号。 注意：新版可能已升级数据库表结构，回退后若报错，需用备份的 data 恢复。

Q：忘记密码/管理员丢了？ 服务端机器上执行：

bash
docker exec -it ptpatronus ./ptpatronus reset-admin

Q：数据保留多久？ 站点统计与签到记录 90 天、监控快照/告警/通知 30 天（每日 3 点自动清理）。

Q：遇到问题去哪反馈？ 设置 → 运行日志 导出日志 + 设置 → 诊断中心 跑一次体检，带上版本号反馈。