SkeyeVSS开发-后台下载(DownloadManager)架构设计

DownloadManager 架构设计：动机、实现与 SSE 协作

本文介绍core/pkg/functions/download中DownloadManager的职责划分、关键数据结构、这样设计的原因，以及优劣势；最后说明在VSS SSE（type=file_download）场景下的端到端流程。

项目源码地址https://github.com/openskeye/go-vss

一、组件定位

它不依赖 Gin/WebSocket，是可复用的下载 + 进度广播小内核；与SSE的关系是：Manager 负责「下什么、进度多少」，SSE 负责「如何把进度推到浏览器」。

二、核心数据结构

2.1DownloadTask

• TaskID：当前实现里TaskID == URL（CreateTask中taskID := url）。
• Filepath：saveDir+ 调用方传入的fileName。
• 状态：downloading/completed/error/cancelled。
• 进度：Downloaded、Total（来自Content-Length，未知则为 0）、Progress（百分比）、Speed（KB/s，按已读字节与耗时估算）。

2.2DownloadManager

tasks *xmap.XMap[string, *DownloadTask] // taskID -> 任务 clients *xmap.XMap[string, chan ProgressUpdate] // taskID -> 订阅 channel

• tasks：正在进行的任务索引；Finished/ 结束后会Remove。
• clients：每个taskID对应一个chan ProgressUpdate（缓冲10），下载循环通过notifyClients写入。

xmap.XMap为线程安全泛型 Map（读写锁），适合多 goroutine 并发注册任务与推送进度。

2.3 单例

var(manager*DownloadManager once sync.Once)funcGetManager()*DownloadManager{once.Do(func(){...})returnmanager}

保证全进程唯一 Manager，任务与订阅表全局共享——与「按 URL 去重、运维看板统计任务数」等需求一致。

三、API与行为

四、为什么要这样设计？

4.1 问题背景

平台侧需要从给定 URL 拉文件到服务器磁盘，同时让前端实时看到进度（百分比、速度、路径）。若仅用「同步 HTTP 下载 + 轮询 DB/Redis」，复杂度高、延迟大；若在业务里手写 goroutine + 多处chan，容易泄漏、难统一取消与统计。

4.2 设计选择背后的意图

1. 任务与传输解耦
   DownloadManager只关心任务生命周期 + 进度事件；谁消费进度（SSE、日志、未来 WebSocket）由上层Subscribe决定，符合观察者模式。

2. 以 URL 为 TaskID
   同一 URL 在表里天然去重：避免重复建任务、重复占带宽；与CheckExists、file_downloadSSE里「已存在则只订阅」的语义一致。

3. 单例 + 全局 Map
   在单进程 VSS内，所有下载与订阅集中管理，TaskNum/ClientNum可直接用于运维 SSE 面板（sev_state），无需再挂一层注册中心。

4. 进度 channel 带小缓冲（10）
   下载循环写进度频率高，缓冲可吸收瞬时突发，减少下载 goroutine 因消费者暂时未读而立刻阻塞的概率（消费者仍要跟得上）。

五、优势与风险

5.1 优势

5.2 风险

六、与 SSE 的配合过程（VSSfile_download）

实现位置：core/app/sev/vss/internal/logic/sse/file_download.go。

6.1 时序概览

6.2 关键步骤说明

1. Query 参数：type=file_download、url、可选filename、cancel=1。
2. 启动条件：!CheckExists(url)或cancel时调用downloader：取消走CancelDownload；否则CreateTask并go StartDownload。
3. 订阅：Subscribe(req.Url)与TaskID==url一致；defer Unsubscribe保证连接断开或逻辑退出时释放。
4. 向 SSE 转发：for { select { case v := <-ch } }，将ProgressUpdate封装为SSEResponse.Data写入messageChan。
5. 降频：通过NowMilli()%100 == 0等条件减少 SSE 帧率（避免每 32KB 都打一帧拖慢浏览器），终态（完成/取消/错误）仍强制推送。
6. 结束：Finished(url)关闭订阅 channel、移除任务；SSE 侧Done: true或Err结束事件流。

6.3 小结

七、与运维面板的衔接

sev_state（internal/logic/sse/sev_state.go）中两项：

• 「文件下载任务数量」→DownloadManager.TaskNum()
• 「文件下载任务数量」（第二项实现为ClientNum()，语义上更接近当前订阅连接数）

用于观察下载与 SSE 订阅是否堆积，可与SSE.MessageChanBuffer等配置联合调优（见 SSE 专题文档）。

八、源码索引

本文与《VSS-SSE架构设计》中file_download一节互补：前者偏传输协议，本文偏下载内核与协作边界。