NAS下载器详细需求文档

# NAS下载器原型结构图

## 文档目的

本文件用于输出下载器 V1 的信息架构、页面结构和低保真原型关系，便于产品、设计、研发统一页面范围。

关联文档：[[我的笔记/NAS需求文档/下载器/NAS下载器详细需求文档]]、[[我的笔记/NAS需求文档/下载器/NAS下载器功能清单.md]]

---

# 一、整体信息架构

```mermaid
flowchart LR
    A[下载器应用] --> B[首页/任务列表]
    A --> C[添加任务弹窗]
    A --> D[任务详情页]
    A --> E[设置页]
    A --> F[通知/完成反馈]

    B --> B1[状态筛选]
    B --> B2[任务表格]
    B --> B3[批量操作]
    B --> B4[搜索/筛选]
    B --> B5[全局速率栏]

    C --> C1[链接创建]
    C --> C2[Torrent上传]
    C --> C3[品牌分享链接]

    D --> D1[基础信息]
    D --> D2[文件列表]
    D --> D3[Tracker/网络信息]
    D --> D4[错误日志]

    E --> E1[常规]
    E --> E2[下载/上传限制]
    E --> E3[BT/PT连接]
    E --> E4[做种规则]
    E --> E5[Tracker]
    E --> E6[通知]
    E --> E7[存储]
```

---

# 二、核心页面跳转结构

```mermaid
flowchart TD
    A[首页/任务列表] -->|点击添加任务| B[添加任务弹窗]
    A -->|点击任务名称| C[任务详情页]
    A -->|点击设置| D[设置页]
    A -->|点击完成通知| C
    B -->|创建成功| A
    B -->|需查看详情| C
    C -->|打开目录| E[文件管理]
    C -->|返回列表| A
    D -->|保存设置| A
```

---

# 三、首页/任务列表页原型结构

## 3.1 页面结构图

```mermaid
flowchart TD
    A[下载器首页] --> B[顶部工具栏]
    A --> C[左侧状态导航]
    A --> D[中间任务列表]
    A --> E[底部状态栏]
    A --> F[右侧详情抽屉 可选]

    B --> B1[添加任务]
    B --> B2[开始]
    B --> B3[暂停]
    B --> B4[删除]
    B --> B5[搜索框]
    B --> B6[筛选器]

    C --> C1[全部]
    C --> C2[下载中]
    C --> C3[做种中]
    C --> C4[已完成]
    C --> C5[已暂停]
    C --> C6[错误]

    D --> D1[多选框]
    D --> D2[名称]
    D --> D3[类型]
    D --> D4[状态]
    D --> D5[进度]
    D --> D6[下载速度]
    D --> D7[上传速度]
    D --> D8[剩余时间]
    D --> D9[已下载]
    D --> D10[分享率]
    D --> D11[保存位置]
    D --> D12[添加时间]

    E --> E1[总下载速率]
    E --> E2[总上传速率]
    E --> E3[任务统计]
```

## 3.2 低保真示意

```text
┌─────────────────────────────────────────────────────────────────────────────┐
│ 下载器                              [添加任务] [开始] [暂停] [删除] [搜索] │
├───────────────┬─────────────────────────────────────────────────────────────┤
│ 全部 (12)     │ □ 名称     类型  状态   进度  下行  上行  剩余  已下载  时间 │
│ 下载中 (4)    │ □ Ubuntu   BT   下载中 60%  2MB  0.3  8m   1.2G   10:21 │
│ 做种中 (3)    │ □ Movie    PT   做种中 100% 0    1.5  --   8.0G   昨天   │
│ 已完成 (2)    │ □ Tool.zip HTTPS 完成 100% --   --   --   1.1G   昨天   │
│ 已暂停 (1)    │ □ 分享资料 分享  排队中 0%   --   --   --   0      刚刚   │
│ 错误 (2)      │                                                             │
├───────────────┴─────────────────────────────────────────────────────────────┤
│ 总下载：12.6 MB/s   总上传：3.1 MB/s   活跃任务：5   错误任务：2           │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

# 四、添加任务弹窗原型结构

## 4.1 页面结构图

```mermaid
flowchart TD
    A[添加任务弹窗] --> B[类型识别区]
    A --> C[通用配置区]
    A --> D[协议专属配置区]
    A --> E[底部操作区]

    B --> B1[链接输入框]
    B --> B2[上传torrent按钮]
    B --> B3[自动识别结果标签]

    C --> C1[资源名称]
    C --> C2[保存目录]
    C --> C3[备注]
    C --> C4[自动开始]

    D --> D1[BT/PT文件列表]
    D --> D2[PT安全模式提示]
    D --> D3[分享链接提取码]
    D --> D4[分享文件列表]
    D --> D5[保存方式 转存/下载]

    E --> E1[取消]
    E --> E2[创建任务]
