🚀 使用 Docker Compose 部署 NAS Tools

🚀 使用 Docker Compose 部署 NAS-Tools

NAS-Tools 是一款由 jxxghp 开发的 NAS 媒体库资源归集整理工具。它能够自动化完成影视资源的搜索、下载、识别、重命名和刮削，显著提升媒体库的管理效率和影音服务器的刮削识别率。该项目完全免费开源，且作者更新非常频繁。

📦 项目简介

NAS-Tools 的核心目标是实现媒体库管理的自动化。其主要功能包括：

资源检索与下载：支持 PT 站聚合 RSS 订阅自动追新，也可通过微信、Telegram 或 Web 界面进行聚合搜索及订阅。还能关联豆瓣账号，自动检索用户在豆瓣标记的影视资源，并为未完结的剧集加入 RSS 追更。
媒体识别与重命名：监控下载器或指定目录，在文件下载完成或发生变化时，自动识别真实媒体信息，通过硬链接（或复制、移动）方式转移到媒体库并规范命名，支持国产剧集和动漫，确保 Emby、Jellyfin、Plex 等影音服务器能准确刮削。
消息通知服务：支持 ServerChan、微信、Telegram、Bark 等图文消息通知，方便在手机上接收状态和进行控制。
影音服务器集成：可与 Emby、Jellyfin、Plex 等集成，例如通知它们更新媒体库。

⚙️ 部署前准备

环境要求
- 确保你的系统已安装 Docker 和 Docker Compose。
- 系统内存：建议至少 1GB 。
- 磁盘空间：确保有足够空间存储配置文件和媒体资源。
环境检查 在终端中执行以下命令，确认 Docker 环境正常： bash docker --version docker-compose --version
创建项目目录 建议创建一个独立的目录来管理 NAS-Tools 的所有文件，这有助于日后管理和备份。 bash mkdir -p /opt/docker/nas-tools cd /opt/docker/nas-tools

🛠️ 配置 Docker Compose

基于你提供的配置，这里是对 docker-compose.yml 文件的解读和优化说明。

networks:
  videos:
    external: true # 使用已创建的外部网络（需提前执行 docker network create videos）

#version: "3.8"
services:
  nas-tools:
    image: hsuyelin/nas-tools:latest  # 国内维护版镜像（适配国内网络，更新更便捷）
    container_name: nas-tools  # 容器名称，便于管理
    ports:
      - 5004:3000  # 端口映射：主机 5004 端口 → 容器 3000 端口（WebUI 访问端口）
    volumes:
      - ./config:/config     # 配置目录：主机 ./config → 容器 /config（保存设置、订阅等，核心目录）
      #- ./video:/media
      - /mnt/10t/videos:/media  # 媒体目录：映射主机影视目录到容器 /media（用于整理和同步）
      #- ./video:/video
      #- ./video/Movie:/media/video1
      #- ./video/TV-Play:/media/video2
      #- ./video/Anime:/media/video3
      #- ./media:/media
      #- /你的媒体目录:/你想设置的容器内能见到的目录   # 媒体目录，多个目录需要分别映射进来，需要满足配置文件说明中的要求
    environment:
      - PUID=0  # 运行用户 ID（0 为 root 权限，避免媒体目录权限问题，新手推荐默认）
      - PGID=0  # 运行用户组 ID（与 PUID 一致）
      - UMASK=000 # 权限掩码（默认 000，确保新创建文件可正常访问，无需修改。可以考虑设置为022）
      - NASTOOL_AUTO_UPDATE=false  # 容器启动时是否自动更新（新手建议关闭，手动更新更稳定，开启=true）
      - NASTOOL_CN_UPDATE=false # 如果开启了容器启动自动升级程序，并且网络不太友好时，可以设置为true，会使用国内源进行软件更新
       # 自动更新时是否用国内源（开启 AUTO_UPDATE 后生效，国内用户可设为 true）
      #- REPO_URL=https://ghproxy.com/https://github.com/hsuyelin/nas-tools.git  # 当你访问github网络很差时，可以考虑取消注释用代理源
    #extra_hosts:   # 增加此行与如下一行，实践后没用。
      #- "api.thetvdb.org:192.241.234.54"
      #- "image.themoviedb.org:138.199.36.10"
      #- "www.themoviedb.org: 138.199.36.10"
      #- "image.tmdb.org:185.93.1.243"
      #- ""

    restart: always  # 容器退出后自动重启（开机自启）
    #network_mode: bridge
    hostname: nas-tools  # 容器主机名（默认即可）


    #privileged: true
    #特权:真
    #restart: 'unless-stopped'


    networks:
      videos:
        ipv4_address: 10.1.1.6  # 容器在 videos 网络中的固定 IP（默认即可，无需修改）
        #ipv6_address: 2001:3984:3989::10

关键配置说明：

配置项	说明与建议
`image`	你使用的是 `hsuyelin/nas-tools` 镜像。也可考虑 `jxxghp/nas-tools`（原作者）或其他衍生版本。
`ports`	`"5004:3000"` 将容器内的 3000 端口（Web UI）映射到主机的 5004 端口。你可按需修改主机端口。
`volumes`	`./config:/config` 用于持久化存储NAS-Tools 的所有配置、数据库等，务必确保此配置，防止容器重启后数据丢失。`/mnt/10t/videos:/media` 将你的媒体目录映射到容器内。确保 NAS-Tools 容器内进程对宿主机挂载的媒体目录有读取权限。
`environment`	`PUID`/`PGID`：设置为 `0` 即以 root 权限运行，可避免很多权限问题。但出于安全考虑，在生产环境建议使用非特权用户。`NASTOOL_AUTO_UPDATE=false`：建议关闭容器内自动更新，而是通过更新镜像的方式进行升级，以提高稳定性。
`networks`	使用外部网络并指定静态 IP，便于容器间通信。
networks.videos.external	必须提前创建 `videos` 网络，否则启动会报错 “网络不存在”（执行 `docker network create videos` 解决）。

