NAS下载器技术选型与技术方案调研（V1.0 / 615）

一、结论先行

1.1 推荐路线

推荐采用：统一任务编排层 + 协议内核适配层 + 双下载内核。

• BT / PT / Magnet 内核：优先采用 qBittorrent-nox
• HTTPS 直链内核：优先采用 aria2
• 品牌分享链接：自研 share-adapter，优先走服务端转存，失败降级真实下载任务
• 统一对外：由自研 download-orchestrator 暴露统一 REST/WebSocket API、统一任务模型、统一权限与通知能力

1.2 为什么这么选

因为 615 版本的重点不是“做一个通用下载框架”，而是：

1. 尽快把核心链路跑通并稳定上线；
2. PT 安全、Tracker 详情、文件级选择、做种规则这些 BT/PT 核心能力不能弱；
3. HTTPS 直链、断点续传、重定向、冲突策略又必须补齐；
4. 还要保证 Web / App / NAS 本地使用统一任务模型。

单内核想同时把 BT/PT 体验和 HTTPS 能力都做强，短期并不划算。双内核 + 编排层，是当前最现实的快速落地方案。

1.3 最终建议

• 615 版本上线建议：qBittorrent-nox + aria2 + 自研编排层
• 若法务/License 风险较高：改为 libtorrent + libcurl 的“自研内核路线”
• 若极度追求低配 NAS 资源占用：可把 BT 内核备选为 Transmission daemon

---

二、需求反推后的关键技术约束

结合 [[我的笔记/NAS需求文档/下载器/NAS下载器应用V1.0（615版本）产品需求文档]]，615 版本对技术方案的硬约束主要有：

2.1 协议覆盖

• BT / 私有 PT / Magnet / HTTPS / 品牌分享链接

2.2 BT/PT 必须具备的能力

• torrent 解析
• Magnet 元数据获取
• 文件级选择下载
• 做种、分享率、上传统计
• Tracker 列表 / 状态 / reannounce
• PT 安全模式
• 重启恢复

2.3 HTTPS 必须具备的能力

• 301/302/307 重定向
• 断点续传
• 文件名识别
• 同名冲突策略
• 失败重试与明确错误提示

2.4 平台侧要求

• NAS 常驻进程
• 设备重启后恢复
• Web / App / 本地统一任务模型
• 200 条历史任务、20 个活跃任务并发
• 可观测、可排障、可通知、可打开目录

这意味着：下载引擎不能直接裸暴露给前端，必须有一层统一编排层做状态收敛、权限治理、错误码标准化与多端同步。

---

三、候选开源方案调研

3.1 方案 A：qBittorrent-nox（推荐作为 BT/PT/Magnet 内核）

优点

• Headless 运行成熟，适合服务端/NAS 场景。
• WebUI / WebAPI 很完整，远程控制能力成熟。
• 对 BT/PT 运维型功能支持更丰富：
  • torrent 列表/详情
  • tracker 列表
  • reannounce
  • 文件优先级/文件选择
  • share limit / seeding time
  • 全局速率信息
  • 日志接口
• 用户侧认知成本低，很多 PT 用户对 qBittorrent 行为较熟悉。

风险 / 缺点

• 不适合作为 HTTPS 直链内核，因此仍需第二内核或自研 HTTP 下载模块。
• License 为 GPLv2+ 路线，商用 NAS 预装需做法务审查。
• 从官方 WebAPI 文档看，DHT / PEX / LSD 更多是偏“应用级偏好设置”；如果要做到你们 PRD 要求的“PT 安全模式强约束”，建议在编排层增加校验与回归测试，不要只依赖 UI 默认值。

适配结论

非常适合承担 615 版本的 BT/PT/Magnet 内核。

---

3.2 方案 B：Transmission daemon（BT 内核备选，偏 NAS/轻量）

优点

• 官方明确提供 headless daemon for servers and routers，天然适合 NAS。
• 官方站点明确强调其低资源占用，且曾被多家 NAS/路由器厂商采用。
• RPC 能力完整，支持：
  • tracker_stats
  • peers
  • file wanted/unwanted
  • seed ratio / seed idle / queue
  • 端口、PEX、LPD、DHT、传输协议偏好
• RPC 在 4.1.0 起已支持 JSON-RPC 2.0，接口现代化程度较高。

风险 / 缺点

• 面向“产品级排障”的能力不如 qBittorrent 完整，尤其是日志、可解释性和用户熟悉度略弱。
• 同样不覆盖 HTTPS 直链下载。
• 若你们未来想做更强的 PT 高级用户运营能力，扩展面可能不如 qBittorrent 直观。