```

## 4.2 低保真示意

```text
┌──────────────────────────────────────────────┐
│ 添加任务                                  X │
├──────────────────────────────────────────────┤
│ [输入链接................................]   │
│ [上传 .torrent]    识别结果：PT种子          │
├──────────────────────────────────────────────┤
│ 资源名称：Ubuntu ISO                         │
│ 保存目录：[ downloads/linux            v ]   │
│ 备注：   [                                ]   │
│ 自动开始：[√]                                │
├──────────────────────────────────────────────┤
│ 文件列表：                                   │
│ [√] ubuntu.iso                     4.8 GB    │
│ PT 安全模式已启用：DHT / PEX / LSD 已关闭     │
├──────────────────────────────────────────────┤
│                         [取消] [创建任务]     │
└──────────────────────────────────────────────┘
```

---

# 五、任务详情页原型结构

## 5.1 页面结构图

```mermaid
flowchart LR
    A[任务详情页] --> B[头部摘要]
    A --> C[页签区]
    B --> B1[任务名称]
    B --> B2[状态]
    B --> B3[进度]
    B --> B4[开始/暂停/删除/打开目录]

    C --> C1[概览]
    C --> C2[文件]
    C --> C3[Tracker/网络]
    C --> C4[日志]

    C1 --> D1[保存目录]
    C1 --> D2[时间信息]
    C1 --> D3[累计下载/上传]
    C1 --> D4[错误摘要]

    C2 --> E1[文件名]
    C2 --> E2[大小]
    C2 --> E3[进度]

    C3 --> F1[Tracker列表]
    C3 --> F2[Peer数]
    C3 --> F3[分享率]
    C3 --> F4[PT安全模式]

    C4 --> G1[最近日志]
    C4 --> G2[错误码]
```

## 5.2 低保真示意

```text
┌────────────────────────────────────────────────────────────────┐
│ Movie-Pack [PT]   做种中 100%   ↑1.2 MB/s  Ratio 2.31         │
│ [暂停] [删除] [打开目录]                                      │
├────────────────────────────────────────────────────────────────┤
│ 概览 | 文件 | Tracker/网络 | 日志                              │
├────────────────────────────────────────────────────────────────┤
│ 保存目录：/media/downloads/movies                              │
│ 创建时间：2026-04-08 10:21                                     │
│ 累计下载：8.2 GB   累计上传：18.9 GB   做种时长：2天           │
│ PT安全模式：已启用                                             │
│ 错误摘要：无                                                   │
├────────────────────────────────────────────────────────────────┤
│ Tracker：tracker.xxx.com   正常   最近响应：320ms             │
│ Peer：38   下载器端口：51413                                  │
└────────────────────────────────────────────────────────────────┘
```

---

# 六、设置页原型结构

## 6.1 页面结构图

```mermaid
flowchart LR
    A[设置页] --> B[左侧分类导航]
    A --> C[右侧配置面板]

    B --> B1[常规]
    B --> B2[下载/上传限制]
    B --> B3[BT/PT连接]
    B --> B4[做种规则]
    B --> B5[Tracker]
    B --> B6[通知]
    B --> B7[存储]

    C --> C1[表单项]
    C --> C2[开关]
    C --> C3[数字输入]
    C --> C4[目录选择器]
    C --> C5[保存按钮]