注意：媒体目录的映射必须注意权限问题。如果遇到 "Permission denied" 错误，通常是因为容器内进程（由 PUID/PGID 指定）没有足够权限访问宿主机上映射的目录。可尝试将 PUID/PGID 设置为 0（root），或者调整宿主机上媒体目录的权限和所有者。

🚀 启动与验证

启动服务 在 docker-compose.yml 文件所在目录执行： bash docker-compose up -d 此命令会拉取镜像并在后台启动容器。
检查服务状态 bash docker-compose ps 如果看到 nas-tools 容器的状态为 Up，说明服务已成功启动。
查看实时日志（可选） 如果遇到问题，可以通过以下命令查看容器日志来排查： bash docker-compose logs -f nas-tools
访问 Web 界面 打开浏览器，访问 http://你的服务器IP:5004。
- 如果一切正常，你将看到 NAS-Tools 的登录界面。
- 默认的用户名是 admin，密码是 password 。

⚙️ 基础配置与使用

成功登录后，你需要进行一些基础配置以使 NAS-Tools 正常工作。

配置 TMDB API Key
- 这是必不可少的一步，因为 NAS-Tools 主要依赖 The Movie Database (TMDB) 的元数据。
- 前往 TMDB 官网注册账号并申请 API Key。
- 在 NAS-Tools Web 界面的 "基础设置" -> "媒体" 中，填入获取到的 API Key 并保存。
配置目录同步（媒体整理） 这是实现自动整理的核心功能。
- 规划目录：建议在媒体目录下建立清晰的文件夹结构，例如区分 "未整理" 和 "已整理" 文件夹，并且它们最好处于同一级目录 。
- 添加目录同步：
  - 进入 "设置" -> "目录同步"。
  - 源目录：选择容器内映射的、存放原始下载文件的路径（例如 /media/未整理）。
  - 目的目录：选择容器内映射的、用于存放整理后文件的路径（例如 /media/已整理）。
  - 同步方式：
    - 硬链接：推荐方式，文件在源和目标目录"同时存在"，但只占用一份磁盘空间，适合 PT 保种用户。
    - 移动：直接移动文件，不保留原文件。
    - 复制：复制一份文件，占用双倍空间，不推荐。
  - 开启同步并保存。
配置媒体服务器（可选） 如果你使用了 Emby、Jellyfin 或 Plex，可以在 "基础设置" -> "媒体服务器" 中配置连接信息，使 NAS-Tools 在整理完资源后能通知媒体服务器更新库。
尝试手动整理
- 在 "服务" -> "目录同步" 中，可以手动触发一次同步。
- 在 "媒体整理" -> "手动识别" 中，可以对未能自动识别的文件进行手动干预。

🔒 维护与管理

服务管理：
- 停止服务：docker-compose down
- 重启服务：docker-compose restart
- 查看服务状态：docker-compose ps
数据备份：
- 定期备份 docker-compose.yml 文件以及映射的 ./config 目录。./config 目录包含了 NAS-Tools 的所有配置和数据库，至关重要。
版本更新：由于设置了 NASTOOL_AUTO_UPDATE=false，更新需要通过以下步骤： bash # 进入 docker-compose.yml 所在目录 docker-compose down docker-compose pull # 拉取最新镜像 docker-compose up -d # 可选：清理无用镜像 docker image prune 注意：更新前，特别是大版本更新时，建议备份 ./config 目录 。如果更新后容器启动失败，可能是由于依赖冲突或缓存问题，可以尝试清理旧镜像和容器后重新部署。

🐛 常见问题排查 (FAQ)

问题现象	可能原因与解决方法
无法访问 Web 界面	1. 检查防火墙/安全组是否放行 5004 端口。 2. 确认容器是否正常运行：`docker-compose ps`。 3. 查看容器日志：`docker-compose logs nas-tools`。
媒体库扫描不到文件或权限错误	1. 检查 `volumes` 映射的宿主机目录是否存在且有媒体文件。 2. 检查目录权限：确保容器内进程（根据 `PUID`/`PGID`）对宿主机挂载的目录有读取权限。可尝试将 `PUID`/`PGID` 设为 `0`，或使用 `chown`/`chmod` 调整宿主机目录权限。 3. 在 NAS-Tools Web 界面添加目录时，务必使用容器内的路径（例如 `/media`）。
TMDB 海报/元数据无法加载	1. 确认已正确配置 TMDB API Key 。 2. 检查网络连接，如果访问 TMDB 网络不畅，可尝试在 `docker-compose.yml` 中配置网络代理（你配置中的 `HTTP_PROXY` 和 `HTTPS_PROXY` 环境变量）或使用 `REPO_URL` 国内源。
容器启动失败/不断重启	1. 查看日志获取具体错误信息：`docker-compose logs nas-tools`。 2. 可能是 Python 依赖冲突或镜像缓存问题。尝试清理后重装： `bash<br> docker-compose down<br> docker rmi hsuyelin/nas-tools:latest<br> docker-compose up -d<br>`

希望这份详细的教程能帮助你顺利部署和使用 NAS-Tools，享受自动化媒体库管理带来的便捷！