Project dossier

PTDash

PT 控制面板,当前正从单节点面板演进为双节点种池控制器。

进行中 启动于 2026年4月16日 公共项目页
Python qBittorrent Web API Jinja Templates SSH Automation
当前状态
目标

把 PTDash 做成能安全管理 `local` 与 `pool2` 两个 qB 节点的控制面板,并支持单侧 ownership 迁移。

Current Focus

把现有迁移流程从请求驱动改成后台 job 系统,避免大体积迁移超时,同时让 ownership 状态更稳定。

Next Milestone

引入迁移队列、job 状态跟踪和 UI 进度展示,让迁移和 ownership 同步具备可恢复性。

下次开场提示

这段提示词默认面向跨地点、跨设备接续,不再把单机绝对路径当成前提。

你现在接手的是项目 `PTDash`(slug: `ptdash`)。
先阅读这些公网入口:
- 总接续看板:https://doc.unicorn5514.fun/resume/
- 项目档案:https://doc.unicorn5514.fun/projects/ptdash/
- PTDash 面板:https://pt.unicorn5514.fun/

工作约束:
- 以项目档案、最近 session log 和运行中面板状态作为 source of truth。
- 不要默认假定迁移是同步完成的;先核对 ownership 状态、重复种提示和当前批次进度。
- 如果当前设备没有代码工作副本,先登录运行 PTDash 的控制节点并确认当前服务状态,再继续 currentFocus。
跨地点接入
Public Entry Points
Bootstrap
  • 先阅读 https://doc.unicorn5514.fun/projects/ptdash/ 和最近一篇 PTDash session log,确认 currentFocus、blockers 和 ownership 模型。
  • 打开 https://pt.unicorn5514.fun/ 查看当前面板状态;这个入口需要现有 Basic Auth 凭据。
  • 如需改代码,先登录运行 PTDash 的控制节点,核对正在运行的 systemd 服务和当前工作树,再修改后端或模板。
  • 改动后先验证 local / pool2 快照、duplicate warning、ownership 展示和迁移动作,再决定是否发布到运行中的服务。
项目背景

这页内容整理自运行环境中的 ptdash/DEVELOPMENT.md,目的是把能支持后续接力开发的核心上下文收敛到公网档案里。

当前背景

PTDash 正在从单节点 PT 控制面板,扩展成双节点控制器:

  • local:主控制节点
  • pool2:第二个做种池节点

pool2 的目的不是重复跑同一批种子,而是在不让同一 torrent 同时运行在两个节点上的前提下,扩大在线做种池,提升做种积分效率。

已经完成

第二节点基础设施

  • 第二个 qBittorrent 实例已经部署完成,可被控制节点采集状态。
  • 远端 SSH 公钥认证已经就位,便于自动化操作。
  • 反向隧道已建立,控制节点不再依赖短时敲门窗口来获取 pool2 状态。

PT 工具链整合

  • ptool 已经加入第二个 qB client profile。
  • PTDash 后端已支持多节点快照、client 列表和跨节点重复种检测。

PTDash 后端与前端

  • 后端新增了 qb_nodesclient_names、重复种检测和 ownership 文件。
  • 已有 POST /api/migrate-pool2 迁移入口。
  • 前端已增加节点摘要卡片、pool2 传输表、在线做种池表、重复种警告和 迁到 pool2 动作按钮。
  • ownership 相关展示字段也已经接到 UI。

Ownership Model

当前 ownership 设计状态:

  • active
  • migrating_to_pool2
  • migrated_to_pool2

迁移规则仍然要求单侧运行:

  1. local 暂停 torrent
  2. 复制数据到 pool2
  3. pool2 以 paused 状态添加
  4. local client 移除 torrent,但不删数据
  5. pool2 恢复运行

当前迁移状态

第一批迁移已经完成,第二批迁移正在进行中。公网档案里只保留阶段性判断:

  • 已完成批次应该显示为“已迁到 pool2”
  • 进行中批次应该显示为“迁移到 pool2 中”

更细的种子清单、节点地址和运行中的具体操作明细,仍以控制节点上的 DEVELOPMENT.md 为准。

Known Gaps

迁移接口健壮性不足

大体积迁移可能超过 HTTP 请求时长,调用方先收到 timeout,但后台传输其实仍在继续。实际结果是:

  • 迁移可能已经成功
  • UI 要等下一次 snapshot sync 才能完整反映最终状态

Ownership 覆盖问题

sync_ownership() 会根据实时 qB 数据重建 ownership,如果过渡态没有被持续回写,就可能被覆盖。

还没有后台任务系统

现在迁移仍然偏请求驱动 / shell 驱动,缺少这些基础能力:

  • migration job queue
  • job status tracking
  • resumable migration record
  • per-job UI progress

Recommended Next Steps

  1. 把迁移流程改成后台 job 系统。
  2. 持久化每个 job 的进度,而不是从零散状态反推。
  3. 在 PTDash 中展示 migration jobs,包括 source node、target node、phase 和 last update time。
  4. 让 ownership state 成为 UI 动作启用/禁用的主依据。
  5. 继续把已完成且空闲的种子迁到 pool2,但避免移动当前仍有上传流量的项。

Relevant Files

  • server.py
  • templates/index.html
  • config.json
  • torrent_ownership.json
  • DEVELOPMENT.md

公网档案默认不直接公开全部运行细节;如果需要更细粒度的节点信息和迁移批次,请回到运行环境内对照原始开发文档。

会话时间线