```

## 6.2 低保真示意

```text
┌───────────────────────────────────────────────────────────────┐
│ 设置                                                          │
├───────────────┬───────────────────────────────────────────────┤
│ 常规          │ 默认下载目录  [ downloads/default        v ]  │
│ 下载/上传限制 │ 最大同时下载数 [ 3 ]                          │
│ BT/PT连接     │ 最大同时做种数 [ 5 ]                          │
│ 做种规则      │ 全局下载限速   [ 0 ] KB/s                     │
│ Tracker       │ 全局上传限速   [ 200 ] KB/s                   │
│ 通知          │ 分时段限速     [开启]                          │
│ 存储          │                                               │
│               │ [保存]                                         │
└───────────────┴───────────────────────────────────────────────┘
```

---

# 七、移动端关键结构

## 7.1 App 首页结构

```mermaid
flowchart TD
    A[App 下载器页] --> B[顶部搜索/添加]
    A --> C[状态标签]
    A --> D[任务卡片列表]
    A --> E[底部Tab或更多菜单]
```

## 7.2 App 卡片字段

- 名称
- 类型标签
- 状态
- 进度条
- 当前速度
- 错误摘要
- 更多操作

## 7.3 App 创建任务最小链路

```mermaid
flowchart TD
    A[点击添加] --> B[粘贴链接]
    B --> C[自动识别类型]
    C --> D[选择保存目录]
    D --> E[创建成功]
    E --> F[返回任务列表]
```

---

# 八、V1 与 V1.5 原型边界

## V1 必须出现的页面/模块

- 首页 / 任务列表页
- 添加任务弹窗
- 任务详情页
- 设置页
- Web/App 核心远程管理页

## V1.5 可扩展区域

- 监听目录页
- 自动整理规则弹窗
- App 上传 torrent 页
- 媒体联动配置区

---

# 九、设计说明

1. 首页尽量保持高频任务操作的低认知成本。
2. 添加任务弹窗需突出自动识别和 PT 安全提示。
3. 详情页需兼顾普通用户与进阶用户，两层信息展示即可。
4. 设置页避免一次性暴露过多高级参数，V1 聚焦关键项。
5. 移动端优先保障“创建任务、看进度、看错误、暂停恢复”。


NAS下载器原型结构图

# 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/>


NAS下载器技术选型与技术方案调研

# NAS下载器功能清单

## 说明

本文件为功能清单索引页，明细表见：[[我的笔记/NAS需求文档/下载器/NAS下载器功能清单.csv]]

关联文档：[[我的笔记/NAS需求文档/下载器/NAS下载器详细需求文档]]、[[我的笔记/NAS需求文档/下载器/NAS下载器原型结构图]]

---

## 一、功能清单结构

CSV 字段说明：

- 功能模块
- 页面/入口
- 功能点
- 功能说明
- 用户价值
- 优先级
- 版本
- 依赖
- 验收标准
- 备注

---

## 二、P0 功能模块汇总

| 功能模块 | 核心内容 |
|---|---|
| 任务创建 | 统一入口、类型自动识别、目录选择、重复任务检测 |
| BT/PT | torrent解析、文件选择、PT安全模式、做种规则、Tracker状态 |
| 磁力链 | magnet解析、元数据拉取、超时提示 |
| HTTPS | 直链下载、重定向、断点续传、冲突策略 |
| 品牌分享链接 | 链接识别、提取码校验、文件选择、转存/下载双模式 |
| 任务列表 | 状态导航、搜索、批量操作、总速率 |
| 任务详情 | 通用详情、日志、错误、Tracker/网络信息 |
| 系统设置 | 默认目录、并发、限速、端口、TCP/uTP |
| 通知联动 | 完成/失败通知、打开目录 |
| 远程管理 | Web管理、App远程添加链接任务、App查看状态 |

---

## 三、版本划分

### V1
- 完成 P0 主链路
- 支持 BT / 私有 PT / Magnet / HTTPS / 品牌分享链接
- 覆盖 Web / App 基础远程场景

### V1.5
- 监听目录
- UPnP / NAT-PMP
- 最大 Peer / 最大连接数
- App 上传 torrent
- 自动整理与媒体刷新

### V2
- RSS 自动订阅
- API / Webhook
- 规则引擎

---

## 四、使用建议

- 产品评审：优先查看本页 + CSV
- 设计评审：结合 [[我的笔记/NAS需求文档/下载器/NAS下载器原型结构图]]
- 研发排期：按 CSV 中“优先级 / 版本 / 依赖”三列拆分任务


NAS下载器功能清单

# NAS下载器服务端模块拆解图

## 一、服务端总体模块图

```mermaid
flowchart TB
    UI[Web / App / NAS本地界面] --> GW[API Gateway / BFF]
    GW --> AUTH[认证鉴权层]
    GW --> ORCH[Download Orchestrator\n下载编排服务]
    GW --> WS[WebSocket Push\n状态推送服务]

    ORCH --> TASK[Task Service\n统一任务服务]
    ORCH --> ROUTER[Protocol Router\n协议识别路由]
    ORCH --> POLICY[PT Safety Guard\nPT安全策略]
    ORCH --> CONFLICT[Conflict Resolver\n重复任务/冲突处理]
    ORCH --> SCHED[Scheduler / Queue Manager\n调度与队列]
    ORCH --> EVENT[Event Bus\n事件总线]
    ORCH --> FILE[File Link Service\n打开目录/文件联动]
    ORCH --> NOTICE[Notification Service\n通知服务]
    ORCH --> LOG[Log & Diagnostics\n日志诊断服务]
    ORCH --> SETTING[Settings Service\n设置中心]

    ROUTER --> QBADAPTER[qB Adapter\nBT/PT/Magnet适配层]
    ROUTER --> ARIA2ADAPTER[aria2 Adapter\nHTTPS适配层]
    ROUTER --> SHAREADAPTER[Share Adapter\n品牌分享适配层]

    QBADAPTER --> QB[qBittorrent-nox]
    ARIA2ADAPTER --> ARIA2[aria2 daemon]
    SHAREADAPTER --> SHAREAPI[品牌分享系统接口]

    TASK --> DB[(SQLite / Task DB)]
    EVENT --> DB
    LOG --> DB
    SETTING --> DB
    CONFLICT --> DB

    FILE --> FS[文件系统 / NAS目录权限]
    QB --> FS
    ARIA2 --> FS
    SHAREAPI --> FS

    NOTICE --> NC[系统通知中心]
    WS --> UI
