nastool V2 部署指南：群晖/飞牛/极空间/绿联 NAS 自动化媒体库搭建

在 NAS 上搭建影音媒体库，很多人走到一半就放弃了。下载器、媒体库、海报墙、字幕、目录规范……每个环节单独看都不复杂，串在一起却很容易崩。nastool V2 就是为了把这套流程串联起来，把“手动找资源、手动下载、手动改名、手动整理”变成“一键订阅、自动入库”的闭环方案。

本文将围绕 nastool V2 展开，先讲清楚它解决什么问题，再分别介绍在群晖、飞牛、极空间、绿联四类 NAS 上的部署步骤。文章会按“核心概念 → 环境准备 → 部署实战 → 使用配置 → 常见排错 → 最佳实践”的顺序组织，尽量覆盖新手关心的每个细节。

如果你是刚入手 NAS，还没想清楚媒体库怎么规划；或者已经在用 Jellyfin/Emby 管理海报墙，但苦于下载和整理太繁琐，这篇文章都值得读完。

1. 认识 nastool V2：它到底解决什么问题

1.1 从“资源整理”到“媒体自动化”

nastool 是一款面向 NAS 场景的媒体资源自动化整理工具。它的核心定位不是播放器，也不是下载器，而是“调度中心”。

它可以把你已经有的下载工具（qBittorrent、Transmission）、媒体服务器（Jellyfin、Emby、Plex）、索引站点、消息通知渠道串起来，实现一条完整的自动化链路：

订阅/关注想看的内容 ↓ nastool 自动检索可用资源 ↓ 调用下载器自动下载 ↓ 下载完成后自动转移到媒体库 ↓ 重命名、整理目录、刮削海报 ↓ Jellyfin/Emby/Plex 自动刷新，海报墙更新

换句话说，以前你需要手动去各个站点搜资源、复制链接、在下载器里添加任务、等下载完成再手动移动到媒体库，然后到媒体服务器里刷新库。用了 nastool V2 之后，这些步骤大部分都能自动完成。

1.2 nastool V2 的典型应用场景

• 家庭影音库：订阅新剧，更新后自动下载并入库。
• 多用户共享：给家人朋友分配访问账号，媒体库自动整理，打开客户端就能看。
• 媒体库规范化：批量重命名、归入演员/年份目录、下载缺失字幕。
• 提醒与通知：下载完成、入库失败、磁盘空间不足，通过微信、Telegram、飞书等渠道推送。

1.3 和 Jellyfin/Emby/Plex 的区别

很多刚接触 NAS 的读者会把 nastool 和 Jellyfin 混在一起。简单区分：

• Jellyfin / Emby / Plex：负责“播放和展示”，把已经整理好的媒体文件刮削成海报墙，提供网页端、客户端播放能力。
• nastool：负责“入库前的工作”，包括资源检索、下载、改名、目录归档。它本身不依赖特定的媒体服务器，但通常会配合 Jellyfin/Emby/Plex 使用。

两者配合起来，架构才是完整的。nastool 管“把资源变成规范的媒体文件”，Jellyfin 管“把规范的媒体文件变成好看的海报墙”。

1.4 为什么推荐通过 Docker 部署

nastool 支持多种部署方式，但在不同 NAS 平台上，最通用、最不易污染系统环境的方式是 Docker。

原因很简单：

• 依赖隔离：所有运行环境打包在容器里，不会和 NAS 自带的 Python、Node 等版本冲突。
• 迁移方便：升级、换机时导出配置目录即可。
• 回滚容易：容器可以固定镜像版本，出问题后重新创建容器即可。
• 不同平台差异小：群晖、飞牛、极空间、绿联都支持 Docker，部署思路几乎一致。

接下来的部署部分，会以 Docker 为主要方式展开。

2. 部署前准备：目录规划与基础信息

2.1 先规划目录，再动手安装

很多新手装完 nastool 后遇到“找不到文件”“媒体库不刷新”之类的问题，根源多半是目录映射没规划好。

建议在安装前，先设计好两类目录：

1. 配置目录：存放 nastool 自身的数据库、日志、缓存、配置文件。
2. 媒体目录：包括下载临时目录和最终媒体库目录。

