jxxghp/moviepilot-v3 Docker Image

MoviePilot V3：NAS 媒体库自动化管理工具

一、概述

MoviePilot V3 是面向个人与家庭 NAS 场景的新一代媒体库自动化管理工具。它基于前后端分离架构，把影视信息检索、订阅追更、下载调度、文件重命名整理，以及与媒体服务器的联动整合到同一套工作流中，减少手工维护成本。

典型用法是：对接 qBittorrent、Transmission 等下载客户端，自动匹配并下载资源；下载完成后按自定义规则重命名并整理进媒体库目录；再通知 Plex、Emby、Jellyfin 刷新媒体库。配合插件市场与智能助手，可按需求扩展自动化能力。

官方镜像仓库为 jxxghp/moviepilot-v3，支持 linux/amd64 与 linux/arm64。国内环境可通过轩辕镜像加速拉取。

二、核心功能

1. 智能搜索与订阅

自动搜索并匹配电影、电视剧等媒体信息，支持订阅管理与追更。可在仪表盘统一查看媒体库状态，用订阅日历按日期查看更新与入库进度。

2. 自动下载管理

按设定规则自动下载资源，支持 qBittorrent、Transmission 等主流下载客户端。可将种子目录映射进容器，便于识别下载任务与完成状态。

3. 智能重命名与整理

按自定义命名格式对媒体文件重命名并整理到目标目录，保持媒体库结构清晰，方便媒体服务器识别刮削。

4. 媒体服务器集成

可对接 Plex、Emby、Jellyfin 等主流媒体服务器，整理完成后自动触发库刷新，缩短从下载到可看的时间。

5. 多样化通知

支持微信、***、Slack 等多种通知渠道，及时掌握下载、整理、订阅更新等系统状态。

6. 插件生态与智能助手

采用插件化架构，官方与社区插件数量丰富，可按需安装扩展功能。内置智能助手支持自然语言等方式触发搜索、订阅、下载、整理等常用操作。

三、V3 版本要点

• 独立镜像：正式版使用 jxxghp/moviepilot-v3:latest，也可按版本号拉取，如 3.2.5。
• 配置兼容：V3 兼容 V2 的配置与数据库数据；从 V2 切换时保留原 /config 映射即可，无需单独迁移用户数据。
• 必须重建容器：不能只在 V2 容器内“重启升级”。应先备份，再将镜像改为 V3、拉取并重建容器。
• 内置进程管理：镜像内通过 supervisor 托管 Nginx 与后端；Web 内建重启由容器内完成，一般无需映射 /var/run/docker.sock。
• 优雅停止：停止时会依次收尾后台任务与插件，建议设置 --stop-timeout 120（Compose 中为 stop_grace_period: 120s）。
• 首次初始化：全新安装不会预置管理员账号。首次访问 Web 时进入初始化页，设置管理员用户名、密码并生成 API Key，再登录使用。
• 单向数据库升级：V3 完成数据库升级后，不能直接换回 V2 镜像；如需回退，请按官方文档操作。

四、快速开始

1. 拉取镜像

bash
docker pull docker.xuanyuan.run/jxxghp/moviepilot-v3:latest

2. Docker Run（单容器，适合入门）

将下面路径按实际环境修改：/media 为媒体与下载共同根目录（计划使用硬链接时，下载目录与媒体库应位于同一根目录下）；/moviepilot-v3/config 为配置持久化目录；/moviepilot-v3/core 为内置浏览器内核数据目录。

bash
docker run -itd \
  --name moviepilot-v3 \
  --hostname moviepilot-v3 \
  --network bridge \
  -p 3000:3000 \
  -p 3001:3001 \
  -v /media:/media \
  -v /moviepilot-v3/config:/config \
  -v /moviepilot-v3/core:/moviepilot/.cloakbrowser \
  -e NGINX_PORT=3000 \
  -e PORT=3001 \
  -e PUID=0 \
  -e PGID=0 \
  -e UMASK=000 \
  -e TZ=Asia/Shanghai \
  --stop-timeout 120 \
  --restart always \
  docker.xuanyuan.run/jxxghp/moviepilot-v3:latest

3. Docker Compose（单容器示例）

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

启动：

bash
docker compose up -d

4. 访问与初始化

浏览器打开：http://宿主机IP:3000

按页面提示完成管理员账号与 API Key 初始化后即可登录。默认 Web 端口为 3000，后端端口为 3001（通常只需对外映射 Web 端口）。

五、常用参数说明

进阶场景可外挂 PostgreSQL、Redis，或按需映射下载器种子目录（如 qBittorrent 的 BT_backup、Transmission 的 torrents 目录）。具体环境变量与 Compose 全功能示例见官方安装文档。

六、使用与升级提示

1. 硬链接整理：若使用硬链接，请保证下载目录与媒体库目录位于同一文件系统挂载点下（例如都在 /media 下）。
2. 权限：PUID/PGID 建议与媒体目录所有者一致，避免下载或整理时报权限错误。
3. 从 V2 升级：先备份配置目录；将 Compose/Run 中的镜像改为 jxxghp/moviepilot-v3，保留原 /config（以及如有的 PostgreSQL、Redis 数据卷），执行 pull 后重建容器。未适配 V3 契约的插件需安装开发者提供的 V3 版本。
4. 更新本版本：

bash
docker pull docker.xuanyuan.run/jxxghp/moviepilot-v3:latest
docker compose up -d --force-recreate

5. 查看日志：

bash
docker logs -f moviepilot-v3

七、相关链接

• 项目官网：[***]
• 使用文档：[***]
• 后端项目：https://github.com/jxxghp/MoviePilot
• 前端项目：https://github.com/jxxghp/MoviePilot-Frontend
• 插件项目：https://github.com/jxxghp/MoviePilot-Plugins
• Docker Hub：https://hub.docker.com/r/jxxghp/moviepilot-v3