NasTool v2 部署指南：群晖/飞牛/极空间/绿联 NAS 媒体库自动化

NasTool v2 这个项目，很多玩 NAS 的人应该都听过，但真正用起来的人可能并不多。这次我们直接来看 NasTool v2 到底是什么、能做什么，以及它在群晖、飞牛、极空间、绿联这些主流 NAS 上要怎么部署、怎么用。

简单说，NasTool v2 是一个 NAS 媒体库自动化管理工具。它解决的是这类问题：你的 NAS 上装了下载工具，也装了 Jellyfin、Emby 或 Plex 这样的媒体服务器，但资源下载完之后需要手动整理、手动改名、手动刮削海报和简介，资源多了以后非常浪费时间。NasTool v2 把订阅、下载、识别、整理、刮削、通知这一整条流程串起来，让媒体库的维护尽量自动化。

它最核心的几个特点：支持多平台 Docker 部署，群晖、飞牛、极空间、绿联都能跑；具备资源订阅和自动下载能力；能对接 QBittorrent、Transmission 等常见下载器；能联动 Jellyfin、Emby、Plex 进行媒体库自动更新；自带通知推送，可以配合微信、Tg、Server酱等渠道；同时提供 Web 管理界面和接口服务，适合二次开发和第三方工具对接。

这篇文章会演示 NasTool v2 在常见 NAS 上的 Docker 部署流程，然后从基础配置、功能测试、接口调用、资源占用、常见问题排查这几个维度展开。如果你正在用群晖、飞牛、极空间或绿联，并且想把自己的影音库整理流程自动化，这篇文章可以直接收藏。

1. 核心能力速览

这里要特别说明一点：NasTool v2 更像是一个流程调度和文件管理工具，它本身不产生内容。所以实际部署时，下载工具、媒体服务器、媒体资源来源都需要你自己准备，并且确保使用过程符合相关法律法规和平台规则。

2. 适用场景与使用边界

从实际使用场景来看，NasTool v2 最合适的人群其实是两类：一类是 NAS 里已经存了大量影片、剧集，但目录乱、命名乱、Jellyfin 刮削经常失败的用户；另一类是希望建立“订阅 -> 自动下载 -> 自动整理 -> 媒体库自动更新”完整链路的自动化玩家。

它能解决的具体问题包括：

• 手动下载资源后不知道放在哪个目录，导致媒体库识别失败。
• 文件命名不规范，刮削不到海报和简介。
• 没有定时扫描机制，新资源入库后 Jellyfin 不自动刷新。
• 多用户家庭场景下，没有统一的通知和审批入口。

但也有不适合的场景。如果你的 NAS 配置非常低，比如只有 1G 内存，同时还要跑下载工具、Jellyfin、数据库等多个容器，那 NasTool v2 跑起来会比较吃力，建议先扩大内存或精简容器数量。另外，如果你只是想手动管理少量文件，不愿意折腾配置，那这个工具带来的收益也不明显，反而会增加维护成本。

合规边界必须说清楚。NasTool v2 提供了订阅、下载器联动、文件整理等能力，这些能力本身是中性的，但使用这些能力时的内容来源、下载行为、版权归属由使用者自己负责。请确保你订阅、下载、整理和传播的媒体内容具备合法授权，不要使用该工具规避版权保护机制，也不要用它处理涉及他人隐私的文件。在配置通知推送、API 接口、远程访问时，注意保护自己的账号和 token，避免泄露到公网。

3. 环境准备与前置条件

部署 NasTool v2 之前，先检查 NAS 环境是否满足基本条件。

3.1 系统要求

无论是群晖 DSM、飞牛 fnOS、极空间 ZOS 还是绿联 UGOS Pro，只要系统支持 Docker，理论上都能安装 NasTool v2。各个品牌在 Docker 支持上略有差异：

• 群晖：DSM 7.x 使用 Container Manager，DSM 6.x 使用 Docker 套件。
• 飞牛：fnOS 自带 Docker 管理界面，操作相对直接，热门搜索里也有不少用户在飞牛上装各种容器，环境比较成熟。
• 极空间：自带 Docker 功能，可以在 Docker 页面中新建容器，部分型号系统版本差异较大，建议先确认 Docker 版本。
• 绿联：UGOS Pro 内置 Docker，支持 docker-compose 和图形化创建容器。

更稳妥的判断是：先确认你的 NAS 系统能正常拉取 Docker 镜像并创建容器，再继续下一步。如果连 Docker 基础环境都没打通，先解决 Docker 本身的问题。