下面是一套比较通用的目录规划思路：

/nas_data ├── docker │ └── nastool │ └── config # nastool 配置目录 ├── downloads # 下载器下载目录（临时区） │ ├── movies │ └── tv └── media # 整理后的媒体库 ├── movies └── tv

为什么要把下载目录和媒体库目录分开？

• 下载目录是“未整理区”，文件可能命名混乱、文件格式不统一，不适合直接提供媒体服务器扫描。
• 媒体库目录是“已整理区”，nastool 会把文件重命名并移动到对应子目录，Jellyfin/Emby/Plex 只需要扫描这个目录。

如果两者混在一起，媒体服务器很容易把半成品、种子文件、多余说明文件一起扫进去，导致海报墙出现各种奇怪条目。

2.2 镜像选择与版本说明

nastool 的项目迭代速度较快，镜像名、默认端口、环境变量在不同版本中可能发生变化。建议在部署前先打开项目仓库或 Docker Hub 页面，确认当前版本要求的镜像名和启动参数。

常见的镜像写法大致如下：

镜像名：nastool/nas-tools（或项目 README 中标注的最新镜像） 默认端口：3000 默认用户密码：admin / admin

注意：这里的镜像名和端口仅用于示例说明。请以你实际操作时的官方 README 为准。版本更新后，部分参数可能调整，本文重点演示的是部署思路。

2.3 PUID / PGID 是什么

在 Linux 类 NAS 上跑 Docker，经常会遇到权限问题。nastool 容器内默认以某个用户运行，如果这个用户在宿主机上没有对应权限，就可能写不进配置文件、移不动文件。

常用解决方法是设置环境变量 PUID 和 PGID，让容器内进程以宿主机某个指定用户的身份运行。

以群晖为例，管理员用户通常 UID 是 1024，用户组 GID 是 100。具体值可以在 SSH 终端里执行下面命令查看：

id

输出类似：

uid=1024(admin) gid=100(users) groups=100(users)

那么部署时就可以设置：

environment: - PUID=1024 - PGID=100

在飞牛 fnOS、极空间、绿联上，同样可以用 SSH 执行id查看当前用户的 UID 和 GID。不同 NAS 系统的默认用户可能不同，不要照搬网上教程里的数值，一定要先查看自己系统的实际值。

2.4 网络模式选择：bridge 还是 host

• bridge 模式：需要手动映射端口，例如3000:3000。冲突风险小，适合群晖、极空间、绿联、飞牛这类带图形界面管理 Docker 的系统。
• host 模式：容器直接使用宿主机网络，不需要映射端口，性能更好，但端口冲突时排查更麻烦。

多数情况下，建议先使用 bridge 模式加端口映射。如果后续遇到容器需要访问局域网内其他设备，或者某些下载器回调出现网络不通的问题，再考虑调整。

3. 群晖 NAS 部署 nastool V2

3.1 群晖环境说明

群晖部署 Docker 的推荐方式是使用自带的 Container Manager（DSM 7.2 及以后版本）或 Docker 套件（DSM 7.0 以下版本，以及部分老机型）。界面名称可能略有不同，但核心操作是一致的。

部署前需要先准备：

• 一台已经装好 DSM 的群晖 NAS。
• 存储空间里预留出容器配置目录和媒体目录。
• 能访问群晖的账号，并且具备创建容器、映射目录的权限。

3.2 在群晖上创建项目

群晖的 Container Manager 支持“项目”概念，也就是通过 docker-compose.yml 一键创建多个容器。这种方式比在界面上一个个填写更直观，也方便后续修改和重建。

在 Container Manager 中找到“项目”页面，点击“新增”，然后填写项目名称和 compose 文件路径。

下面是一个通用的 compose 示例：

services: nastool: image: nastool/nas-tools:latest container_name: nastool restart: unless-stopped ports: - "3000:3000" volumes: - /volume1/docker/nastool/config:/config - /volume1/downloads:/downloads - /volume1/media:/media environment: - PUID=1024 - PGID=100 - TZ=Asia/Shanghai

路径说明：

