你是否经历过这样的场景：想追一部周更的美剧，每周都要记得去站点搜资源、挑版本、添加下载，下完还要手动改名、移动到媒体库、刷新 Emby——一部剧追下来，重复劳动不计其数。
MoviePilot 要解决的正是这个问题：你只需点一次「订阅」，剩下的搜索、下载、识别、重命名、整理、刮削、入库、通知，全部自动完成。
本文基于 MoviePilot 官方 Wiki（wiki.movie-pilot.org）系统整理，分为三大部分：认识 MoviePilot → Docker Compose 部署实战 → 使用与进阶教程，带你从零走完媒体库自动化的完整闭环。
❌请勿在任何国内平台发布或引用此文章任何相关内容，请尽量避免在国内公共场合提及MoviePilot全称，如确实有需要请使用简称：MP。
第一部分：认识 MoviePilot
1.1 MoviePilot是什么
MoviePilot 是一款开源的 NAS 媒体库自动化管理工具，基于 NAStool 的部分代码重新设计，聚焦「自动化」这一核心需求，在减少历史问题的同时，架构上更易于扩展和维护。
它的定位非常清晰：作为家庭影音自动化链路的「中枢神经」，MoviePilot 负责 资源订阅下载 与 文件整理刮削 两大核心任务——你告诉它「我想看这部剧」，剩下的事（监控站点新资源、择优下载、识别元数据、重命名、整理入库、刮削海报、通知媒体服务器刷新）全部自动完成。
项目主要资源：
1.2 核心功能全景
核心功能全景
① 资源订阅与自动追更。 搜索电影、剧集后点击「订阅」即可加入追更列表。系统周期性刷新站点新资源（支持内置爬虫自动模式与站点 RSS 模式），对增量资源逐个识别匹配，命中即自动下载。支持洗版（出现更高优先级资源时自动替换下载）与订阅搜索（每 24 小时全站补搜防漏集）。
② 精准媒体识别。 「识别」是 MoviePilot 区别于一般下载工具的核心特性：内置针对 PT 资源命名优化的规则引擎，从标题提取关键信息后到 TheMovieDb / 豆瓣 / Bangumi 匹配元数据。识别失败的资源不会被下载和整理——宁可少下，也不下错。识别率还可通过自定义识别词、ChatGPT 类插件进一步增强。
③ 文件整理与刮削。 支持下载器监控（每 5 分钟）与目录实时监控（V2 内建）两种触发方式；整理方式涵盖硬链接、软链接、复制、移动、Rclone 复制/移动，满足保种、省空间、网盘同步等不同需求；基于 Jinja2 语法的自定义重命名格式配合二级分类策略，媒体库结构完全由你掌控；整理完成自动刮削元数据与海报，并可联动刷新 Emby/Jellyfin/Plex。
④ 站点管理。 支持 100+ 私有 PT 站点与 Nyaa、动漫花园等公开站点（清单见软件内「设定 → 关于」）。支持手动添加，也支持通过 CookieCloud 浏览器插件批量同步站点 Cookie 并定时更新；站点卡片直观展示连接状态（绿/黄/红），支持优先级、流控、代理、浏览器仿真等精细设置。
⑤ 优先级与过滤体系。 优先级是核心概念，统一遵循「数值越小越优先」，贯穿站点、目录、过滤规则、分类策略等场景。通过订阅/搜索/洗版优先级规则，可以精确描述「优先特效字幕、排除杜比、1080P 优先于 4K」这类复杂偏好。
⑥ 消息通知与远程交互。 支持企业微信、Telegram、Slack、SynologyChat、VoceChat、Discord、WebPush 等渠道。配置任一渠道即获得远程交互能力：聊天窗口发影片名即可搜索下载，发「订阅 + 名称」即可添加订阅；V2 支持按用户隔离通知，家庭成员各收各的消息。
⑦ 插件生态。 V2 插件市场已有 300+ 插件，默认内置 20 个官方与社区仓库，可一键「同步 Wiki」合并公开仓库。常用插件如站点自动签到、豆瓣想看/榜单订阅、IYUU 自动辅种、媒体库服务器刷新、ChatGPT 识别增强等。插件还能向智能助手注册 Agent 工具，扩展性极强。
⑧ AI 智能助手（V2 内置）。 真正的「智能体」能力而非问答机器人：内置工具 + 技能系统 + 插件扩展三层架构。你说「帮我搜《沙丘2》的资源，优先 2160p」「分析最近一次整理失败的原因并重试」，它会真的去查询、判断并执行。支持文本、图片、文件、语音多模态交互，可在 WEB、本地 CLI、Telegram/微信等渠道使用，还支持搜索结果 AI 推荐与整理失败智能接管。
⑨ 开放集成。 提供完善的 REST API 与 MCP Server，可在 Claude Code、OpenClaw 等第三方 Agent 工具中接入；通过模拟 Radarr/Sonarr API，与 Overseerr/Jellyseerr 无缝集成，实现多用户选片申请与审批。
1.3 适用场景
1.4 主要特点
聚焦自动化，准确优先：相比「搜到更多」，更在意「搜得更准」——所有搜索订阅默认经过元数据匹配过滤，从源头避免误下载。
部署方式多样：Docker（推荐）、Windows（exe 与安装版）、群晖 DSM7 套件、macOS/Linux 本地 CLI。
配置全部可视化：V2 几乎所有配置项可在 WEB 界面完成，配置优先级为「环境变量 > env 配置文件 / WEB 界面」。
生态完善：300+ 插件、官方资源包自动更新、Windows 版、移动端（MoviePilotLite）、Apple TV（MoviePilot-TV）、浏览器扩展（MoviePilot-Tools）等周边项目齐全。
拥抱 AI：内置智能助手、AI 推荐、MCP 开放接口，是同类工具中 AI 集成最深的之一。
企业级细节：支持 PostgreSQL、Redis 缓存、SQLite WAL、大内存模式、数据自动清理、插件热加载等进阶运维选项。
1.5 运行原理
┌─────────┐ 订阅/搜索 ┌────────────┐ 添加下载 ┌─────────┐
│ 用户 │ ───────────▶ │ MoviePilot │ ─────────▶ │ 下载器 │
│ (WEB/ │ │ │ │ QB / TR │
│ 微信/TG)│ ◀───────────│ │ ◀───────── │ │
└─────────┘ 通知提醒 └─────┬──────┘ 下载完成 └─────────┘
│
识别/重命名/刮削 ▼
┌────────────┐ 刷新媒体库 ┌─────────┐
│ 媒体库目录 │ ─────────▶│ Emby / │
│ (硬链接等) │ │ Jellyfin│
└────────────┘ │ / Plex │
└─────────┘
❗使用前需要准备：资源订阅下载功能需要有可用的 PT 站点账号，且至少一个站点支持用户认证（点击查看配置参考 | MoviePilot Wiki）、下载器（Qbittorrent ≥ 4.3.9 或 Transmission ≥ 3.0）、媒体服务器（Emby / Jellyfin / Plex），以及能顺畅访问 TheMovieDb 与 Github 的网络环境。
第二部分：Docker Compose 部署实战
Docker 是官方推荐的部署方式——镜像内置虚拟显示、浏览器仿真、内建重启、代理缓存等特性，一个容器即可承载完整功能。下面从环境检查开始，一步步完成部署。
2.1 环境要求
硬件与系统：支持 Docker 的 x86_64 / ARM64 设备（群晖/威联通 NAS、Linux 服务器、macOS、Windows Docker Desktop 均可），内存建议 2GB 以上。
软件依赖：Docker Engine 与 Docker Compose；可选装 Portainer 方便图形化管理：
docker run -d --restart=always --name="portainer" -p 9000:9000 \
-v /var/run/docker.sock:/var/run/docker.sock 6053537/portainer-ce
网络环境（关键前提）：MoviePilot 依赖两类外部服务
推荐使用「单独代理」或「全局代理」，网络质量更稳定。
代理配置教程查看这篇文章：Docker部署 Clash 代理完整指南 - 屋檐下的猫🐱
配套软件（需提前安装）：
2.2 部署前准备
① 目录规划（最重要的决策）。建议将下载目录与媒体库目录放在同一存储空间下，以便使用「硬链接」整理（一份文件两个入口，不占双倍空间且不影响做种）。推荐结构：
/media
├── downloads/ # 下载器实际保存目录（QB/TR 中也指向此目录）
│ ├── 电影/
│ └── 电视剧/
└── library/ # 媒体库目录（Emby/Jellyfin/Plex 扫描此目录）
├── 电影/
└── 电视剧/
要点：MoviePilot 的下载目录需与下载器的保存目录一致；推荐将宿主机
/media直接映射为容器内/media，路径完全一致可避免大量问题。
② 调整宿主机 inotify 限制。目录监控基于文件系统事件实现，文件较多时默认句柄数可能不足。在宿主机（不是容器内）执行：
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
echo fs.inotify.max_user_instances=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
③ 创建配置目录：
mkdir -p /moviepilot-v2/config # 持久化配置目录
mkdir -p /moviepilot-v2/core # 浏览器内核目录（避免每次启动重复下载）
2.3 快速部署（精简版）
适合大多数个人用户，使用内置 SQLite 与本地缓存，一个容器即可运行。
services:
moviepilot:
stdin_open: true
tty: true
container_name: moviepilot-v2
hostname: moviepilot-v2
image: jxxghp/moviepilot-v2:latest
restart: always
ports:
- '3000:3000' # WEB 管理界面端口
- '3001:3001' # API 服务端口
volumes:
- '/media:/media' # 媒体目录（下载 + 媒体库）
- '/moviepilot-v2/config:/config' # 持久化配置
- '/moviepilot-v2/core:/moviepilot/.cloakbrowser' # 浏览器内核持久化
- '/var/run/docker.sock:/var/run/docker.sock:ro' # 内建重启权限
environment:
- 'NGINX_PORT=3000'
- 'PORT=3001'
- 'PUID=0'
- 'PGID=0'
- 'UMASK=000'
- 'TZ=Asia/Shanghai'
- 'SUPERUSER=admin'
- 'SUPERUSER_PASSWORD=请修改为你的初始密码'
# - 'API_TOKEN=16位以上复杂字符串' # 可选，不设置则自动生成
# - 'PROXY_HOST=http://127.0.0.1:7890' # 可选，按需设置代理
如需让 MoviePilot 监控下载器种子做二次整理/辅种，可追加映射：
- '/tr/config/torrents:/torrents' # Transmission 种子位置
- '/qbittorrent/data/data/BT_backup:/BT_backup' # Qbittorrent 种子位置
启动：
docker compose up -d
2.4 全功能部署（PostgreSQL + Redis）
数据量较大或追求性能的用户，可使用 PostgreSQL 数据库与 Redis 缓存（数据库需 v2.7.3+）。以下 Compose 还包含 pgloader 服务，可将旧 SQLite 数据迁移至 PostgreSQL：
services:
moviepilot:
stdin_open: true
tty: true
container_name: moviepilot-v2
hostname: moviepilot-v2
image: jxxghp/moviepilot-v2:latest
restart: always
ports:
- '3000:3000'
- '3001:3001'
volumes:
- '/media:/media'
- '/moviepilot-v2/config:/config'
- '/moviepilot-v2/core:/moviepilot/.cloakbrowser'
- '/var/run/docker.sock:/var/run/docker.sock:ro'
- '/tr/config/torrents:/torrents'
- '/qbittorrent/data/data/BT_backup:/BT_backup'
environment:
- 'NGINX_PORT=3000'
- 'PORT=3001'
- 'PUID=0'
- 'PGID=0'
- 'UMASK=000'
- 'TZ=Asia/Shanghai'
- 'SUPERUSER=admin'
- 'SUPERUSER_PASSWORD=请修改为你的初始密码' # 请修改为你的初始密码
- 'PROXY_HOST=http://127.0.0.1:7890' # 代理配置改成自己的
- 'TMDB_API_KEY=XXXXX' # themoviedb的令牌密钥改成自己的
- 'GITHUB_TOKEN=ghp_XXXXX' # github令牌改成自己的
- 'AUTH_SITE=站点名称' # 认证站点名称改成自己的
- '站点名称_UID=XXXXX' # 认证站点用户ID改成自己的
- '站点名称_PASSKEY=XXXXX' # 认证站点秘钥改成自己的
# PostgreSQL 数据库配置
- 'DB_TYPE=postgresql'
- 'DB_POSTGRESQL_HOST=postgresql'
- 'DB_POSTGRESQL_PORT=5432'
- 'DB_POSTGRESQL_DATABASE=moviepilot'
- 'DB_POSTGRESQL_USERNAME=moviepilot'
- 'DB_POSTGRESQL_PASSWORD=pg_password' # 请修改你的数据库密码，需和下方POSTGRES_PASSWORD保持一致
# Redis 缓存配置
- 'CACHE_BACKEND_TYPE=redis'
- 'CACHE_BACKEND_URL=redis://:redis_password@redis:6379'
depends_on:
postgresql:
condition: service_healthy
redis:
condition: service_healthy
redis:
image: redis
volumes:
- /volume1/docker/redis/data:/data
command: redis-server --save 600 1 --requirepass redis_password
healthcheck:
test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
interval: 10s
timeout: 5s
retries: 5
postgresql:
image: postgres:18
restart: always
environment:
POSTGRES_DB: moviepilot
POSTGRES_USER: moviepilot
POSTGRES_PASSWORD: pg_password # 请修改你的数据库密码，需和上方DB_POSTGRESQL_PASSWORD保持一致
volumes:
# PostgreSQL 18.0+ 使用此路径；17.6 及以下改用 /var/lib/postgresql/data
- /volume1/docker/postgresql:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U moviepilot -d moviepilot"]
interval: 10s
timeout: 5s
retries: 5
# 可选：将已有 SQLite 数据迁移到 PostgreSQL（迁移完成后可移除该服务）
# pgloader:
# image: dimitri/pgloader:latest
# volumes:
# - /moviepilot-v2/config:/mp_config
# command: >
# pgloader
# sqlite:///mp_config/user.db
# postgresql://moviepilot:pg_password@postgresql:5432/moviepilot
# depends_on:
# postgresql:
# condition: service_healthy
注意：切换 PostgreSQL 前请备份原 SQLite 数据库；若是先升级到 v2.7.3+ 再切换数据库，需在 PostgreSQL 中执行
update alembic_version set version_num = 'd58298a0879f';后重启。使用 Redis 后本地文件缓存自动迁移到 Redis，可降低主程序内存占用。
2.5 环境变量参数详解
基础部署参数：
网络与加速参数：
升级与存储参数：
用户认证参数：推荐登录后通过「用户头像 → 用户认证」在前端完成；自动化部署可用环境变量，例如：
- 'AUTH_SITE=iyuu' # 认证站点，多个用逗号分隔，依次尝试直到成功
- 'IYUU_SIGN=你的IYUU登录令牌'
认证站点变量（完整清单见官方 Wiki「配置参考」）：配置参考 | MoviePilot Wiki
HTTPS 参数（仅 Docker 环境）：ENABLE_SSL、SSL_DOMAIN、SSL_NGINX_PORT（默认 443）、SSL_EMAIL、AUTO_ISSUE_CERT（acme.sh 自动签发，仅 DNS 认证）、DNS_PROVIDER、ACME_ENV_xx。
配置优先级：
环境变量>env 配置文件==WEB 界面。已通过环境变量注入的项，前端与app.env中的同名配置不会覆盖它。
2.6 启动、验证与首次登录
# 启动
docker compose up -d
# 查看实时日志（首次启动会执行更新与初始化，需耐心等待）
docker logs -f moviepilot-v2
获取初始密码：已设置 SUPERUSER_PASSWORD 则直接使用；未设置时系统生成随机复杂密码，在日志中查找：
grep "超级管理员" /moviepilot-v2/config/logs/moviepilot.log
浏览器访问 http://服务器IP:3000 登录后，依次完成三件事：
设定 → 用户修改管理员密码（不要弱密码，非必要不暴露公网——账号被盗将导致站点 Cookie 等敏感数据泄露）；检查
设定 → 系统 → 基础设置 → API令牌：若API_TOKEN不满足 16 位复杂度要求，每次启动都会重新生成，请尽快修改固定；按第三部分教程完成站点认证、目录、下载器、媒体服务器等配置。
2.7 反向代理与 HTTPS
如需域名访问，以 Nginx 为例，必须包含以下配置项，否则部分功能无法访问：
location / {
proxy_pass http://ip:port;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
使用 SSL 时还需开启 http2，否则日志加载可能过慢或不可用：
server {
listen 443 ssl;
http2 on;
# ...
}
代理连接超时时间应尽量长（如 10 分钟），避免流式搜索、日志等长连接请求被代理提前中断。
2.8 升级与日常维护
自动升级：设置 MOVIEPILOT_AUTO_UPDATE=release 与 AUTO_UPDATE_RESOURCE=true 后，重启容器即可自动升级到最新正式版并保持站点资源包最新；由于映射了 docker.sock，可直接在 WEB 界面选择重启。
手动升级：
docker compose pull
docker compose up --force-recreate -d
正常映射了
/config目录的前提下，重置/重建容器不会导致配置丢失（群晖为右键「重置」，Portainer 为容器详情页「重建」）。
备份：定期备份 /moviepilot-v2/config 目录即可完整保留配置、数据库（SQLite 模式）与插件数据。
第三部分：使用与进阶教程
部署完成只是起点。本部分按「初始配置 → 功能模块 → 进阶玩法」的顺序，带你把 MoviePilot 真正用起来。
3.1 初始配置
登录与密码：浏览器访问 http://服务器IP:3000，使用超级管理员账号（默认 admin）与初始密码登录，第一时间在 设定 → 用户 中修改密码。
API_TOKEN 检查：设定 → 系统 → 基础设置 → API令牌，V2 要求 16 位以上复杂字符串。该令牌用于媒体服务器 Webhook、消息回调、MCP 等所有对外服务地址。
用户认证（关键步骤）：资源搜索、订阅、下载功能必须先通过站点用户认证。三种方式任选（推荐前两种）：
首次安装的初始化向导中直接完成认证；
点击右上角用户头像 → 用户认证，系统动态列出当前支持的认证站点；
或添加环境变量
AUTH_SITE+ 对应站点参数（适合自动化部署）。
基础设置一览：
3.2 站点管理
手动添加站点：进入「站点管理」，点击右下角 +：
CookieCloud 快速添加（推荐）：
浏览器安装 CookieCloud 插件，登录各站点后同步 Cookie 到服务端；
设定 → 站点中配置 CookieCloud 参数（服务器地址、用户 KEY、加密密码）并开启同步——可使用 MP 内置本地服务或独立服务端，与浏览器插件地址保持一致；设定 → 服务中手动运行一次「同步CookieCloud站点」，自动添加站点、生成 RSS 链接和图标，并按设定间隔（默认 24 小时）定时更新 Cookie。
站点维护：站点卡片的「更新」按钮可输入用户名密码自动模拟登录刷新 Cookie（依赖浏览器内核与 OCR，非 100% 成功）；卡片右上角图标显示连接状态——🟢 正常、🟡 慢（>5 秒）、🔴 无法连接；设定 → 规划 → 下载规则 选择「站点优先级」时，卡片顺序影响下载选择策略。
3.3 目录与整理设置
下载目录：设定 中添加，注意 Docker 部署时根路径必须映射到容器内，且需与下载器中的保存目录一致；支持多目录按优先级依次匹配。
媒体库目录与分类：支持两级分类体系——一级为媒体类型（电影/电视剧，固定），二级为媒体类别（由分类策略结合 TMDB 元数据确定，如华语电影、日韩剧）。目录项三个选项的配合逻辑：
常见方案（根目录 /video）：
# 方案一：一二级全自动分类
路径 /video，类型：全部，类别：全部，自动分类：开
# 方案二：一级手动、二级自动
路径 /video/电影，类型：电影，类别：全部，自动分类：开
路径 /video/电视剧，类型：电视剧，类别：全部，自动分类：开
# 动漫独立一级目录（需先在 category.yaml 配好动漫二级分类）
路径 /video/动漫，类型：电影，类别：动画电影
路径 /video/动漫，类型：电视剧，类别：国漫
整理方式（设定 → 目录 → 整理模式）：
覆盖方式（媒体库已存在同名文件时）：从不覆盖（中断并报错）/ 按大小覆盖 / 总是覆盖 / 仅保留最新版本（删除其它所有版本，配合洗版使用）。
自动整理触发：下载器监控每 5 分钟一次；目录监控为实时（请勿对网盘目录使用，易触发流控）；QB 用户还可在「设置 → 下载完成时运行外部程序」填入 curl "http://localhost:3000/api/v1/transfer/now?token=你的API_TOKEN" 实现秒级入库。
3.4 下载器与媒体服务器
下载器：设定 → 连接 → 下载器 中添加 Qbittorrent（≥4.3.9）或 Transmission（≥3.0）。添加下载时会打上 MOVIEPILOT 标签，并通过「下载文件自动整理」开关监控完成状态。
qbittorrent部署教程：【NAS教程】docker部署qbittorrent下载器 - 屋檐下的猫🐱
媒体服务器：支持 Emby（建议 ≥4.8.0.45）、Jellyfin、Plex。配置后 MoviePilot 会：通过 API 查询库存避免重复下载；按 MEDIASERVER_SYNC_INTERVAL（默认 6 小时）同步媒体库数据；接收 Webhook——在媒体服务器 Webhook 插件中配置 http://ip:3001/api/v1/webhook?token=你的API_TOKEN（同类型配置多个时追加 &source=配置名称）。
Overseerr/Jellyseerr 集成（可选）：MoviePilot 模拟 Radarr/Sonarr API，可作为 Overseerr 后端——Overseerr 负责多用户选片与审批，MoviePilot 负责订阅、下载与整理。
3.5 搜索功能
搜索媒体信息：点击搜索图标或按 Ctrl+K / Cmd+K 打开聚合搜索窗口；设定 → 搜索 → 媒体数据源 设置展示来源与排序。
搜索资源：
先在
设定 → 搜索 → 搜索站点圈定站点范围（站点越多越慢）；在
设定 → 搜索 → 过滤规则全局排除不想要的资源，例如无杜比设备可排除：Dolby[\s.]+Vision|DOVI|[\s.]+DV[\s.]+|杜比视界；两种方式——精确搜索（点击媒体卡片/详情页搜索图标，结果经识别匹配过滤，只含该媒体资源）与模糊搜索（聚合窗口选「站点资源」，直接展示站点返回数据，不经过滤，适合精确搜索无结果时补充）；
V2 采用流式搜索：实时显示进度与预览结果，页面保持可交互；代理不支持流式时自动回退。
精确搜索依赖识别源与展示源一致；若因 TMDB 与豆瓣/Bangumi 数据不一致导致无法搜索，请重新搜索媒体并选择与识别源一致的数据源浏览。
AI 智能推荐：配置智能助手并开启 AI_RECOMMEND_ENABLED 后，搜索结果页可执行「AI智能推荐」，对当前结果二次筛选排序；原始结果与 AI 推荐结果切换时筛选条件自动保存与恢复。
3.6 订阅与自动追更
添加订阅：搜索媒体后点击卡片 ❤️ 或详情页「订阅」。添加后系统 3 分钟内对全订阅站点做一次搜索补全存量资源，未下全的进入「订阅刷新」循环。
订阅模式（设定 → 订阅）：
每次刷新只处理站点增量资源，逐个识别匹配并缓存，命中订阅即下载。
订阅搜索（防漏集）：站点列表页与 RSS 均有条数限制，更新频繁时可能漏集。开启后系统每隔 24 小时对订阅做一次全站搜索补漏（间隔固定）。未出现漏订阅建议不开启，以免给站点造成压力。
洗版：开启后匹配到更高优先级资源会继续下载，直到拿到洗版优先级中的最高版本。注意：仅完结状态剧集支持洗版；需配合覆盖策略（「总是覆盖」或「仅保留最新版本」），或在重命名规则中加入质量要素实现多版本共存。
订阅站点与编辑：全局范围在 设定 → 订阅 → 订阅站点；「编辑订阅」可单独设定站点范围与识别词，还可将订阅分享给其他用户。
远程订阅：配置任一消息渠道后，聊天客户端发送「订阅 + 影片名称」即可远程添加。
3.7 文件整理与历史记录
自动整理：下载完成的文件被自动识别、重命名、转移并刮削入库；识别失败的资源不会被整理，会在历史记录中留下失败记录。
手动整理：
历史记录：找到失败记录，手动修正媒体信息后重新整理；文件管理：浏览文件系统，对单个文件或整个目录发起整理；批量手动整理：选择整个目录，或历史记录按关键字筛出某剧集全选「重新整理」。整理对话框的实用字段：
自动重新整理：全部留空，使用内置识别重新整理；
指定集数：如
1、1-2（合并集）、1,3；集数定位：
{ep}占位符标定集数位置，如(BD)十二国記 第{ep}話{a}(1440x1080 x264-10bpp flac).mkv；集数偏移：解决合集/多季集数错位，如
-10，或用EP运算（EP*2-1）。
历史记录中的两种重新处理：「重新整理」（已知正确媒体信息时手工修正）与「智能助手整理」（失败原因复杂时调用智能助手重新分析，需启用 AI_AGENT_ENABLE，过程实时滚动显示）。
/redo 命令（消息渠道）：
/redo [id]
/redo [id] [tmdbid/豆瓣id]|[类型]
3.8 通知与远程交互
通知渠道（设定 → 通知）要点：
消息回调统一地址：http(s)://域名:端口/api/v1/message/?token=你的API_TOKEN；同类型配置多个时追加 &source=配置名称。
通知隔离（多用户）：在用户个人信息中维护通知渠道 ID，并按消息类型设定发送范围——交互类消息只有操作人收到；用户主动操作（下载、订阅）可发给操作人/管理员/全体；系统广播类消息可发给管理员或全体。
远程交互能力：配置任一渠道后即可——发影片名搜索下载、发「订阅 + 名称」加订阅、使用 /redo、/skills 等命令；已启用智能助手时，消息入口同时支持 AI 交互（文本、图片、文件、语音）。
3.9 插件生态
插件市场：V2 已有 300+ 插件，默认内置 20 个官方与社区仓库；「插件市场设置」中点击「同步 Wiki」可自动合并 Wiki 收录的公开仓库。也可手动在 PLUGIN_MARKET 添加第三方仓库（仅支持 Github 仓库 main 分支，逗号分隔）。插件安装升级依赖 Github 连通性，建议配置 GITHUB_TOKEN、GITHUB_PROXY、PIP_PROXY 与代理。
常用插件：
配置中心、站点数据统计、目录监控等 V1 热门插件在 V2 已内置，无需安装。部分插件提供数据页面与仪表板组件，启用后可在仪表盘展示。
3.10 AI 智能助手
启用配置（最少四项）：设定 → 系统 → 基础设置 打开「启用智能助手」（AI_AGENT_ENABLE），选择 LLM提供商，填写 LLM API密钥，填写或刷新选择 LLM模型名称，点击「测试调用」验证。可选增强：全局智能助手（消息对话默认走智能体）、图片输入（多模态模型建议开启）、音频输入/语音回复（独立配置 AUDIO_INPUT_* / AUDIO_OUTPUT_*）、搜索结果智能推荐、文件整理失败智能接管。
能力范围：智能助手 = 读取上下文 + 调用 MoviePilot 工具 + 按技能流程执行，覆盖媒体检索与推荐、资源搜索与下载、订阅管理与缺集处理、文件整理与媒体库查询、站点/下载器/工作流排障、插件命令分发。典型说法：
「帮我搜《沙丘2》的资源，优先 2160p 和免费」
「看看《人生切割术》订阅过没有，没有就帮我加上」
「分析最近一次整理失败，能修就直接重试」
「测试一下这个站点的连通性」
使用入口：WEB（搜索页「AI智能推荐」、历史记录「智能助手整理」）、CLI（moviepilot agent 帮我检查当前配置）、消息渠道（直接对话，/skills 管理技能市场）。
权限边界：查询类能力可直接使用；修改配置、删除记录、执行命令、运行工作流等高风险操作需管理员权限。MCP 与 Agent API 使用 API_TOKEN 认证，持有该密钥的客户端视为受信任的管理员级集成，请只配置给信任的客户端。
3.11 进阶玩法
① 优先级规则（订阅/搜索/洗版三套）：
按顺序匹配，第一个匹配通过的规则即该资源的优先级，全部不匹配则被过滤；
数字越小优先级越高，越先被下载；
同一规则内各规则项为「与」关系，同类型规则项不能同时选择；
全局排除某规则项时，所有规则都要排除它。
示例（优先特效/中文字幕，排除杜比与蓝光原盘，仅限 4K 和 1080P，1080P 优先）：
SPECSUB & !BLU & !DOLBY & 1080P > CNSUB & !BLU & !DOLBY & 1080P > SPECSUB & BLU & !DOLBY & 4K > CNSUB & !BLU & !DOLBY & 4K
规则支持「分享/导入」，可快速复用他人配置。
② 自定义识别词（捷径 → 词表）：对命名不规范的资源用正则校正，支持四种格式（注意连接符两侧空格）：
屏蔽词
被替换词 => 替换词
前定位词 <> 后定位词 >> 集偏移量（EP）
被替换词 => 替换词 && 前定位词 <> 后定位词 >> 集偏移量（EP）
替换词支持 {[tmdbid/doubanid=xxx;type=movie/tv;s=xx;e=xx]} 直接指定识别结果（不要把原标题整个替换掉）；集偏移支持运算（EP+1、2*EP-1）。社区共享识别词可通过「共享识别词」插件订阅自动更新；若出现大面积识别异常，先排查共享词表。识别测试可用 WEB 右上角 捷径 → 识别。
③ 自定义重命名（Jinja2 语法，设定 → 目录 中编辑）。默认模板：
{# 电影 #}
{{title}}{% if year %} ({{year}}){% endif %}/{{title}}{% if year %} ({{year}}){% endif %}{% if part %}-{{part}}{% endif %}{% if videoFormat %} - {{videoFormat}}{% endif %}{{fileExt}}
{# 电视剧 #}
{{title}}{% if year %} ({{year}}){% endif %}/Season {{season}}/{{title}} - {{season_episode}}{% if part %}-{{part}}{% endif %}{% if episode %} - 第 {{episode}} 集{% endif %}{{fileExt}}
可用变量包括 title、en_title、year、videoFormat、videoCodec、videoBit、audioCodec、releaseGroup、resourceType、edition、tmdbid、imdbid、doubanid 等；电视剧额外有 season_fmt（S01）、season_episode（S01E02）、episode_title 等。建议对每个变量加 {% if %} 判空。示例（文件名加入编码与位深）：
{{title}}{% if year %} ({{year}}){% endif %}/{{title}}{% if year %} ({{year}}){% endif %}{% if videoCodec %} - {{videoCodec}}{% endif %}{% if videoBit %} {{videoBit}}{% endif %}{{fileExt}}
④ 二级分类策略：编辑 /config/category.yaml（或用「二级分类策略」插件），按 genre_ids、original_language、origin_country/production_countries、release_year 等条件从上到下依次匹配，! 前缀表示排除；同分类下多条件为「与」，单条件多值（逗号分隔）为「或」。修改后目录设置中「自动分类」即按新策略生成二级目录。
3.12 日常使用流程速查
看一部新电影：
Ctrl+K搜影片 → 详情页点搜索 → 选资源下载（或直接点订阅）→ 完成后收到通知 → 媒体服务器已自动刷新可观看。追一部周更剧：搜到剧集点 ❤️ 订阅 → 系统每日自动刷新站点增量资源 → 出新集自动下载整理入库 → 微信/Telegram 收到「完成订阅」通知。
豆瓣联动：安装「豆瓣想看」插件 → 豆瓣 App 标记想看 → 自动订阅下载。
整理失败处理：
历史记录找到失败记录 → 能确定原因就手动重新整理 → 不确定就点「智能助手整理」。远程操作：聊天窗口发「订阅 片名」加订阅；发片名搜资源；
/redo id重整理；/skills管理 AI 技能。
第四部分：常见问题 FAQ
结语
MoviePilot 把「找片—下载—整理—刮削—入库—通知」这条原本需要多个工具和大量手工操作的链路，压缩成了一次点击：
对新手：Docker Compose 一键部署 + 初始化向导引导，半小时即可跑通「订阅 → 入库 → 通知」全流程；
对进阶玩家：优先级规则、识别词、分类策略、洗版机制提供了足够精细的控制粒度；
对折腾爱好者：300+ 插件、开放 API、MCP 接口与内置 AI 助手，能力边界还在不断扩展。
无论你是刚入坑 NAS 的新手，还是拥有几十 TB 影音库的资深玩家，它都能显著降低媒体库的维护成本。
参考资源：
官方 Wiki：https://wiki.movie-pilot.org
GitHub 主仓库：https://github.com/jxxghp/MoviePilot
API 文档：https://api.movie-pilot.org
免责声明：本文仅为软件使用教程整理，内容来自公开官方文档。请遵守各站点规则与当地法律法规，仅下载和使用你有权访问的内容。
❌请勿在任何国内平台发布或引用此文章任何相关内容，请尽量避免在国内公共场合提及MoviePilot全称，如确实有需要请使用简称：MP。