MoviePilot V3 Docker 部署教程

MoviePilot 可以连接下载器和媒体服务器，完成搜索、订阅、整理与媒体库通知。这篇教程采用官方当前提供的 V3 Docker 镜像，适合全新部署。

已有 V2 用户先别直接升级

V3 可以复用 V2 的配置和数据库，但升级前必须备份。V3 完成数据库升级后不能直接换回 V2 镜像；插件也可能需要安装 V3 专用版本。已有环境请先阅读官方版本说明，再安排升级。

内容状态

本文依据 MoviePilot 官方安装指引于 2026-09-11 更新。软件迭代较快，实际界面和变量请以官方文档为准。

部署前准备

开始前确认：

• NAS 已安装 Docker 或容器管理工具。
• 已规划配置目录和媒体根目录。
• 3000 与 3001 端口没有被其他应用占用。
• 下载器与 MoviePilot 能映射到相同的媒体根目录。

建议目录结构：

/volume1/docker/moviepilot/
├── config/        # 配置、数据库和日志
└── core/          # 内核浏览器文件

/volume1/media/
├── downloads/     # 下载目录
└── library/       # 整理后的媒体库

不同 NAS 的实际路径可能不同，请把示例路径替换成自己的共享文件夹路径。

Docker Compose 部署

在 MoviePilot 应用目录中新建 compose.yaml：

services:
  moviepilot:
    image: jxxghp/moviepilot-v3:latest
    container_name: moviepilot-v3
    hostname: moviepilot-v3
    restart: always
    stop_grace_period: 120s
    ports:
      - "3000:3000"
      - "3001:3001"
    volumes:
      - /volume1/docker/moviepilot/config:/config
      - /volume1/docker/moviepilot/core:/moviepilot/.cloakbrowser
      - /volume1/media:/media
    environment:
      NGINX_PORT: "3000"
      PORT: "3001"
      PUID: "0"
      PGID: "0"
      UMASK: "000"
      TZ: Asia/Shanghai

启动容器：

docker compose up -d
docker compose ps
docker compose logs -f moviepilot

如果 NAS 使用图形化容器管理器，也可以新建 Compose 项目并粘贴上面的内容。路径必须先按自己的设备修改。

首次初始化

浏览器访问：

http://NAS的局域网IP:3000

V3 全新安装不会预置管理员密码。首次打开时，按页面提示完成：

1. 设置管理员用户名。
2. 设置并确认管理员密码。
3. 生成并妥善保存 API Key。
4. 保存后进入登录页面。

不要把管理端口直接暴露到公网。需要远程访问时，优先使用可信的组网工具或配置 HTTPS 反向代理。

连接 qBittorrent

MoviePilot 和 qBittorrent 必须看到一致的文件路径。例如两边都把宿主机的 /volume1/media 映射为容器内的 /media：

宿主机：/volume1/media/downloads
MoviePilot 容器：/media/downloads
qBittorrent 容器：/media/downloads

然后在 MoviePilot 的下载器设置中填写：

项目	示例
类型	qBittorrent
地址	http://qbittorrent:8080 或 NAS 局域网地址
用户名	qBittorrent WebUI 用户名
密码	qBittorrent WebUI 密码

如果两个容器不在同一 Docker 网络中，容器名可能无法解析，可以先使用 NAS 的局域网 IP 测试连接。

硬链接和目录映射

希望使用硬链接整理媒体时，下载目录和媒体库需要位于同一文件系统，并通过一个共同的根目录映射进容器。

推荐：

volumes:
  - /volume1/media:/media

不建议把 /volume1/media/downloads 和 /volume1/media/library 分别映射成两个独立挂载。即使它们位于同一块硬盘，容器内也可能被识别为不同文件系统，导致硬链接失败。

连接媒体服务器

MoviePilot 可以连接 Jellyfin、Plex 或 Emby。先确认媒体服务器已经能够扫描 /media/library，再在 MoviePilot 中填写局域网地址和 API Key。

以 Jellyfin 为例：

1. 在 Jellyfin 控制台创建 API Key。
2. 在 MoviePilot 中添加 Jellyfin 媒体服务器。
3. 填写 http://NAS局域网IP:8096 和 API Key。
4. 测试连接后保存。

常见问题

页面打不开

依次检查容器状态、日志、端口占用和 NAS 防火墙：

docker compose ps
docker compose logs --tail=200 moviepilot

下载器连接失败

• 确认 qBittorrent WebUI 可以在浏览器中打开。
• 检查地址、端口、用户名和密码。
• 使用容器名连接时，确认两个容器位于同一 Docker 网络。
• 使用局域网 IP 时，确认 qBittorrent 没有限制来源地址。

下载完成后没有整理

• 对照 MoviePilot 与下载器中的容器路径。
• 确认下载目录和媒体库的读写权限。
• 如果使用硬链接，确认两个目录处于同一文件系统和同一根目录映射。
• 查看 MoviePilot 日志中的转移或权限错误。

备份与升级

升级前至少备份映射到 /config 的宿主机目录。为了便于回退，也建议记录当前镜像版本和 Compose 文件。

docker compose pull
docker compose up -d
docker compose logs --tail=100 moviepilot

跨 V2、V3 等主版本升级时，不要只执行普通拉取命令。先阅读官方迁移说明，确认数据库和插件兼容性。

继续阅读

• MoviePilot 使用指南
• MoviePilot 插件使用
• MoviePilot 常见问题
• qBittorrent 部署教程
• qBittorrent 手动下载视频教程

参考资料

• MoviePilot 官方安装指引

最后复核：2026-09-11