• /volume1/docker/nastool/config：nastool 的配置目录，建议放在独立的 config 目录下，方便备份。
• /volume1/downloads：下载器使用的下载目录，映射为容器内的/downloads。
• /volume1/media：媒体库目录，映射为容器内的/media。

保存后点击“立即运行”，群晖会自动拉取镜像并启动容器。

3.3 通过命令行部署

如果你更习惯 SSH 操作，也可以直接登录群晖终端执行命令。

首先创建目录：

sudo mkdir -p /volume1/docker/nastool/config

然后进入目录，创建 docker-compose.yml 文件：

cd /volume1/docker/nastool

写入上面提到的 compose 内容后，执行：

sudo docker compose up -d

如果群晖上的 Docker 版本较老，不支持docker compose命令，可以尝试：

sudo docker-compose up -d

启动后查看容器状态：

sudo docker ps

确认 nastool 容器处于 Up 状态即可。

3.4 群晖端口占用提醒

群晖系统本身可能占用一部分常见端口。如果 3000 被占用，在 compose 里改成其他映射端口即可，比如：

ports: - "3100:3000"

注意，冒号左侧是群晖的端口，右侧是容器内部的端口。改左侧不影响 nastool 内部运行。

4. 飞牛 fnOS 部署 nastool V2

4.1 飞牛 fnOS 环境说明

飞牛 fnOS 是近期关注度较高的国产 NAS 系统，基于 Debian，系统界面简洁，对 Docker 支持也比较友好。很多用户会拿它和群晖、极空间、绿联对比。

飞牛 fnOS 的应用中心提供了 Docker 应用入口，可以直接通过图形界面上传 compose 文件，也可以在 SSH 终端里操作。

4.2 在飞牛 fnOS 上创建 docker-compose 项目

登录飞牛 fnOS 的网页管理界面，找到“Docker”应用，进入“Compose”或“容器编排”页面，选择新增项目。

这里需要先确定你的媒体目录路径。飞牛 fnOS 的存储卷通常挂载在/vol1、/vol2等路径下，具体以你自己的存储规划为准。

示例 compose：

services: nastool: image: nastool/nas-tools:latest container_name: nastool restart: unless-stopped ports: - "3000:3000" volumes: - /vol1/docker/nastool/config:/config - /vol1/downloads:/downloads - /vol1/media:/media environment: - PUID=1000 - PGID=1000 - TZ=Asia/Shanghai

保存后点击启动，飞牛会自动完成拉取镜像和创建容器的过程。

4.3 飞牛权限注意事项

飞牛 fnOS 默认管理用户的 UID/GID 不一定是 1000，尤其是如果你在安装系统时自定义过用户，需要先执行id命令确认。

另外，如果下载目录和媒体库目录属于不同的存储卷，映射关系要单独写。例如：

volumes: - /vol1/docker/nastool/config:/config - /vol2/downloads:/downloads - /vol2/media:/media

目录跨卷是没有问题的，Docker 只关心宿主机路径，不要求它们在同一个卷里。但要注意，nastool 在移动文件时，如果是跨卷复制，可能会产生较大的 IO 压力，建议下载和媒体库尽量放在同一块硬盘或同一个存储池，至少避免频繁跨物理磁盘移动。

5. 极空间部署 nastool V2

5.1 极空间 Docker 功能说明

极空间部分机型内置了 Docker 功能，能在“应用中心”或“Docker”模块里添加容器。极空间的 Docker 管理界面相对简洁，支持填写容器名称、镜像名、端口映射、目录映射、环境变量等。

不同机型和系统版本界面可能不同，但核心配置项是一样的。

5.2 极空间图形界面配置示例

在极空间 Docker 模块中，点击“添加容器”或“自定义容器”，依次填写：

• 容器名称：nastool
• 镜像：nastool/nas-tools:latest（以官方 README 为准）
• 端口映射：本地端口 3000 → 容器端口 3000
• 目录映射：
  • 本地路径/docker/nastool/config→ 容器路径/config
  • 本地路径/downloads→ 容器路径/downloads
  • 本地路径/media→ 容器路径/media
• 环境变量：
  • PUID=1000
  • PGID=1000
  • TZ=Asia/Shanghai

保存后启动容器。

5.3 极空间常用路径参考

