纳存下载 (NASave-DL)

纳万物，存光影。 One-click to NAS, Save it all.

「纳存」是运行在 NAS 上的多合一媒体下载服务器。它将强大的 yt-dlp (视频) 和 gallery-dl (图集) 封装成简单的 API 接口，让你能通过快捷指令、浏览器扩展或订阅功能，一键将互联网媒体资源自动保存到 NAS，自动整理归档，完美兼容飞牛影视/相册、Emby、immich 等媒体库的元数据。

⚠️ 音乐下载因为版权问题比较繁琐，暂不考虑整合。

✨ 主要功能

• 🎬 视频下载：支持 YouTube、B 站等数千个视频网站

• 📷 图集下载：支持 Instagram、X (Twitter) 等数百个图片网站

• 🔧 开箱即用：支持 Web 界面管理模板、Cookies 等配置

• 🚀 自动订阅：自动下载频道主页、播放列表、收藏夹的内容

• 🔁 自动整理：自动按网站、作者等分类归档，写入元数据

• 🔔 通知推送：通过 Bark、Server酱³ 接入系统原生通知渠道

• ⚡️ API 驱动：提供标准接口，方便对接快捷指令等自动化

• 🌐 跨平台：现已支持 Docker、飞牛、Mac、PC、安卓客户端 🎉（鸿蒙考虑中）

❤️ 支持项目

• 打赏鼓励：支持我开发更多有趣应用
• 互动群聊：加入 💬 QQ 群 可在线催更
• 更多内容：访问 ➡️ 谢週五の藏经阁

微信

支付宝

🚀 快速开始

推荐 Docker 或 uv 方式在 NAS、VPS 部署，它们能自动处理依赖且稳定性最高。

---

🐳 方式一：Docker 部署 (推荐，适合 NAS)

官方镜像已发布至 GitHub和 Docker hub，支持 x64 和 arm64 架构。

使用 Docker Compose 启动：

services:
  nasave-dl:
    image: ghcr.io/juneix/nasave-dl
    # 备用镜像: docker.1ms.run/juneix/nasave-dl
    container_name: nasave-dl
    network_mode: host
    restart: always
    environment:
      - TZ=Asia/Shanghai
      - PORT=8888 # 自定义端口
    volumes:
      - ./data:/app/data # 配置文件、cookies 文件等
      - /volume1/downloads:/downloads # 下载文件夹

---

⚡ 方式二：uv 方式 (适合开发者)

通过 uv 环境一键安装，无需手动配置 Python 环境，且能获得全局命令。

# 1. Linux 通用安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 安卓 Termux 安装 uv
pkg install uv
export ANDROID_API_LEVEL=24

# 2. 安装运行 nasave-dl
uv tool install git+https://github.com/juneix/nasave-dl.git
uv tool update-shell
nasave-dl
# 无头环境（Linux/Termux）推荐：
# nasave-cli

# 备用：源码直接运行（不安装全局命令）
# git clone https://github.com/juneix/nasave-dl.git
# cd nasave-dl
# uv sync
# uv run launcher.py
# 无头环境：
# uv run app/cli.py

命令速查 (uv tool 安装)

命令	说明
nasave-dl	前台 GUI 启动（默认）
nasave-cli	前台无图形启动（无头 Linux / Termux 推荐）
nasave-dl start|stop|status|restart|update	后台 GUI 进程管理
nasave-cli start|stop|status|restart|update	后台无图形进程管理
--host/--port	默认 host=0.0.0.0，port=8888，可在 start 或 nasave-cli 追加
PID / 日志	~/.cache/nasave-dl/（或 $XDG_CACHE_HOME/nasave-dl/）

默认数据目录 / 下载目录

不同运行方式的默认目录如下：

运行方式	配置数据目录	默认下载目录
Docker	/app/data	/downloads
源码运行 (uv run ...)	<项目根目录>/data	<项目根目录>/downloads
uv tool install Linux	~/.local/share/nasave-dl	~/Downloads/nasave-dl
uv tool install Termux	~/.local/share/nasave-dl	~/storage/downloads/nasave-dl
macOS 打包版	应用同目录/data	~/Downloads/NASave-DL
Windows 打包版	应用同目录/data	应用同目录/downloads

如果 Termux 未执行过 termux-setup-storage，或默认下载目录不可写，会自动回退到 ~/.local/share/nasave-dl/downloads。

环境变量覆盖

如需自定义目录，可在启动前设置：