3.2 硬件与存储

从部署角度看，NasTool v2 的硬件压力主要来自：容器中的 Python 进程、数据库文件、日志写入、定时任务执行。它比影音转码服务的占用低很多，但如果你同时跑下载器、媒体服务器等多个容器，整体资源占用会叠加。

建议给 NAS 预留至少 2 核 CPU、4G 内存的空闲资源，磁盘空间方面预留 10G 以上给 NasTool 的配置、日志和数据库，后续刮削缓存和下载暂存目录再单独规划。实际占用需要以本机部署后的监控数据为准，不同版本、不同任务频率差异很大。

3.3 网络与端口

NasTool v2 的 Web 管理界面需要一个端口对外提供服务。如果 NAS 上已经有很多服务，注意避免端口冲突。常见的做法是在创建容器时手动指定一个不冲突的高位端口，比如 3000、8088、8888 等。默认端口以项目官方文档为准，不要在未确认的情况下直接占用 80、443 这类常用端口。

另外，媒体刮削需要访问在线媒体数据库，部署前要确认 NAS 的网络能正常访问这些数据源。如果刮削失败，先检查网络连通性和 DNS 设置，再看日志定位具体请求失败原因。

4. Docker 安装部署与启动

4.1 通用 Docker 部署思路

NasTool v2 的安装步骤在群晖、飞牛、极空间、绿联上大同小异，核心都是：拉取镜像 -> 创建目录 -> 配置端口和路径映射 -> 启动容器 -> 访问 Web 界面。

先创建数据目录，一般建议建立独立的文件夹用于存放 NasTool 的配置、日志和数据库，方便后续备份和升级。例如在 NAS 的 docker 目录下创建nastool文件夹。

然后准备 docker-compose 文件或 docker run 命令。因为没有你的具体镜像版本和项目参数，下面给的是通用模板，实际使用时需要按项目官方文档替换镜像名、端口、路径。

version: "3" services: nastool: image: your-nastool-image:latest container_name: nastool restart: unless-stopped ports: - "3000:3000" volumes: - /path/to/nastool/config:/config - /path/to/downloads:/downloads - /path/to/media:/media environment: - TZ=Asia/Shanghai

# 通用 docker run 示例，路径和端口请按实际情况替换 docker run -d \ --name nastool \ --restart unless-stopped \ -p 3000:3000 \ -v /path/to/nastool/config:/config \ -v /path/to/downloads:/downloads \ -v /path/to/media:/media \ -e TZ=Asia/Shanghai \ your-nastool-image:latest

创建容器时要注意三个路径：配置文件目录、下载目录、媒体库目录。这三个路径映射得越清楚，后面配置就越省事。如果你把映射路径搞混，很可能会出现“NasTool 能看到文件但 Jellyfin 看不到”之类的奇怪问题。

4.2 群晖部署要点

群晖上如果使用 DSM 7.x，打开 Container Manager，先拉取镜像，然后在“容器”中创建新容器。做路径映射时，点击“文件夹”下方的“添加文件夹”，把本地的下载目录和媒体目录选进去，分别映射到容器内的/downloads和/media。端口设置里把本地端口改成自己指定的端口，避免和已有服务冲突。

启动容器后，打开http://NAS的IP:端口，如果能正常打开 NasTool 的 Web 界面，说明部署成功。后面做配置时，群晖 NAS 的本地路径和容器路径要分清楚，NasTool 里填写的下载器地址、媒体服务器地址，需要从容器网络的角度考虑能否访问到。

4.3 飞牛 fnOS 部署要点

飞牛的用户群里已经有不少人把 NasTool 这类容器跑起来了。在飞牛的 Docker 管理界面中，同样先拉取镜像，再创建容器。飞牛的文件管理路径比较直观，建议先确认 NAS 上的绝对路径，再做映射。如果你的飞牛上已经部署了其他 Docker 容器，端口规划要统一考虑，避免出现端口冲突导致服务启动失败。

4.4 极空间部署要点

极空间的 Docker 功能在系统版本不同时，界面和功能完整度有差异。部署 NasTool 时，重点检查：当前极空间系统版本是否支持自定义容器端口映射，是否支持挂载外部目录。部分旧版本系统可能限制较多，如果遇到“无法映射端口”或“无法挂载目录”的问题，优先考虑升级系统固件，然后在 Docker 页面重新创建容器。