极空间的存储路径受系统版本影响较大，有时会以/tmp/zfs/开头，有时可能是/volume1或/data。在图形界面创建容器时，可以直接通过文件选择器选取目录，不需要手动输入路径。

建议在创建容器之前，先确认：

• config 目录：建议放在极空间的数据盘中，不要放在系统盘。
• downloads 目录：确保下载器（qBittorrent 等）也能访问到同一个路径。
• media 目录：后续要挂载给 Jellyfin/Emby/Plex 使用。

如果后续发现极空间容器内路径映射不对，可以在容器详情页停止容器后修改映射，再重新启动。

6. 绿联 NAS 部署 nastool V2

6.1 绿联 NAS 环境说明

绿联 NAS 近年来在硬件配置上比较有竞争力，系统内置 Docker 应用，支持通过 Docker Compose 创建容器，也支持图形化的容器管理。

绿联 NAS 的 Docker 模块通常在“应用中心”中安装，安装完成后进入 Docker 管理页面，主要操作包括镜像管理、容器管理、Compose 项目管理。

6.2 绿联使用 Compose 创建容器

在绿联的 Docker 管理页面中找到 Compose 或项目功能，新建一个 Compose 项目，名称可以填 nastool。

示例文件：

services: nastool: image: nastool/nas-tools:latest container_name: nastool restart: unless-stopped ports: - "3000:3000" volumes: - /volume1/docker/nastool/config:/config - /volume1/downloads:/downloads - /volume1/media:/media environment: - PUID=0 - PGID=0 - TZ=Asia/Shanghai

注意：这里的PUID=0、PGID=0表示以 root 用户运行容器。很多绿联 NAS 用户反馈系统文件权限管理比较严格，普通用户挂载目录时容易出现写权限不足的问题。用 root 运行容器可以规避权限问题，但安全性会下降。如果你对权限比较敏感，建议先创建好共享目录，给指定用户分配完整读写权限，再通过id查到对应用户的 UID/GID 填入环境变量。

6.3 绿联路径映射建议

绿联 NAS 的存储路径在不同系统版本上也有差异。使用图形界面创建容器时，优先使用文件选择器来指定路径。创建目录时可以参考：

/volume1/docker/nastool/config /volume1/downloads /volume1/media

如果系统提示路径不存在，先到文件管理里创建对应的共享文件夹，再回到 Docker 配置界面刷新路径列表。

7. 通用 Docker Compose 模板与参数说明

7.1 一份完整的通用模板

无论使用哪个 NAS 平台，只要支持 Docker Compose，都可以参考下面这份模板：

services: nastool: image: nastool/nas-tools:latest container_name: nastool restart: unless-stopped ports: - "3000:3000" volumes: - /你的路径/nastool/config:/config - /你的路径/downloads:/downloads - /你的路径/media:/media environment: - PUID=你的用户ID - PGID=你的用户组ID - UMASK=022 - TZ=Asia/Shanghai

7.2 逐个参数说明

7.3 关于 PUID/PGID 的三个常见误区

1. 直接照抄网上教程里的PUID=1024：不同 NAS 系统默认用户不同，最好执行id确认。
2. 设置成不存在的 UID/GID：容器可能启动失败，或者运行后没有权限读写挂载目录。
3. 完全忽略权限设置：某些 NAS 上容器可以运行，但下载完成后文件移不进媒体库，日志里出现 Permission denied。

建议到宿主机终端执行：

id

然后根据输出结果设置 PUID 和 PGID。

8. 首次启动后的初始化配置

8.1 访问 nastool 后台

容器启动成功后，打开浏览器访问：

http://NAS的IP:3000

首次进入会要求登录，默认账号密码通常是admin / admin。如果你使用的镜像版本修改了默认密码，以项目 README 说明为准。

登录后第一件事是修改默认密码，避免泄露到内网后被其他设备乱连。

8.2 添加媒体服务器

在 nastool 后台找到“媒体服务器”或“媒体库”配置，填写 Jellyfin/Emby/Plex 的相关信息：

• 服务器地址：例如http://192.168.1.100:8096
• API Key：在 Jellyfin/Emby 后台生成。

nastool 与媒体服务器联动后，可以做到：

