Dannex Download Manager
  1. 主页
  2. 帮助
  3. 架构

架构

了解 Dannex Download Manager 的各个部分如何协同工作。

Crates

路径 Crate 作用
crates/engine mdm-engine 通过 HTTP(S) 或 FTP(S) 下载单个文件:探测、分段规划器、连接工作器、恢复状态、每主机限制、速度限制器、校验和、代理脚本
crates/app mdm-app 桌面应用(dannexdownloadmanager.exe,egui):列表、类别、队列、调度器、对话框、托盘、设置
crates/cli mdm-cli 无界面下载,带进度(get、resume)、视频、种子和自动化API命令:应用程序运行的库(dannexdownloadmanager --cli …),以及dannexdownloadmanager-cli,一个小型启动器,以相同的参数、终端和退出代码启动它
crates/mcp mdm-mcp MCP 服务器(dannexdownloadmanager-mcp):AI 助手通过自动化 API 列出、添加和控制正在运行的应用的下载
crates/remote mdm-remote 远程控制 (#141):本地网络上已配对的手机或电脑使用的 HTTPS 服务器(其页面、配对码、设备令牌、自签名证书);每个请求都成为应用响应的自动化 API 命令
crates/nmhost mdm-nmhost 浏览器的原生消息主机:从扩展程序获取捕获的下载并将其交给应用
crates/ipc mdm-ipc 应用和主机共享的单实例通道(受令牌保护的本地套接字)、数据文件夹和捕获规则
crates/debrid mdm-debrid 网盘账户 (#44):这些服务的官方 API(Real-Debrid、AllDebrid、Premiumize、TorBox)将文件托管链接转换为下载引擎可直接下载的链接。
crates/extract mdm-extract 档案解压 (#37):zip、tar、gz 和 xz 正在处理中;7z 和 RAR 通过已安装的 7-Zip 程序运行
crates/geo mdm-geo 下载服务器位置 (#140):根据 DB-IP Lite 数据 (tools/geo/build.py) 构建的 IP 到国家/地区范围表,仅在此计算机上查找,并显示国家/地区旗帜
crates/tools mdm-tools 视频页面通过 yt-dlp 和 ffmpeg,图片画廊通过 gallery-dl(作为独立程序运行);当选择网络适配器时,它们的连接通过 DDM 在 127.0.0.1 上的代理,将它们绑定到该适配器 (relay.rs)
crates/crash mdm-crash 崩溃和冻结报告:监视进程、进程外 minidumps、符号化堆栈、报告文本和发布日志(crash-reports.md)
crates/torrent mdm-torrent 通过 librqbit 处理 BitTorrent 和磁力链接
crates/labserver mdm-labserver 一个带请求日志和故障注入的 HTTP Range 服务器,以及一个带自身故障的 FTP/FTPS 服务器,用于测试和基准测试
extension/ — Chromium (MV3) 和 Firefox 扩展程序
docs/ — 用户指南和教程,此文件,基准数据;网站将此指南作为其帮助页面,点击“帮助”即可打开
website/ — dannex.kavangi.co.ke 自己的页面(主页、下载、功能、主题、常见问题);tools/website/build.py 添加了来自 docs/ 的帮助和来自 CHANGELOG 的新闻,共 22 种语言,由 GitHub Pages 发布

依赖项指向内部:app、cli、mcp、nmhost 和 remote 使用 engine 和 ipc;引擎对 UI 一无所知。应用仅通过其事件(进度、分段表快照、完成、失败)查看引擎。

引擎

Download
 ├─ probe()              size, resumable?, validators (ETag / Last-Modified), file name
 ├─ Planner (pure)       segment table: when a connection is free, the largest remaining
 │                       part is split in half (planner.rs, tested by random simulation)
 ├─ Worker × N           one HTTP/1.1 connection each, reused across segments; slow ones
 │                       are dropped and their part re-split
 │    └─ writes at its offset into <name>.mdm.part (created sparse)
 ├─ HostLimits           learns how many connections each server accepts
 ├─ Limiter (shared)     per-download and global token buckets
 ├─ State                segment table saved atomically (craft-atomic) for crash-safe resume
 └─ events → channel     Progress, Done, Failed

当所有分段完成后,部分文件会根据预期大小进行检查并重命名到位;文件的日期可以跟随服务器的日期。

下载的第一个请求 (get) 会跟踪重定向以及那些自行导向文件的页面(例如等待页面的刷新)。如果网站的链接不是文件地址,sites/ 中会有一个模块(例如 Google Drive: sites/gdrive.rs):它将链接转换为文件地址,读取网站自己的页面(例如确认表单、错误页面),并指出其拒绝原因 (Error::Refused),所有这些都通过无需网络即可测试的纯函数实现。实验室服务器会在其真实主机名上模拟此类网站,以进行端到端测试 (labserver/src/drive.rs)。

FTP 和 FTPS(ftp.rs)通过相同的规划器、工作器和状态:一个分段是控制会话上的 REST + RETR,而不是范围 GET,SIZE 和 MDTM 代表头部,会话按下载进行池化并在分段之间重用。

应用

一个 egui 窗口绘制到固定的像素坐标,每个对话框一个即时视口。app.rs 负责维护状态(下载、队列、设置、列表选择),并将菜单、工具栏、按键和 IPC 命令转换为操作。每个对话框都是独立的模块,并返回一个 Outcome(打开、关闭、完成并带有一个值)。仅限 Windows 的调用被限制在 win32.rs 中,而其 Linux 和 macOS 对应部分则在 unix.rs 中(从会话开始、浏览器主机、声音、在文件夹中显示、崩溃处理程序);其他所有文件都是安全、可移植的 Rust 代码。字体来自系统:Windows 的 Fonts 文件夹、macOS 的系统字体、Linux 上的 fontconfig (theme.rs)。在 Windows 上,拉丁语、希腊语和西里尔语文本由 DirectWrite 绘制 (win32.rs,通过 egui 的字形光栅化器钩子):在自然模式下,视图 → 文本 → 平滑,按请求的大小进行抗锯齿处理,并以四分之一像素放置,使用字体自身的字距;经典(默认)模式下,使用 GDI 经典模式,因此每个字母的提示形状和整像素宽度结合在一起。其他脚本由 egui 进行塑形和绘制。

主题

控件绘制的每种颜色和大小都来自活动主题 (#45)。一个主题包含一个亮色和暗色调色板、度量、控件样式和图标样式 (palette.rs):

  • 调色板角色。 palette.rs 声明每个角色都有一个稳定的键("button.hot"、"list.row"、"caption"…)、一个描述以及经典外观的亮色和暗色值,明确写出(经典外观并非派生)。共享的绘图器(winui.rs、chrome.rs、list.rs、scrollbar.rs)通过 theme::colors() 和 theme::metrics() 读取它们,并根据它们决定每个控件的状态;没有绘图代码拥有自己的颜色。
  • 派生调色板。 derive.rs 从几个种子(背景、表面、文本、强调色…)生成完整的调色板,在 OKLab 中混合所有其他角色并保持 WCAG 对比度(文本 4.5:1,边缘 3:1);高对比度会加强所有边缘。 native.rs 根据系统的强调色和对比度(Windows 设置、Linux 上的 freedesktop 门户、macOS 的强调色)为“原生”主题提供种子。
  • 控件样式。 palette::Controls 命名每个控件的形状(文本框、复选框、按钮、进度条、滚动条、焦点标记、标题栏);样式主题(现代、Adwaita、Breeze、Luna、Aero、Aqua、翡翠)选择各自的样式,在 Windows 上 DDM 会自行绘制标题栏(caption.* 角色)。
  • 主题文件。 themefile.rs 从数据文件夹的 themes 读取 TOML 或 JSON(一个文件,或 <id>/theme.toml 旁边带有图标)。一个文件只命名它所更改的内容;其余部分来自它 inherits 的主题(内置主题的 ID 或另一个文件,默认是经典外观),沿着一个拒绝循环的链。未知键是警告,而不是错误。内置样式主题也是此类文件,包含在程序中(crates/app/assets/themes)。
  • 图标集。 themeicons.rs 绘制主题的图标(按用途命名:tb-add-url、cat-music…,16、24、32 和 48 像素的 SVG 或 PNG,-symbolic 的图标以文本颜色着色),在经典外观绘制自己的图标的地方;如果图标集缺少所需图标,则保留经典图标。
  • 工具栏图标样式。视图 → 工具栏 → 线条样式(轮廓线,按主题的设定着色)或 3D 样式:DDM 自己的光泽图片(assets/icons/toolbar3d,由 tools/icon/toolbar_3d.py 以 16 到 64 px 绘制,取与屏幕上大小相符的一张;禁用时由 icons.rs 置灰)。它们用于主题没有为某个按钮提供图标、且按图标自身颜色着色的场合;带有自己图标集的主题,或把图标涂成单一颜色的主题(高对比度),则保留自己的图标。

窗口放置控件的位置保持其布局不变。文件名前的图标也是如此 (fileicons.rs):Windows shell 的系统图像列表、macOS Finder 的 (NSWorkspace)、Linux 桌面的图标主题 (xdgicons.rs、shared-mime-info 和图标主题规范)。每种类型按像素大小查找一次,在后台线程上进行。Tango 的图标(捆绑)在系统图标准备好之前以及系统没有图标的地方作为替代。

绘图

窗口使用 OpenGL(eframe 的 glow)或通过 eframe 的 wgpu 使用系统自己的图形 API 绘制,仅使用该后端:Windows 上的 Direct3D 12(默认),Linux 上的 Vulkan,macOS 上的 Metal(这些是选项;OpenGL 仍是它们的默认,直到真正的显卡尝试过它们,#206)。“视图”→“绘制方式”选择一个,从下次启动开始生效。一个代码路径在每个系统上都这样做 (crates/app/src/renderer.rs):当选择的无法启动时,会尝试另一个,因此窗口总是能打开。使用系统 API 的受监控启动会在绘制第一帧之前留下标记:如果启动在此之前结束(驱动程序内部崩溃),或者第一帧在 10 秒内未出现(DDM 随后会使用 OpenGL 重新启动),或者显卡在 10 分钟内丢失两次,则会记住其原因,并在菜单中显示。

“视图”→“界面大小”(scale.rs, #262) 是 egui 在显示器自身缩放比例之上的缩放因子:每个窗口都以点为单位布局,因此它会按比例放大;如果大于屏幕,则会滚动。

数据

下载列表和设置以原子方式保存到数据文件夹 (downloads.json):Windows 上的 %APPDATA%\dannexdownloadmanager\,Linux 上的 ~/.local/share/dannexdownloadmanager,macOS 上的 ~/Library/Application Support/dannexdownloadmanager,便携式副本旁边的 data 文件夹,或 MDM_DATA_DIR (mdm_ipc::data_dir)。浏览器主机读取相同的文件以获取捕获规则,因此“选项”中的更改适用于下一个捕获的下载。

登录凭据(debrid 账户、“站点登录”和代理的密码)存储在系统的密钥链中 (secrets.rs, #44):Windows 凭据管理器 (win32.rs),Linux 上的 Secret Service 或 macOS 密钥链 (unix.rs)。设置中保留一个 keychain:<service>/<scope>/<key> 引用,仅在密钥链确认凭据后写入;如果没有密钥链(或密钥链已锁定,且从未为 DDM 解锁),凭据仍像以前一样保存在设置中。

下载的服务器位置 (#140) 是其连接到的地址所在国家/地区,在此计算机上通过 mdm-geo 的表格查找(countries.rs 以界面语言命名);发布任务会根据当月数据重新构建表格 (tools/geo/build.py --release)。

浏览器集成

page ──► extension ──native messaging──► mdm-nmhost ──ipc──► app

扩展程序会询问主机要获取哪些文件类型,对照这些类型检查每个下载,并且仅在应用程序接受后才取消浏览器的下载;否则浏览器会保留它,扩展程序会说明原因。

同一次回答还带有选项 → 常规中的按键(keys:page.js 据此判断是否拦截点击,把链接留给浏览器或强制交给应用)和要显示的右键菜单项(menu:这些项更改时,background.js 会重新生成菜单);是否可以显示视频按钮的回答则带有下载面板的设置(panel:在视频或音频播放器上、最短时长、起始角落)。它们的名称和默认值来自 mdm_ipc::capture,取自应用保存的设置。扩展会在浏览器窗口重新获得焦点时(距上次询问几秒后)、页面开始加载时(15 秒)以及下载时(一分钟)再次询问。

工具栏弹出窗口中的下载列表(暂停、恢复、打开文件夹)和按钮上的数字,是自动化 API 的 list 和各项操作,通过设置了 browser 的宿主程序请求:无论 API 的开关如何,应用都会回答这些请求,就像回答视频按钮的画质菜单一样,且宿主程序绝不会为此启动应用。扩展只在弹出窗口打开或有下载运行时才会询问。

主机仅服务于 DDM 自己的扩展程序。其 ID 位于一处,mdm_ipc::extension (crates/ipc/src/extension.rs):未打包副本的 ID(UNPACKED_ID,来自清单的公钥),Chrome 网上应用店的 ID(STORE_ID,用商店自己的密钥签名:pack.ps1 将清单的密钥排除在商店副本之外),Firefox 附加组件的 ID(FIREFOX_ID)及其 addons.mozilla.org 页面;Edge 和 Opera 商店的 ID 是占位符,在扩展程序在那里上架之前不会提供。主机使用这些 ID 写入每个浏览器的清单,应用程序在未打包副本之前提供商店副本(“添加到 Chrome”、“添加到 Firefox”)。

远程控制

phone ──HTTPS (paired token)──► mdm-remote ──ipc::Sink──► app (answer, remote_add)

--headless(headless.rs, #157) 运行相同的 App 而不使用 eframe:一个循环在裸 egui::Context 上调用其 tick(logic 在每一帧运行的内容),由命令通道唤醒,从不调用其 ui;命令由远程控制添加(无窗口)。Dockerfile 和 docker/(Compose、Unraid 的模板)在服务器上运行它(server.md)。

服务器在应用的 Tokio 运行时上运行,每个本地网络地址一个监听器。每个请求都经过检查(Host、Origin、令牌),转换为标记为 mdm_ipc::Command 的 remote(请求行无法设置的字段),并通过与命令行相同的通道传递给应用;应用在下一帧响应它,就像响应自动化 API 一样。其页面内置于 crates/remote/web 中,其文本来自应用的目录 (remote.rs)。

翻译

UI 显示的每个文本都通过 crate::i18n(craft-i18n 目录,i18n/<locale>.tsv)。tools/i18n/extract.py 从源代码重建 i18n/en.tsv,并为每个文本附上翻译人员的注释(它是什么,在哪里显示,其占位符)。tools/i18n/translate.py 填充其他目录中缺少的内容(标记为 #, machine 的行),遵循每种语言的样式指南(i18n/style/)和词汇表;人工审核过的行永远不会被替换,CI(reviewed_guard.py)会使删除行的更改失败。网站有自己的目录(i18n/site/,tools/website/translate_site.py)。

图片

应用图标由几何图形绘制(tools/icon/dannex_logo.py;build_icon.py 写出每种尺寸,16 到 48 px 的尺寸按整像素手工定位)。凡是显示它的地方,都取与屏幕上大小相符的那一张(logo.rs):在 Windows 上,每个窗口的标题栏和任务栏图标按其所在显示器的缩放比例选取(win32::crisp_icons,窗口移到另一台显示器时也保持这一点),托盘图标则按任务栏的缩放比例选取。视图 → DDM 托盘图标可以让它以全彩显示(3D 样式),或只显示用任务栏文字颜色绘制的标志(扁平样式:深色任务栏上为白色,浅色任务栏上为深色;在 macOS 上为模板图像),并在下载运行时于其底部显示一条细进度条。

帮助页面的图片 (docs/images/help/) 来自一个列表,tools/shots/shots.toml:tools/shots/make.py 通过 DDM 自己的 /show <window> 命令行在屏幕外的测试实例中打开每个窗口,从窗口的可访问性树中裁剪和注释,并写入无损 WebP;make.py check (CI) 保持列表、页面和文件同步。已发布的图片是在 GitHub 的 Windows 运行器上拍摄的 (docs-shots.yml)。

贡献者

tools/contributors.py从 GitHub 的公共 API 读取谁发起了拉取请求和问题,以及谁发表了评论(维护者、Claude 和机器人除外),用于感谢他们的所有地方:网站主页、/contributors.html 和新闻页面上的每个版本(build.py,在每个构建中),每个版本的发布说明(release.yml,自上一个版本以来活跃的人员)以及 README(python tools/contributors.py readme 在每个版本准备时:其圆形照片提交在 art/contributors/ 中,因为 GitHub 无法在 README 中将图片设为圆形)。

测试和基准

cargo test针对注入故障(慢速、丢弃和拒绝连接、无范围服务器、文件更改)的 mdm-labserver 运行单元测试和端到端下载。tools/bench 运行已发布的速度比较;其原始数据在 docs/bench/ 中。

窗口的帧是测量出来的,而不是猜出来的(crates/app/src/framestats.rs):MDM_FRAME_STATS=1 每秒记录一次主窗口的重绘次数、其中有多少来自输入、花费多少(主窗口、进度窗口、它们的布局),以及其余的重绘是由哪几行代码请求的;MDM_SYNTHETIC_LIST=10000(配合临时的 MDM_DATA_DIR)会添加相应数量的虚构行;MDM_BENCH_SCROLL=10 让列表自行滚动十秒,并记录各帧的耗时。空闲的窗口除了时钟的帧(每 2 秒一次)外没有别的帧;列表只绘制可见的行。

免费、开源、无广告、无试用版。

下载 Dannex Download Manager