适配结论

适合作为低配 NAS 机型、资源敏感机型的 BT 内核备选。

---

3.3 方案 C：aria2（推荐作为 HTTPS 直链内核）

优点

• 一套引擎同时支持 HTTP/HTTPS/FTP/SFTP/BitTorrent/Metalink。
• JSON-RPC / WebSocket / XML-RPC 成熟，易于被编排层托管。
• HTTP 侧能力强：
  • 断点续传
  • 多连接下载
  • 重定向
  • 代理/证书/超时配置
• 体积小、资源占用低、适合嵌入式/NAS。
• BT 能力也不弱：支持 Magnet、DHT、PEX、UDP tracker、文件选择、做种时间/分享率。
• 官方文档明确说明：private torrent 下即使开启 DHT / PEX / LPD，也不会对该下载生效，这一点对 PT 安全很友好。

风险 / 缺点

• BT/PT 观测能力不如 qBittorrent：官方 RPC 暴露了 peers、files、status，但Tracker 细粒度状态与面向 PT 用户的“可解释性”不如 qBittorrent 友好。
• 如果用 aria2 同时扛 BT 和 HTTPS，615 版本虽然能做，但 BT/PT 体验大概率只能达到“够用”，难以达到“PT 用户满意”。
• License 为 GPL-2.0，商用预装同样要审查。

适配结论

非常适合承担 HTTPS 直链下载内核；若走极简单内核路线，也可作为全能备选，但不建议作为 615 的唯一主内核。

---

3.4 方案 D：libtorrent（长期最优的自研内核基础）

优点

• 官方定位就是“feature complete C++ bittorrent implementation”，且明确支持嵌入式设备。
• License 为 BSD，对商业 NAS 产品更友好。
• 对状态、调度、PT 安全、任务模型映射拥有最高控制权。
• 适合未来统一成你们自己的原生下载服务。

风险 / 缺点

• 开发成本最高。
• 需要自行补齐：
  • 管理 API
  • 持久化
  • 日志与诊断
  • 任务状态机
  • Tracker / Peer / 文件选择封装
  • 与 HTTPS 下载模块的统一任务编排
• 615 版本如果直接上这条路，项目风险会明显高于“基于成熟 daemon 快速落地”。

适配结论

最适合中长期平台化，但不适合作为 615 首发的唯一交付路径。

---

四、选型对比表

方案	BT/PT	Magnet	HTTPS直链	文件选择	Tracker状态	做种规则	远程API	资源占用	License友好度	615落地速度
qBittorrent-nox	强	强	弱	强	强	强	强	中	中低	高
Transmission daemon	强	强	弱	强	强	强	强	高	中	高
aria2	中上	中上	强	强	中	中上	强	高	中低	高
libtorrent	强	强	无	强	强（需自封装）	强（需自封装）	无	高	高	低

结论

• BT/PT 体验第一：qBittorrent-nox
• 低资源/NAS 原生属性第一：Transmission daemon
• HTTPS 第一：aria2
• 长期平台掌控/商业 License 第一：libtorrent

---

五、推荐总体架构

text
Web / App / NAS Local UI
        │
        ▼
Download BFF / API Gateway
        │
        ▼
Download Orchestrator（核心编排层）
├─ Task Service（统一任务模型）
├─ Protocol Router（协议识别与路由）
├─ PT Safety Guard（PT安全策略）
├─ Conflict Resolver（重复/同名冲突）
├─ Notification Service（完成/失败通知）
├─ File Link Service（打开目录联动）
├─ AuthZ / Path Permission（权限校验）
└─ Event Bus / WebSocket Push（多端状态同步）
        │
        ├─ qB Adapter（BT/PT/Magnet）
        ├─ aria2 Adapter（HTTPS）
        └─ Share Adapter（品牌分享转存/下载）
                │
                ├─ 品牌分享元数据接口
                ├─ 提取码校验
                ├─ 转存接口
                └─ 下载降级接口

Persistent Store
├─ SQLite（任务主数据/事件/设置）
├─ Engine Mapping（统一 task_id -> engine job id）
└─ Operation Log / Error Log

---

六、建议的技术栈

6.1 服务端

推荐：Go

原因：

• 开发效率高，适合 615 快速落地；
• 静态编译、交叉编译方便，适合 NAS 多机型发布；
• 并发、RPC 适配、进程托管、HTTP/WebSocket 都成熟；
• 生态足够支撑 SQLite、REST、WebSocket、任务编排、配置管理。

不推荐作为 615 主路线