4.5 绿联部署要点

绿联 UGOS Pro 的 Docker 功能也支持图形化部署和 docker-compose 部署。在图形界面中创建容器时，注意把下载目录和媒体库目录都映射进去，否则 NasTool 无法对这些目录进行识别和整理。绿联部分型号的用户在网络热词中也会搜“绿联 NAS 搭建”相关教程，说明这类设备上自定义容器的需求并不少。

4.6 启动后确认

容器启动后，在浏览器里访问http://NAS的IP:端口。如果打不开，不要急着怀疑镜像问题，先看容器日志。常见启动失败原因包括端口被占用、挂载路径不存在、镜像名写错、环境变量缺少必要项。推荐先用docker logs -f nastool查看容器输出，再判断是配置问题还是镜像问题。

# 查看容器日志，确认启动状态 docker logs -f nastool

5. 基础功能配置

NasTool v2 安装完成只是第一步，真正想让整个流程跑通，还需要完成几项核心配置。

5.1 配置下载器

在 NasTool 的下载器配置页面，填写你下载工具的地址和认证信息。这一步的关键是网络连通性：如果下载工具跑在同一个 NAS 上，地址可以用内网 IP，但要确认容器内的 NasTool 能访问到宿主机 IP。如果下载工具跑了独立端口，需要确保防火墙放行。建议先用“测试连接”确认地址、端口、账户密码都正确，再保存配置。

常见配置项包括下载器的地址、认证方式、保存目录、下载分类。NasTool 通过调用下载工具的接口来创建下载任务和查询任务状态，所以下载工具本身的 API 一定要打开授权。

5.2 配置媒体服务器

在 NasTool 中配置 Jellyfin、Emby 或 Plex 的地址和 API Key，这样 NasTool 可以在文件整理完成后通知媒体服务器刷新媒体库。以 Jellyfin 为例，你需要在 Jellyfin 后台生成一个 API Key，然后在 NasTool 里填上地址和 Key。配置完成后，可以手动触发一次媒体库刷新，验证联动是否正常。

媒体服务器地址同样存在容器网络和宿主机网络的区别。如果 NasTool 和 Jellyfin 都在同一个 Docker 网络中，可以使用容器名称作为主机名；如果在不同网络中，使用 NAS 内网 IP 更稳妥。

5.3 配置目录与整理规则

这是 NasTool 最核心的一环。你需要告诉它：下载文件放在哪里，整理后的文件放到哪里，不同资源类型怎么分类。常见的目录结构是/downloads放下载完成的文件，/media/电影、/media/剧集作为整理目标目录。NasTool 会根据资源类型和命名规则自动移动、重命名文件，并在完成后触发媒体服务器刷新。

整理规则配置建议从最简单的开始，先配置电影和剧集两类，确认自动整理流程没有问题后，再扩展其他分类。不要一上来就配置非常复杂的规则，否则出了问题很难定位是规则问题还是刮削问题。

5.4 配置通知推送

通知推送可以让 NasTool 在订阅命中、下载完成、整理完成等关键节点给你发送消息。常见的通知渠道包括 Server酱、Tg、Webhook 等，在配置页填入对应的 token 或地址，然后发送一条测试通知验证链路。如果通知发送失败，优先检查 token 是否正确、网络是否能访问通知服务。

6. 功能测试与效果验证

配置完成后，建议按顺序做一轮功能测试，确认整个链路是否跑通。

6.1 订阅测试

在 NasTool 中添加一个订阅，指定资源类型、关键词和期望的画质要求。保存后观察下载器是否在短时间内接收到任务。如果订阅已经命中但下载器没有反应，先看 NasTool 日志，确认是不是下载器地址或认证配置错误。

预订测试的重点不是真的下载大量资源，而是确认“订阅 -> 识别 -> 创建下载任务”这一环能通。如果这一环都走不通，后面整理和刮削也无从谈起。

6.2 下载完成后的整理测试

找一个小体积的测试资源，手动放入下载器完成下载，然后观察 NasTool 是否自动识别文件、自动改名、自动移动到媒体库目录。判断成功标准是：文件从下载目录消失了，媒体库目录里出现了规范的文件夹和文件名，Jellyfin 里能看到新的海报和信息。

如果文件没有自动整理，先检查下载完成后的目录是否符合 NasTool 的监控范围，再确认目录映射是否把宿主机路径和容器路径对应起来。

6.3 刮削测试