export NASAVE_DATA_DIR="$HOME/.local/share/nasave-dl"
export NASAVE_DOWNLOAD_ROOT="$HOME/Downloads/nasave-dl"
nasave-cli

这两个环境变量只会覆盖本地运行时目录，不影响 Docker、macOS 打包版和 Windows 打包版的既有业务逻辑。

---

💻 方式三：桌面客户端 (适合普通用户)

直接从 Releases 下载打包好的版本。

🍎 macOS (.dmg)

• 安装: 打开 .dmg 文件并将 Nasave-dl 拖入 Applications。
• ⚠️ 安全警告: 由于我没钱弄数字签名，首次打开可能提示“无法验证开发者”或“镜像损坏”。
• 解决方法:
  1. 打开“系统设置” -> “隐私与安全性” -> 找到 Nasave-dl 并点击 “仍要打开”。
  2. 或在终端运行 sudo xattr -rd com.apple.quarantine /Applications/Nasave-dl.app。

🪟 Windows (.exe)

• 安装: 下载 Nasave-dl.exe 即可直接运行。
• ⚠️ 安全警告: 由于打包机制原因，部分杀毒软件可能会误报；若确保文件来源可信，可加入白名单。

---

🛠️ 技术栈 (Technical Stack)

纳存采用高度模块化、轻量化的技术拼装，旨在保证 NAS 运行效率的同时提供极致的交互体验：

• 后端 (Backend):

  • FastAPI: 基于 Python 3.10+ 的极速异步 Web 框架，负责 API 路由与任务调度。
  • SQLAlchemy + aiosqlite: 异步 SQLite 引擎，零配置实现数据持久化。
  • yt-dlp & gallery-dl: 核心下载引擎，支持全平台媒体深度解析。
  • uv: 采用现代 Python 包管理工具，提供闪电般的依赖同步与环境隔离。

• 前端 (Frontend):

  • Tailwind CSS: 现代化的实用类样式表，提供高质感的 UI 响应式布局。
  • Alpine.js: 轻量级 JavaScript 框架，实现任务列表的实时状态监听与 UI 组件逻辑。
  • HTMX: 实现局部动态刷新（如日志加载），无需刷新整页即可完成复杂交互。
  • Lucide Icons: 精致的矢量化图标系统。

🏗️ 项目架构

graph TD
    User((用户)) <--> Web[纳存控制台 - Alpine.js/HTMX/Tailwind]
    Web <--> API[FastAPI 后端服务]
    API <--> DB[(SQLite 数据库)]
    API --> YTDL[yt-dlp 视频引擎]
    API --> GDL[gallery-dl 图集引擎]
    YTDL --> Storage[(NAS 存储/downloads)]
    GDL --> Storage

Loading

nasave-dl/
├── app/               # 后端核心逻辑 (FastAPI 路由, 引擎调用, 数据库模型)
├── web/               # 前端 UI 代码 (HTML 模板, 静态资源, Tailwind 配置)
├── data/              # 持久化存储 (数据库 data.db, 配置文件 settings.json, Cookies)
├── downloads/         # 默认媒体下载根目录
├── launcher.py        # 桌面端 (Mac/Win) 托盘启动器入口
├── pyproject.toml     # uv 依赖定义
├── Dockerfile         # 极简镜像构建脚本
└── docker-compose.yml # 容器化部署编排

API 参考

以下是服务提供的完整 API 列表。所有 API 返回格式均为 {"code": 0, "msg": "success", "data": ...}。

任务管理（jobs）

方法	路径	描述
GET	/api/jobs	获取任务列表 (支持 limit 参数)
POST	/api/jobs	创建下载任务 (需 url, tpl_id)
DELETE	/api/jobs/{id}	删除任务 (参数 delete_file=true 可同时删除文件)
DELETE	/api/jobs	清空所有任务记录

模板管理（tpl）

方法	路径	描述
GET	/api/tpl	获取所有模板 (含预设)
POST	/api/tpl	创建新模板
PUT	/api/tpl/{id}	更新模板信息
DELETE	/api/tpl/{id}	删除模板

系统与配置（sys）

方法	路径	描述
GET	/api/sys	获取系统信息 (存储空间, 版本号)
GET	/api/path	列出下载目录下的子文件夹
GET / PUT	/api/cfg	获取/保存全局设置 (代理等)
GET / POST	/api/msgs	获取/保存通知设置
POST	/api/debug/msgs	发送测试通知
GET / POST	/api/auth	获取/保存 Cookies (Netscape 格式)