• Node.js：做 BFF 很快，但守护进程/下载编排/资源控制不是最优。
• Rust：长期优秀，但 615 版本对交付速度不占优。
• 直接 C++ 自研全栈：掌控力最强，但首版风险太高。

6.2 Web 端

• Vue 3 + TypeScript + Pinia + Element Plus / Naive UI

原因：

• 中后台类任务列表、详情、设置页开发效率高；
• 与 NAS Web 管理台风格容易统一；
• 表格、树、抽屉、详情页、设置页组件成熟。

6.3 数据存储

• SQLite（WAL 模式） 作为 615 本地元数据主库

存储内容：

• 统一任务表
• 任务事件表
• 设置表
• 引擎映射表
• 错误码/错误快照表
• 分享链接缓存表（可选）

原因：

• 单机 NAS 应用足够；
• 部署简单；
• 便于做恢复和审计；
• 200~1000 级任务数据完全够用。

6.4 进程托管

• 采用 NAS 系统服务管理器 / systemd / supervisor 托管以下进程：
  • download-orchestrator
  • qbittorrent-nox
  • aria2 daemon

要求：

• 开机自启
• 异常拉起
• 健康检查
• 优雅停止
• 重启恢复

---

七、统一任务模型设计建议

建议不要直接把 qB / aria2 原始模型暴露给前端，而是统一映射成你们 PRD 的任务模型。

7.1 建议补充字段

除 PRD 中已有字段外，建议再补充：

字段	说明
engine_type	qb / aria2 / share_transfer
engine_task_id	对应底层引擎任务 ID
source_kind	torrent_file / magnet / https / share_link
capability_flags	是否支持做种 / tracker / 文件选择 / 续传
duplicate_key	用于重复任务检测
share_mode	save / download
visibility_scope	管理员/个人可见范围
last_event_time	最近事件时间
last_event_message	最近一条人类可读事件

7.2 状态映射建议

统一状态	qBittorrent	aria2	分享链路
waiting	queued / stalled	waiting	waiting
metadata_fetching	metaDL	active(元数据阶段)	metadata_fetching
downloading	downloading	active	downloading
seeding	uploading / stalledUP	seeding	-
paused	paused*	paused	paused
verifying	checking*	校验中（需内部映射）	-
completed	completed	complete	saved / completed
failed	error / missingFiles 等	error	failed
invalid	-	-	expired / canceled

说明：底层引擎状态很多，前端只暴露统一状态；更细节的信息下钻到详情页和日志页签。

---

八、核心模块方案

8.1 Protocol Router（协议路由）

输入：用户粘贴内容 / 上传 torrent 文件。

识别逻辑：

• magnet:? -> qB Adapter
• .torrent -> qB Adapter
• https://品牌域名/... -> Share Adapter
• https://其他域名/... -> aria2 Adapter

补充建议：

• 做一个标准化 source 解析器，输出：
  • source_kind
  • normalized_source
  • suggested_name
  • duplicate_key
  • validation_result

---

8.2 PT Safety Guard（PT 安全策略层）

这是 615 的关键差异化模块，建议单独做，不要散落在 UI。

职责

• 识别 private torrent
• 禁止公共 Tracker 注入
• 禁止高风险配置覆盖
• 生成“PT 安全模式已启用”的统一标记
• 记录安全策略命中日志

建议规则

• private=1 -> 自动打 task_type=pt
• 屏蔽“追加公共 Tracker”能力
• DHT/PEX/LSD 风险配置命中时给出拦截或二次确认
• 做种规则默认继承全局 PT 策略

额外建议

建立一份 pt_policy_snapshot，用于记录任务创建时实际生效的 PT 策略，方便客服排障。

---

8.3 Conflict Resolver（重复任务/同名冲突）

HTTPS

• 基于目标路径 + 最终文件名做冲突检查
• 支持：跳过 / 覆盖 / 自动重命名

BT/PT/Magnet

• 基于 infohash 做重复检测
• Magnet 在元数据获取前用 magnet hash 建临时键

分享链接

• 基于分享资源 ID + 目标目录 + 模式（转存/下载）做幂等校验

---

8.4 Share Adapter（品牌分享适配器）

建议拆分

• Share Resolver：解析链接、提取码、登录态
• Share Metadata Service：拉文件树
• Share Save Service：服务端转存
• Share Fallback Downloader：降级为真实下载任务

关键原则

• 先转存，后下载
• 转存失败时给出结构化失败原因
• 下载模式要回写到统一任务模型中，让用户知道当前链路是“转存”还是“下载”