```

---

## 二、分层拆解图

```mermaid
flowchart LR
    subgraph 接入层
        A1[REST API]
        A2[WebSocket]
        A3[鉴权中间件]
    end

    subgraph 业务编排层
        B1[统一任务模型]
        B2[任务创建流程]
        B3[任务控制流程\n暂停/恢复/删除/重试]
        B4[状态机管理]
        B5[错误码标准化]
        B6[多端状态同步]
    end

    subgraph 协议能力层
        C1[qB Adapter]
        C2[aria2 Adapter]
        C3[Share Adapter]
    end

    subgraph 基础能力层
        D1[权限校验]
        D2[目录检查]
        D3[通知]
        D4[日志与埋点]
        D5[设置中心]
        D6[任务恢复]
    end

    subgraph 持久化与外部依赖
        E1[(SQLite)]
        E2[qBittorrent-nox]
        E3[aria2]
        E4[品牌分享接口]
        E5[文件系统]
        E6[通知中心]
    end

    A1 --> B1
    A2 --> B6
    A3 --> D1
    B1 --> C1
    B1 --> C2
    B1 --> C3
    B2 --> D2
    B3 --> C1
    B3 --> C2
    B3 --> C3
    B4 --> E1
    B5 --> E1
    B6 --> A2
    C1 --> E2
    C2 --> E3
    C3 --> E4
    D2 --> E5
    D3 --> E6
    D4 --> E1
    D5 --> E1
    D6 --> E1