• 自动刷新媒体库。
• 获取已存在的媒体列表，避免重复下载。
• 通过媒体服务器查询缺失剧集。

如果暂时没有配置媒体服务器，nastool 也可以独立运行，但体验会打折扣。

8.3 添加下载器

在“下载器”配置中，填写 qBittorrent 或 Transmission 的连接信息。

以 qBittorrent 为例，需要填写：

• 地址
• 端口：Web UI 端口
• 用户名和密码

添加成功后，nastool 会在后台测试连接。连接失败时，优先检查下载器是否允许外部访问、防火墙是否放行端口、密码是否正确。

8.4 配置索引器或资源站点

nastool 的资源检索能力依赖索引器或自定义资源站。这部分配置需要根据你实际使用的资源站和索引器来填写 API Key 或 Cookie。

配置时注意：

• 不要随意填写不明来源的站点配置。
• 资源检索应遵守所使用站点的规则和当地法律法规。
• 只使用你有权访问的服务。

8.5 目录关联设置

在 nastool 后台，需要把容器内的路径和媒体服务器识别的路径对应起来。

典型情况：

• nastool 容器内下载目录是/downloads。
• 下载器里看到的目录是宿主机的/volume1/downloads。
• Jellyfin 容器内媒体库路径是/media。

这些路径分别位于不同容器或宿主机视角下，nastool 需要通过“路径映射”功能做一次转换，把宿主机路径、容器路径、媒体服务器路径关联起来，才能真正实现自动整理。

这是我们最容易踩坑的一步。很多用户下载能完成，但文件始终不进媒体库，就是因为路径映射没有配对。

9. 实际使用演示：订阅、检索与自动入库

9.1 添加订阅

在 nastool 后台搜索想要观看的剧集或电影，点击“订阅”，nastool 会记录这个订阅状态。之后它会根据你配置的索引器定时检索，一旦发现可用资源，就自动推送下载任务到下载器。

订阅功能对追剧场景尤其有用。新剧更新后，无需每集手动去搜资源。

9.2 手动检索

如果没有设置自动订阅，也可以在后台主动搜索资源，手动选择：

• 清晰度：1080p、4K 等。
• 文件大小。
• 资源类型。

选择后 nastool 会调用索引器返回可用结果，确定后推送到下载器。

9.3 自动整理入库

下载完成后，nastool 会执行整理任务：

• 把文件从下载目录转移到媒体库目录。
• 按照配置的命名规范重命名。
• 根据媒体类型放入movies或tv子目录。

整理完成后，nastool 会通知媒体服务器刷新库。Jellyfin 的页面上很快就会看到新的海报墙条目。

9.4 通知渠道配置

nastool V2 支持接入多种通知渠道，例如 Server酱、Telegram、飞书、企业微信等。配置完成后，可以收到以下消息：

• 开始下载通知。
• 下载完成通知。
• 入库失败通知。
• 磁盘空间预警。

在家庭场景中，建议至少配置一种通知渠道。否则下载失败时，你可能要等到打开 NAS 才能发现问题。

10. 常见问题与排查思路

部署和使用 nastool V2 时，下面这些问题出现频率最高。

10.1 容器的日志怎么看

排查问题时，日志是最重要的线索。

群晖：Container Manager → 容器详情 → 日志。 飞牛：Docker → 容器 → 日志。 极空间：容器详情页 → 日志。 绿联：Docker 管理界面 → 容器 → 日志。

也可以在 SSH 终端直接执行：

docker logs -f nastool

关注日志中与Permission、Error、Failed相关的关键词。

10.2 下载器登录异常

qBittorrent 如果开启了“IP 地址过滤”或“反盗链”，nastool 可能无法连接。建议在 qBittorrent 的 Web UI 设置里限制来源 IP，或者放行内网网段，避免把本地容器请求也拦截掉。

10.3 数据迁移与恢复

如果换了 NAS 或者重装系统，只需要备份后恢复 nastool 的 config 目录即可。

备份方法：

tar -czf nastool_config.tar.gz /volume1/docker/nastool/config

恢复时，把 config 目录放回原路径，重新创建容器并挂载相同的目录路径即可。

11. 最佳实践与工程建议

11.1 目录规划原则