---

九、为什么不建议 615 直接做“全自研统一下载内核”

虽然从长期看，libtorrent + libcurl + 自研任务内核 是更优雅的架构，但 615 直接这么做的问题是：

1. 研发风险大；
2. BT/PT 和 HTTPS 两条协议栈都要自己打磨；
3. 远程管理、重启恢复、状态同步、错误诊断都要自己补齐；
4. 首版最容易被拖慢的不是 UI，而是“边界情况 + 守护能力 + 恢复能力”。

615 的目标是先稳定上线，不是先做底座理想化重构。

因此更合理的路线是：

• 615：先用成熟内核快速上线
• 730 / V2：逐步替换成品牌自有原生下载服务

---

十、分阶段落地建议

10.1 Phase 1：615 上线方案（推荐）

技术组合

• BT/PT/Magnet：qBittorrent-nox
• HTTPS：aria2
• 品牌分享：自研 share-adapter
• 编排层：Go
• DB：SQLite
• Web：Vue3 + TS

本阶段目标

• 先交付核心下载链路
• 先打通统一任务模型
• 先把 PT 安全、通知、打开目录、多端同步做稳定

本阶段不追求

• 单内核统一
• 对底层引擎的彻底抽象完美
• 大量高级网络参数

---

10.2 Phase 2：730 版本

• 增加监听目录
• 增加临时目录/完成目录分离
• 增加 App 上传 torrent
• 增加更完整的诊断导出
• 增加引擎熔断和自动迁移策略

---

10.3 Phase 3：平台化演进

如后续确认 License、商业可控性、品牌差异化都很重要，则逐步演进到：

• BT/PT/Magnet：自研 libtorrent 内核服务
• HTTPS：自研 libcurl 下载服务
• Share：沿用自研适配器
• Orchestrator 保持接口不变，仅替换底层 adapter

这也是为什么 615 一开始必须先做“编排层与统一任务模型” —— 因为它能保护后续换核成本。

---

十一、项目风险与应对

风险	描述	应对
GPL 商用合规	qB / aria2 都要做 License 审查	615 先审查；不通过则切 libtorrent+libcurl
双内核状态不一致	qB 和 aria2 模型不同	一切以前台统一 task_id 为准，不直接暴露引擎模型
PT 安全模式不彻底	仅靠 UI 默认值不可靠	独立 PT Safety Guard + 自动化回归测试
下载恢复不稳定	引擎状态与数据库状态可能漂移	启动时做 reconcile，对账恢复
分享链接接口波动	品牌分享接口变更	share-adapter 独立版本化，避免污染下载主链路
低配机型资源吃紧	双 daemon 常驻	低配机型评估 Transmission / aria2-only 备选

---

十二、最终建议（拍板版）

推荐结论

615 版本建议直接采用：

Go 编排层 + qBittorrent-nox（BT/PT/Magnet） + aria2（HTTPS） + 自研 Share Adapter + SQLite + Vue3

原因

• 能最快满足 PRD 全量协议范围；
• BT/PT 能力足够强；
• HTTPS 能力补得快；
• 风险主要集中在“编排与治理层”，而不是底层协议细节；
• 后续能平滑演进到自研原生内核。

一句话判断

• 如果你们最优先考虑“615 快速交付”：选 qBittorrent-nox + aria2
• 如果你们最优先考虑“商用 License 可控”：选 libtorrent + libcurl
• 如果你们最优先考虑“低资源 NAS 机型”：BT 内核可优先评估 Transmission daemon

---

十三、参考资料（2026-04-22 调研）

• qBittorrent 官方站：https://www.qbittorrent.org/
• qBittorrent WebUI API（5.0+）：https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-%28qBittorrent-5.0%29
• qBittorrent 无界面运行文档：https://github.com/qbittorrent/qBittorrent/wiki/Running-qBittorrent-without-X-server-%28WebUI-only%29
• qBittorrent 源码仓库：https://github.com/qbittorrent/qBittorrent
• Transmission 官方站：https://transmissionbt.com/
• Transmission RPC 规范：https://github.com/transmission/transmission/blob/main/docs/rpc-spec.md
• Transmission 源码仓库：https://github.com/transmission/transmission
• aria2 官方站：https://aria2.github.io/
• aria2 Manual：https://aria2.github.io/manual/en/html/aria2c.html
• aria2 源码仓库：https://github.com/aria2/aria2
• libtorrent 官方站：https://libtorrent.org/
• libtorrent 源码仓库：https://github.com/arvidn/libtorrent
• curl / libcurl：https://curl.se/