NASTool v2部署指南：从Docker Compose到NAS媒体库自动化

玩 NAS 的朋友多半都经历过这样的场景周末想找部电影先打开下载器添加任务等下载完成后再手动改文件名、拖到媒体库目录最后还要打开 Jellyfin 或 Emby 触发一次扫描。如果资源每周更新这套手动流程就要反复执行。NASTool v2 解决的正是这条“搜索—下载—整理—入库—通知”的自动化链路。本文将围绕 NASTool v2 展开介绍它的核心概念、工作流程和部署方式。重点会放在群晖、飞牛、极空间、绿联这四类常见 NAS 平台的 Docker Compose 部署上并给出完整的初始化配置和排错思路。无论你是刚接触 NAS 的新手还是已经在用 Jellyfin、Emby 的进阶玩家这篇文章都能帮你把媒体库管理这件事理顺。1. NASTool v2 是什么它解决了什么问题1.1 手动媒体库管理的痛点不使用自动化工具时一套完整的媒体库维护流程大致是这样打开下载器搜索资源确认下载。等待下载完成。手动将文件移动到电影或剧集对应的目录。按照“电影名称 (年份)”的规范重命名文件。打开 Jellyfin、Emby 或 Plex手动扫描媒体库。如果文件名不规范媒体服务匹配不到海报和简介还得手动修正。这套流程最大的问题是重复劳动。资源一多每周都要花费大量时间维护。而且手动重命名容易出错一旦命名不规范媒体服务器就无法正确刮削海报、简介、演员等信息整个媒体库的体验会大打折扣。1.2 NASTool v2 的核心定位NASTool 本质上是一个“媒体库自动化管家”它把上面这些手动步骤串联起来形成一条完整的自动化流水线。v2 是项目重新设计后的版本相比 v1 在模块拆分和配置逻辑上有较大调整整体界面和配置方式更偏向“服务化”思维。它的核心能力可以概括为统一检索与订阅将多个索引器/站点聚合在一起统一搜索电影、剧集并支持订阅。资源更新后自动触发下载。下载器管理接管 qBittorrent、Transmission 等下载工具自动添加任务、监控完成状态。媒体库整理根据预设规则将下载完成的文件硬链接或移动到媒体库目录并按规范重命名。媒体服务联动扫描完成后自动通知 Jellyfin、Emby、Plex 刷新媒体库。消息通知通过 Telegram、Bark、微信等渠道推送下载、整理结果。专业一点说NASTool v2 是一个“以媒体资源生命周期管理为核心”的自动化平台。它不替代 Jellyfin 这类媒体服务器而是作为上游调度层把下载器和媒体库之间的断点补齐。1.3 适用场景与读者画像NASTool v2 特别适合下面几类用户有 NAS但总觉得“下载—整理—入库”太麻烦的人。已经在用 Jellyfin 或 Emby但媒体库命名混乱、海报匹配不上的人。下载内容较多希望订阅后自动入库、自动推送通知的人。喜欢折腾 Docker愿意花时间把家庭媒体库做成“全自动流水线”的人。如果你是纯新手第一次接触 NAS 和 Docker本文也会把每一步拆开讲跟着操作即可。2. 核心原理目录规划、硬链接与刮削2.1 一条完整的媒体自动化工作流在动手部署前先把 NASTool 的工作流程讲清楚。了解整条链路后面配置目录和模块时就不会乱。订阅/手动搜索 ↓ NASTool 聚合索引器选择最佳资源 ↓ 自动下发任务到 qBittorrent / Transmission ↓ 下载完成 ↓ NASTool 监听下载器状态执行整理规则 ↓ 硬链接/复制/移动至媒体库目录按规范重命名 ↓ 调用 TMDB 等元数据服务刮削海报、简介、演员信息 ↓ 通知 Jellyfin / Emby / Plex 刷新媒体库 ↓ 推送消息到 Telegram / Bark / 微信这里最关键的三个环节是下载器监听、目录整理、媒体库刷新。任何一环断了自动化都不完整。2.2 目录规划与硬链接NASTool v2 对目录规划非常敏感。部署之前一定要先想清楚目录结构。推荐结构如下/nas/media ├── downloads # 下载暂存目录 │ ├── movies │ └── tv ├── movies # 电影媒体库目录最终入库 ├── tv # 剧集媒体库目录最终入库 ├── anime # 动漫媒体库目录可选 └── docker ├── nastool # NASTool 配置目录 ├── qbittorrent # 下载器配置目录 └── jellyfin # 媒体服务配置目录为什么下载目录和媒体库目录要放在同一个存储空间这与“硬链接”机制有关。硬链接Hard Link可以让多个目录项指向同一个文件数据块。也就是说downloads 里的文件和 movies 里的文件虽然路径不同但占用的是同一份磁盘空间。这样既满足了媒体库的结构要求又不会因为复制文件而翻倍占用硬盘空间同时下载任务还可以继续做种。如果下载目录和媒体库目录跨了文件系统比如一个在磁盘 1、一个在磁盘 2硬链接就无法建立。NASTool 在这种情况下会退化为复制或移动要么多占用空间要么无法保留做种文件。这是新手最常踩的坑。2.3 媒体信息刮削与命名刮削Scraper是指媒体服务器或整理工具通过文件名去匹配 TMDB、TheTVDB、豆瓣等元数据站点拉取海报、简介、评分、演员信息。刮削的前提是文件名规范。NASTool 会自动把文件重命名为类似下面的格式电影/movies/流浪地球2 (2023)/流浪地球2 (2023).mkv 剧集/tv/三体 (2023)/Season 1/三体 (2023) - S01E01.mkv这种“电影名 (年份)”和“SxxExx”格式是 Jellyfin、Emby、Plex 都能很好识别的标准。文件命名越规范刮削成功率越高这是整个媒体库体验的基础。2.4 为什么选择 Docker 部署NASTool v2 对运行环境有一定要求尤其在群晖、飞牛、极空间、绿联这类 NAS 上Docker 是成本最低、最统一的方式不污染 NAS 原生系统容器随时可以删除重建。四个平台的部署逻辑一致只需要调整路径映射。升级、回滚方便配置文件在宿主机上容器重新创建即可。可以锁定镜像版本避免自动升级导致配置不兼容。这也是本文重点讲解 Docker Compose 部署的原因。3. 环境准备与版本说明3.1 硬件与系统要求NASTool v2 本身对硬件要求不高主要占用集中在下载器和媒体服务端。如果你还要跑 Jellyfin 的硬件转码那 CPU 的核显或独立显卡就比较重要。最低参考配置双核 CPU2GB 以上内存。至少一个存储空间用于放置下载目录和媒体库。能够正常安装 Docker 服务的 NAS 系统。注意如果你使用群晖建议 DSM 7.2 及以上Container Manager 对 Docker Compose 的支持更完善。飞牛 fnOS、极空间、绿联的 Docker 应用在各自系统内已经内置无需额外安装。3.2 四类平台部署方式对比NAS 平台Docker 管理入口存储路径习惯注意事项群晖 DSMContainer Manager套件中心安装/volume1/xxx路径受共享文件夹权限控制飞牛 fnOS系统自带 Docker/vol1/1000/xxx 或 /vol1/xxx有图形化管理界面路径直观极空间自带 Docker 管理器在界面中选择存储空间注意容器网络模式建议 bridge绿联 UGOS Pro自带 Docker 应用/volume1/xxx与群晖路径习惯相近版本说明NASTool v2 的镜像 tag 会随项目发布节奏变化不同时间段可能使用不同的镜像仓库或版本号。本文的配置以常见环境为例重点演示配置思路具体镜像 tag 请以你实际拉取的镜像仓库说明为准。3.3 配套软件栈推荐NASTool v2 不是单打独斗通常需要搭配以下工具下载器qBittorrentWebUI 默认端口 8080。媒体服务器JellyfinWebUI 默认端口 8096或者 Emby、Plex。元数据站点TMDB API Key刮削电影、剧集信息必须。消息推送BarkiOS、Telegram、Server 酱等。下面实战中我会以 qBittorrent Jellyfin 为例展示一套最小可用组合。4. Docker Compose 部署 NASTool v24.1 创建项目目录在 NAS 的存储空间上创建如下目录结构以群晖为例路径前缀按实际调整/volume1/docker/nastool/config /volume1/docker/qbittorrent/config /volume1/docker/jellyfin/config /volume1/media/downloads/movies /volume1/media/downloads/tv /volume1/media/movies /volume1/media/tv如果是飞牛路径前缀可能是/vol1/1000极空间和绿联在 Docker 界面选择目录即可。建议先把目录建好再写 compose 文件这样映射时不会迷路。4.2 编写 docker-compose.yml我习惯把 NASTool、qBittorrent、Jellyfin 放在同一个 Compose 项目中三个容器可以一起管理配置起来也更清晰。下面是完整示例。文件路径/volume1/docker/docker-compose.ymlservices: nastool: image: nastool/nas-tools:latest container_name: nastool restart: unless-stopped ports: - 3000:3000 environment: - PUID1000 - PGID1000 - TZAsia/Shanghai - NASTOOL_AUTO_UPDATEfalse volumes: - /volume1/docker/nastool/config:/config - /volume1/media:/media depends_on: - qbittorrent - jellyfin qbittorrent: image: lscr.io/linuxserver/qbittorrent:latest container_name: qbittorrent restart: unless-stopped ports: - 8080:8080 - 6881:6881 - 6881:6881/udp environment: - PUID1000 - PGID1000 - TZAsia/Shanghai volumes: - /volume1/docker/qbittorrent/config:/config - /volume1/media/downloads:/downloads healthcheck: test: [CMD, curl, -f, http://localhost:8080] interval: 30s timeout: 10s retries: 5 jellyfin: image: jellyfin/jellyfin:latest container_name: jellyfin restart: unless-stopped ports: - 8096:8096 environment: - TZAsia/Shanghai - PUID1000 - PGID1000 volumes: - /volume1/docker/jellyfin/config:/config - /volume1/media:/media这里有几个关键点需要解释PUID/PGID容器内进程运行的用户 ID 和组 ID。建议与你 NAS 上的普通用户一致避免容器创建的文件无法被 NAS 上的用户管理。最稳妥的方式是在 NAS 上执行id命令查看当前用户的 UID/GID然后替换。/volume1/media:/media把整个媒体目录挂进容器这样 NASTool 既能管理 downloads 目录也能管理 movies、tv 等媒体库目录。NASTOOL_AUTO_UPDATEfalse关闭自动更新。虽然自动更新方便但 v2 版本的升级可能伴随配置结构变化手动更新更可控。如果需要自动更新可以改为true。depends_on确保 qBittorrent 和 Jellyfin 先启动。但注意它只能控制容器启动顺序不能保证服务完全就绪所以后面配置连接时仍需要手动确认服务已启动。4.3 启动并验证SSH 登录 NAS进入 docker-compose.yml 所在目录执行docker compose up -d等待镜像拉取并启动。然后查看容器状态docker compose ps预期三个容器都是Up状态nastool容器的端口映射为0.0.0.0:3000-3000/tcp。此时浏览器访问http://NAS的IP:3000如果能看到 NASTool 的初始化页面说明容器启动成功。4.4 群晖 NAS 部署要点群晖部署时路径前缀通常是/volume1或/volume2取决于你的存储空间。打开 File Station在共享文件夹docker下创建子目录即可。注意容器权限问题。群晖的 Container Manager 创建的容器默认以 root 运行但你在 compose 中指定了PUID/PGID容器内就会以普通用户身份创建文件。为了不让权限混乱建议在控制面板中创建一个专用用户比如nas。使用该用户的 UID/GID 作为PUID/PGID。给docker和media共享文件夹设置该用户的读写权限。这样无论是 NASTool 整理文件还是你通过 SMB 访问媒体库权限都是一致的。4.5 飞牛 fnOS 部署要点飞牛 fnOS 自带 Docker 图形界面使用起来比较友好。路径方面飞牛的主存储通常对应/vol1/1000其中1000是第一个用户目录。如果你把配置文件放在文件管理的docker目录下映射路径可能是/vol1/1000/docker/nastool:/config。飞牛部署有几个常见注意点飞牛 Docker 界面创建 Compose 项目时会自动识别目录名称路径要仔细核对。如果发现下载完成后无法硬链接优先检查下载目录和媒体库目录是否在同一个存储空间。飞牛系统防火墙默认规则如果比较严格需要放行 3000、8080、8096 等端口否则局域网无法访问。4.6 极空间部署要点极空间的 Docker 管理器提供了比较完整的 Compose 编辑界面。存储空间路径不需要手动输入可以在界面中选择目录系统会自动生成对应的挂载路径。极空间部署建议网络模式建议选择 bridge然后配置端口映射。不要把容器设置为 host 模式除非你清楚端口冲突风险。极空间的文件目录和群晖不同建议直接使用应用内的“目录选择器”来选择/media和/config对应的宿主机路径而不是手动输入。极空间的 Docker 默认存储路径可能与你的数据盘不同务必确认配置目录落在容量充足的数据盘上。4.7 绿联部署要点绿联 UGOS Pro 的 Docker 应用和群晖比较像路径以/volume1开头。在绿联的共享文件夹中创建docker目录和media目录然后按照相同的 compose 文件修改路径前缀即可。绿联需要注意绿联的文件管理器对权限控制比较严格如果容器创建的文件在 SMB 下不可见检查共享文件夹是否勾选了正确权限。绿联部分型号的 Docker 应用对 Compose 支持程度可能随系统版本变化如果界面中没有 Compose 入口可以先选择镜像手动创建容器参数与本文一致。4.8 国内拉取镜像慢的解决办法NAS 在国内拉取 Docker Hub 镜像经常遇到超时或速度慢的问题。常见解决方式是配置镜像加速器。以飞牛 docker 为例在 Docker 的镜像加速配置中可以添加国内可用的 registry mirror 地址。不同加速地址的可用性会随时间变化建议在部署前先搜索当前可用的镜像加速服务。另一个可选方案是使用docker pull时通过其他镜像仓库中转例如部分云厂商提供的镜像仓库。这里不展开核心原则是先把镜像拉下来部署流程才会顺利。5. 初始化配置与媒体库联调5.1 首次进入后台打开 NASTool v2 后台后第一件事是设置语言、时区和基础参数。v2 的界面模块划分比较清晰左侧菜单通常包括基础设置索引器下载器媒体库订阅消息通知不同版本的菜单名称可能略有差异但核心配置逻辑一致。5.2 配置 qBittorrent 下载器进入下载器配置页选择 qBittorrent填写地址http://qbittorrent:8080 或 http://NAS的IP:8080 用户名admin 密码你设置的 WebUI 密码这里有一个网络细节。如果你在 compose 文件中没有给容器指定network_mode: host三个容器默认在同一个 bridge 网络中。此时 NASTool 容器访问 qBittorrent应该使用容器名qbittorrent而不是 IP例如http://qbittorrent:8080容器名在 Docker 内部 DNS 中可以自动解析这样即使 NAS 重启后 IP 变化配置也不会失效。建议先通过浏览器确认 qBittorrent WebUI 可以登录再回来填配置。qBittorrent 首次登录用户名是admin密码会随机生成在容器日志中可以找到也可以先手动进入 WebUI 修改密码。5.3 配置 Jellyfin 媒体库Jellyfin 首次启动后需要进行初始化设置。进入 Jellyfin 后台添加媒体库电影库路径填写/media/movies剧集库路径填写/media/tv注意这里填的是容器内路径因为 Jellyfin 容器把宿主机的/volume1/media映射成了/media。然后在 NASTool 的媒体库配置中选择 Jellyfin填写 Jellyfin 的地址和 API Key。API Key 在 Jellyfin 后台的“控制台 → API 密钥”中生成。配置完成后NASTool 在整理完文件后就会主动调用 Jellyfin 的接口刷新媒体库不需要再手动触发扫描。5.4 配置目录映射和整理规则在 NASTool 的目录配置中需要明确告诉它下载完成后的文件从哪里来即/media/downloads。电影整理到哪里即/media/movies。剧集整理到哪里即/media/tv。这里的路径都是容器内路径。如果你在主配置中已经将宿主机/volume1/media映射为容器内/media那么所有目录都放在/media下面管理即可非常直观。整理规则建议电影按“电影名称 (年份)”建目录。剧集按“剧集名称 (年份)/Season xx”建目录。动漫单独分目录避免与真人剧混合。如果资源包含中文字幕确认 NASTool 配置了字幕文件的移动规则避免字幕丢失。5.5 订阅与自动整理验证配置完成后做一次端到端验证。在 NASTool 中搜索一个已知资源确认能搜到结果。添加到下载任务。等待 qBittorrent 下载完成。观察 NASTool 是否自动整理文件到/media/movies或/media/tv。打开 Jellyfin检查是否自动出现新入库的电影或剧集。查看通知渠道是否收到推送。如果每一步都成功你的媒体库自动化链路就已经跑通了。6. 常见问题与排查思路6.1 容器启动后无法访问后台问题现象常见原因解决思路浏览器无法打开 3000 端口端口映射未生效执行docker compose ps查看端口映射状态页面能打开但一直转圈容器初始化尚未完成等待 1-2 分钟查看容器日志局域网其他设备无法访问NAS 防火墙拦截放行 3000 端口或检查网络 AP 隔离排查命令docker logs -f nastool如果看到正常启动日志说明应用本身没问题问题大概率在端口映射、防火墙或网络环境。6.2 硬链接失败文件被复制或移动这是最常见的目录规划问题。检查思路下载目录和媒体库目录是否在同一个存储空间。在容器内查看两个目录是否属于同一文件系统docker exec nastool df /media/downloads docker exec nastool df /media/movies如果两个路径的Filesystem列不同说明跨了文件系统硬链接必然失败。这时候只能调整目录结构让下载目录和媒体库目录在同一存储空间内。6.3 媒体识别不出海报和简介问题现象常见原因解决思路新入库的电影没有海报缺少 TMDB API Key申请 TMDB API Key 并填入配置海报之前有现在没有了元数据站点访问异常检查网络和 DNS 设置部分电影匹配错误文件名不规范手动修正命名或开启 NASTool 更严格的重命名规则需要强调媒体刮削依赖 TMDB 等外部元数据服务如果你的网络环境无法稳定访问这些服务刮削就会失败。这不是 NASTool 本身的问题而是网络可达性问题。6.4 下载完成后不自动整理先从日志看NASTool 的日志系统会记录下载器状态和整理任务。排查顺序下载器配置是否保存成功测试连接是否通过下载任务是否真的在 qBittorrent 中完成且处于做种状态目录映射是否包含下载目录和媒体库目录是否配置了同步目录或订阅任务如果下载器已经完成但 NASTool 没有动作可以尝试手动触发一次“待整理”任务看日志中的具体报错。6.5 自动更新后配置异常如果你启用了NASTOOL_AUTO_UPDATEtrue某次更新后可能发现配置页字段变了或者部分功能不可用。建议做法更新前备份/docker/nastool/config整个目录。更新后留意项目发布说明确认配置结构是否有破坏性变更。如果异常无法解决回退到之前的镜像 tag并把 config 恢复回去。7. 最佳实践与工程建议7.1 版本锁定与升级策略Docker 镜像不要长期使用latest标签尤其在生产环境。latest每次重新拉取都会漂移到新版本一旦遇到破坏性更新排错成本很高。建议正式使用后把镜像 tag 固定到当前稳定版本。升级时按计划进行备份 config 目录。修改 compose 文件中的镜像 tag。执行docker compose up -d。观察日志和功能确认无异常后再继续使用。7.2 目录设计与命名规范家庭媒体库的目录设计建议从一开始就定好规范下载目录和媒体库目录放同一存储空间确保硬链接可用。电影、剧集、动漫分开管理。命名统一采用“标题 (年份)”和“SxxExx”。字幕文件与视频文件同名方便播放器自动加载。这些规范不仅服务于 NASTool也能让你未来迁移到其他工具时少踩坑。7.3 权限与安全边界容器权限要遵循最小化原则使用普通用户的PUID/PGID避免容器内使用 root 产生大量 root 文件。不要让容器挂载整个宿主机根目录只挂载需要访问的目录。qBittorrent 的 WebUI 一定要修改默认密码并避免暴露到公网。如果需要在公网访问建议使用 NAS 厂商提供的安全隧道或反向代理并开启 HTTPS不建议直接把端口映射到公网。7.4 备份与恢复NASTool 的配置都在/config目录中这个目录是备份的核心。建议把以下内容纳入定期备份/docker/nastool/config/docker/qbittorrent/config/docker/jellyfin/config如果有自定义的整理规则、索引器配置也一并备份恢复流程很简单在新环境中重新创建容器把 config 目录恢复再启动即可。注意 PUID/PGID 要与之前一致否则可能出现文件权限问题。7.5 版权与合规提醒NASTool 本身是一个媒体库管理工具它不生产内容也不主动下载内容。在使用过程中请确保你只管理自己拥有合法权利的内容。媒体刮削需要访问 TMDB 等外部元数据服务申请和使用 API Key 时请遵守对应服务的使用条款。不要把 API Key 提交到公开仓库或博客中。8. 总结NASTool v2 的价值不是让你“少点几次鼠标”而是真正把媒体库维护从“手动运维”变成“自动流水线”。它把索引器、下载器、媒体库和通知渠道串联在一起你只需要负责订阅内容剩下的搜索、下载、整理、入库、推送都由系统自动完成。本文从核心概念讲到目录规划从 Docker Compose 部署讲到四个 NAS 平台的具体适配最后给了一套完整的初始化配置流程和排错清单。如果你是第一次尝试建议先在一台备用设备上把整套流程跑通再迁移到主力 NAS 上长期使用。接下来可以继续研究的方向NASTool 的订阅规则编写实现“新剧自动追更”。针对不同资源类型的整理规则调整。Jellyfin 硬件转码与播放链路优化。多盘 NAS 场景下的目录分层策略。媒体库自动化是一条值得细水长流打磨的链路希望这篇文章能帮你把第一步走得稳一点。