```

---

## 三、核心模块职责表

| 模块 | 职责 | 关键输入 | 关键输出 |
|---|---|---|---|
| API Gateway / BFF | 给 Web/App 提供统一接口 | 请求、用户身份 | REST 响应、WebSocket 订阅 |
| Auth / AuthZ | 登录态、目录权限、任务可见范围校验 | 用户、目录、任务 | allow / deny |
| Download Orchestrator | 总控创建、调度、状态流转、错误收敛 | 创建请求、控制请求、引擎回调 | 统一任务事件 |
| Task Service | 维护统一任务模型 | 引擎状态、用户操作 | task record |
| Protocol Router | 识别 magnet / torrent / https / share link | 原始输入 | 路由到对应 adapter |
| PT Safety Guard | private torrent 风险策略控制 | torrent metadata、系统设置 | PT 安全策略快照 |
| Conflict Resolver | 重复任务、同名冲突处理 | infohash、文件名、保存目录 | 冲突处理策略 |
| Scheduler / Queue Manager | 活跃下载数/做种数限制 | 全局设置、当前任务集 | waiting / active 调度结果 |
| qB Adapter | 对接 qB API，处理 BT/PT/Magnet | 任务命令 | torrent 状态、tracker、ratio |
| aria2 Adapter | 对接 aria2 RPC，处理 HTTPS | 任务命令 | 下载状态、续传信息 |
| Share Adapter | 对接品牌分享接口 | 分享链接、提取码 | 转存结果 / 降级下载 |
| Notification Service | 完成/失败通知 | 任务事件 | 系统通知 |
| File Link Service | 打开目录、跳转文件管理 | save_path | 文件管理联动动作 |
| Log & Diagnostics | 聚合日志、错误快照、诊断信息 | 引擎日志、系统事件 | 最近日志、错误摘要 |
| Settings Service | 管理默认目录、限速、并发、端口、做种规则 | 配置请求 | 生效配置 |
| Recovery Service | 重启后任务恢复、引擎对账 | DB 快照、引擎当前状态 | 恢复后的统一状态 |

---

## 四、建议的服务拆分（615版本）

### 4.1 单体守护进程方案（推荐）

615 更建议先做成 **单体服务 + 内部模块化**：

- `download-orchestrator`
  - 内含：API / 任务编排 / 状态机 / 通知 / 恢复 / 设置 / 日志聚合
- 外挂 daemon：
  - `qbittorrent-nox`
  - `aria2`

### 4.2 原因

- 部署简单
- 调试简单
- 机型适配成本低
- 更适合 NAS 首版
- 后续仍可以平滑拆分为独立微服务

---

## 五、615 版本建议的代码目录拆分

```text
server/
├─ cmd/
│  └─ downloaderd/
├─ internal/
│  ├─ api/
│  │  ├─ http/
│  │  ├─ websocket/
│  │  └─ middleware/
│  ├─ app/
│  │  ├─ task/
│  │  ├─ orchestrator/
│  │  ├─ scheduler/
│  │  ├─ policy/
│  │  ├─ conflict/
│  │  ├─ notify/
│  │  ├─ filelink/
│  │  ├─ settings/
│  │  └─ recovery/
│  ├─ adapter/
│  │  ├─ qb/
│  │  ├─ aria2/
│  │  └─ share/
│  ├─ domain/
│  │  ├─ task/
│  │  ├─ event/
│  │  ├─ enum/
│  │  └─ errorcode/
│  ├─ infra/
│  │  ├─ db/
│  │  ├─ logger/
│  │  ├─ config/
│  │  └─ eventbus/
│  └─ bootstrap/
└─ migrations/
```

---

## 六、最小可落地模块边界

615 真正必须先做好的，不是全部模块，而是下面 8 个：

1. `API Gateway / BFF`
2. `Download Orchestrator`
3. `Task Service`
4. `Protocol Router`
5. `qB Adapter`
6. `aria2 Adapter`
7. `Share Adapter`
8. `Recovery + Notification`

其余模块可以先内嵌在 orchestrator 中，以后再独立抽出。


NAS下载器详细需求文档

文档信息

NAS下载器原型结构图

文档目的

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

一、结论先行

1.

NAS下载器功能清单

说明

NAS下载器服务端模块拆解图

一、服务端总体模块图