在 NasTool 或媒体服务器中，对一部已经整理完成的电影发起刮削请求。判断标准是海报、简介、演员、类型等信息都正确显示。刮削失败通常和网络连通性有关，也可能是资源的文件名太乱导致识别不到正确条目。建议在刮削前把文件重命名为“电影名+年份”的规范格式，可以大幅提高刮削成功率。

6.4 通知测试

在通知渠道中点击发送测试消息，确认手机或电脑能正常收到通知。通知是自动化流程中很重要的一环，很多用户部署完后发现下载整理都正常，但通知一直不生效，最后查出来是网络问题或 token 填错。建议在配置阶段就做一次验证，不要等到出现问题才想查通知。

7. 接口 API 与批量任务

NasTool v2 除了 Web 界面，还提供了接口能力，便于第三方工具对接和二次开发。这部分的准确性需要以项目官方接口文档为准，下面给出一个通用调用思路。

7.1 接口启动方式

NasTool 容器本身启动后，Web 管理界面和接口服务是同时存在的。你需要拿到接口的访问地址、端口和认证 token，然后在 NAS 内网中测试接口连通性。不要直接把接口暴露到公网，建议通过内网访问或在安全的网关后面使用。

7.2 请求与返回示例

通用接口调用模板如下：

# 通用请求模板，实际接口路径、参数和鉴权方式请按项目文档调整 curl -X GET "http://127.0.0.1:端口/api/路径" \ -H "Authorization: Bearer YOUR_TOKEN"

import requests # 通用调用示例，需要按实际接口文档填写 URL、参数和鉴权信息 url = "http://127.0.0.1:端口/api/v1/资源" headers = { "Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json" } response = requests.get(url, headers=headers, timeout=30) print(response.status_code) print(response.json())

如果返回状态码为 200 且 JSON 结构符合预期，说明接口可以正常对接。如果返回 401，一般是 token 不对或鉴权方式错误；如果返回 404，基本是接口路径和文档不一致。

7.3 批量任务设计

NasTool 在批量任务上更适合做“定时自动化”。你可以把常见操作设计成这样的流程：

• 定时订阅检查：每隔一段时间检查一次订阅规则，命中后自动创建下载任务。
• 定时整理扫描：对新文件进行识别、改名、移动到媒体库。
• 定时媒体库刷新：整理完成后通知 Jellyfin 等媒体服务器刷新。
• 定时清理：对过期的缓存、种子、失败任务进行清理。

对于更复杂的批量任务，建议在外部脚本里通过接口循环调用 NasTool 的功能，并且加入日志和失败重试机制。

import time import requests # 批量处理通用模板，接口地址和参数需要按实际项目调整 def batch_process(items): url = "http://127.0.0.1:端口/api/批量任务" headers = {"Authorization": "Bearer YOUR_TOKEN"} for item in items: payload = {"name": item} try: resp = requests.post(url, json=payload, headers=headers, timeout=60) print(f"processed {item}: {resp.status_code}") except requests.exceptions.RequestException as e: print(f"failed {item}: {e}") time.sleep(2) # 避免请求过快 items = ["demo1", "demo2", "demo3"] batch_process(items)

批量任务的日志输出要单独保存，每次任务的开始时间、结束时间、状态、失败原因都记录下来，方便排查。

8. 资源占用与性能观察

8.1 资源占用如何观察

部署完成后，建议先观察 24 小时的资源占用曲线。在群晖的 Container Manager、飞牛的 Docker 管理界面或极空间/绿联的容器监控页面中，都能看到容器的 CPU、内存、网络和磁盘状态。重点关注内存占用是否持续增长，定时任务执行期间 CPU 是否会突然飙高，以及磁盘写入量是否异常。

需要说明的是，每个 NAS 的硬件配置、容器数量、任务频率、媒体库大小都不一样，所以资源占用没有固定值。更稳妥的做法是记录你本机环境的基线数据，然后观察长期趋势。

8.2 影响性能的关键因素

任务频率是影响 CPU 占用最直接的因素。比如订阅检查、定时扫描这类任务如果设置成每分钟执行一次，会导致容器频繁唤醒，占用会明显增加。建议先用保守的频率，比如每 30 分钟或每小时执行一次，观察资源占用后再逐步调整。

刮削任务对网络依赖大，如果媒体库文件特别多，大批量刮削时 CPU 和网络占用都会上升。第一次整理大媒体库时，建议分批次处理，不要一次性把几千个文件都提交到刮削队列里。