• 配置目录、下载目录、媒体库目录要分开。
• 下载目录和媒体库目录尽量放在同一个存储池，减少跨盘移动。
• 媒体库目录按movies和tv分大类，后续可以在内部按年份、地区等二级目录继续组织。

11.2 权限最小化

如果只是个人家庭使用，并且在受信任的内网环境，可以适当放宽权限。但如果 NAS 暴露到公网，或者需要多人共用，建议：

• 为 nastool 创建专用用户，而不是直接用 root。
• 只给容器挂载它需要访问的目录，不要把整个 NAS 根目录映射进去。
• 不要将 Docker Socket 挂载给不信任的容器。

11.3 网络与远程访问安全

NAS 上的媒体管理工具通常涉及大量个人数据，远程访问时需要注意安全边界。

• 不建议直接暴露 3000 端口到公网。
• 如果确实需要远程管理，优先使用带身份认证的反代方案，并开启双重认证。
• 即使在内网，也建议修改默认密码。
• 定期检查容器日志和登录记录。

nastool 本身只是管理工具，真正的安全风险往往出在暴露服务时不加保护。很多人用 Docker 部署服务后，直接做端口映射到公网，后续很容易被扫描工具盯上。

11.4 更新策略

nastool 的版本更新比较频繁。升级前建议：

1. 备份 config 目录。
2. 拉取最新镜像。
3. 删除旧容器。
4. 使用相同配置重新创建容器。

注意：不同大版本之间的配置结构可能不兼容。如果是从 V1 升级到 V2，不要拿旧配置直接套新容器，先阅读官方升级说明。

11.5 整合其他 NAS 工具

nastool 经常和以下工具联合使用：

• qBittorrent / Transmission：下载器。
• Jellyfin / Emby / Plex：媒体服务器。
• 1Panel：服务器运维面板。
• Portainer：Docker 容器管理。

这里需要提醒一点：nastool 的定位是“媒体自动化整理”，不要试图让它替代 Jellyfin 去做硬件解码、转码等工作。转码性能问题建议交给 Jellyfin 自己处理，部分 NAS 支持 GPU 硬件加速，可以在 Jellyfin 中开启。

如果部署过程中遇到“jellyfin 硬件加速”相关的问题，排查方向通常在 Jellyfin 的容器参数和宿主机显卡驱动，而不是 nastool。

11.6 备份策略

nastool 的配置数据库虽然不大，但包含了订阅列表、路径映射、索引器配置等信息，丢失后重新配置非常麻烦。

建议把 config 目录列入 NAS 的定时备份任务中，至少每周备份一次。如果家庭使用频率不高，也可以在每次调整重要配置后手动备份。

11.7 关于版权与合规

nastool 的自动化能力很强大，但请务必遵守所在地区的法律法规。

• 只订阅、下载、整理你有权访问的内容。
• 使用资源站点时遵守站点规则，不用来传播或商用。
• 涉及远程访问时要保护个人隐私，不要随意把内网服务暴露给不相关的人。

12. 总结与后续学习方向

nastool V2 的价值在于把“检索、下载、整理、入库、通知”整合成一条自动化链路。部署本身并不复杂，真正需要花心思的是目录规划、路径映射和索引器配置。只要这几个环节打通，后续使用体验会非常顺畅。

如果你是从零开始，建议按这个顺序演练：

1. 先部署 Jellyfin 或 Emby，把媒体库目录跑通。
2. 再部署 qBittorrent 或 Transmission，熟悉下载器设置。
3. 最后部署 nastool V2，接入索引器和通知渠道。
4. 完成路径映射后，测试一次完整流程：订阅 → 检索 → 下载 → 整理 → 海报墙刷新。

这样做的好处是每增加一个组件，都只引入一个变量。如果出了问题，很容易定位是在下载器、nastool 还是媒体服务器。

接下来你还可以继续研究：

• Jellyfin 的硬件转码配置。
• 多用户权限和媒体库分级。
• 基于 Docker Compose 的一体化部署方案。
• 通知渠道的深入配置。
• 日志监控与自动告警。

NAS 媒体自动化这条链路，越往后越能体会到“自动化”带来的便利。希望本文能帮你把第一步走稳。