数据库大小也会影响界面响应速度。运行时间久了以后，日志表、订阅记录、历史记录会越来越大，如果发现界面加载变慢，可以检查数据库体积，并按项目文档清理历史日志和任务记录。

8.3 如何降低资源占用

降低资源占用主要靠三种方式：降低任务频率、精简插件和自动化规则、定期清理日志和历史记录。如果内存确实紧张，可以适当调低容器的资源限制，设置内存上限和 CPU 配额，但要注意不要设置得太低导致服务频繁 OOM。

# docker-compose 中限制容器资源示例 services: nastool: image: your-nastool-image:latest deploy: resources: limits: cpus: "2.0" memory: 2G

9. 常见问题与排查方法

如果在群晖、飞牛、极空间、绿联上遇到的是系统层面的问题，比如 Docker 服务本身不可用、存储空间不足、系统 Docker 版本太旧，需要先解决 NAS 系统本身的问题，再回到 NasTool 的排错流程。

10. 最佳实践与使用建议

NasTool v2 这类自动化媒体管理工具，用好的关键是配置清晰、流程可控。以下几个实践建议值得参考。

10.1 目录结构规范化

从第一台设备开始，就把目录结构定下来。建议把下载文件、整理后的媒体库、种子和备份目录彻底分开。下载目录和媒体库目录的映射路径写清楚，避免容器重启后路径对不上。

10.2 第一次先小规模测试

不要在还没有完全理解配置项的情况下，直接把整个媒体库交给 NasTool 处理。建议先用几个测试文件，把“订阅 -> 下载 -> 整理 -> 刮削 -> 刷新 -> 通知”的完整链路跑通，确认没问题后再扩大到正式媒体库。

10.3 备份配置与数据库

NasTool 的配置和数据库存放在配置目录中，容器升级前建议先备份这个目录。升级出现问题时，可以直接回滚到旧配置，避免重新配置所有内容。备份文件建议放在独立的备份盘或压缩后下载到本地。

10.4 接口与远程访问安全

如果想在外面查看 NasTool 状态，建议使用带身份验证的远程访问方案，不要直接把接口端口映射到公网。API token 泄露后，别人可能直接操作你的下载器和媒体库，影响很大。

10.5 权限与多用户控制

如果 NasTool 部署在家庭共享的 NAS 上，要注意下载目录和媒体库目录的权限划分。避免普通用户有权限删除或修改整个媒体库目录的情况，NasTool 使用的账户也应该只授予必要的最小权限。

10.6 合规使用提醒

再次强调，NasTool v2 提供的是自动化和整理能力，请确保订阅、下载、整理、传播的媒体内容具备合法授权。不要使用该工具去规避版权保护机制，不要处理涉及他人隐私的文件。涉及他人肖像、声音、私人文件时，需要获得明确授权后再进行操作。在使用通知推送、Webhook 等外部服务时，也注意不要泄露个人敏感信息。

10.7 定期检查日志和任务状态

自动化流程跑起来后，不要完全不管。建议每周末花几分钟看一下容器日志、任务记录和通知记录，确认订阅任务、整理任务、刮削任务都正常运行。任何自动化工具都可能因为外部 API 变化、网络波动、存储空间不足等原因产生异常，定期检查能避免问题积累成大故障。

11. 总结与下一步

NasTool v2 最值得尝试的点，是把“下载文件 -> 手动整理 -> 手动刮削 -> 手动刷新媒体库”这条重复性极高的流程，变成全自动的链路。最先应该验证的功能，是“订阅命中后下载器是否自动创建任务”和“下载完成后是否自动整理到媒体库”。这两个功能跑通，说明核心能力已经生效。

最容易踩的坑集中在路径映射和网络连通性：容器内的路径和宿主机路径对不上、容器访问不了下载器和媒体服务器的地址，都会导致流程中断。部署时优先把目录映射和网络策略检查清楚。

后续可以继续扩展的方向包括：把 NasTool 的接口接到自己写的自动化脚本里，批量管理订阅和媒体库；配合通知服务，把 NAS 上的异常也纳入统一告警；再进一步，可以结合更多 NAS 系统工具，把媒体管理、备份、监控整合成一套完整的家庭 NAS 运维方案。

如果你用的是群晖、飞牛、极空间或绿联，从 Docker 部署开始，按这篇文章的测试路径跑一遍，就能判断 NasTool v2 是否适合你的媒体库管理需求。建议收藏备用，后续配置时可以对照排查。