MoviePilot-V3配置完全指南-博客版

MoviePilot-V3配置完全指南-博客版

MoviePilot V3 配置完全指南:从安装到自动分类策略

  V3 把过去一大半靠环境变量的配置搬进了 Web 界面。这份指南按「能照着点」的顺序,从安装、认证、三台下载器、目录结构,一路讲到 V3 全新的自动分类策略引擎——分类树、条件规则、结果预览、影响分析、版本回退,全部拆开讲。

  适用版本:MoviePilot V3 | 界面来源:V3 前端源码 + 官方 Wiki | 场景:Windows 主控 + 三下载器跨机 | 约 20 张界面还原图

  1. 先看全局:这套配置要做什么
  2. V3 与 V2 的 5 个关键差异
  3. 安装与初始化
  4. 用户认证
  5. 下载器:三台 qB 怎么配
  6. 目录:资源目录与媒体库目录
  7. 先认路:V3 的菜单和设定页
  8. 分类策略在哪:三个工作区
  9. 第一步:在「分类树」里建分类
  10. 第二步:在「规则」里写匹配条件
  11. 第三步:验证、预览、发布
  12. 回到目录:让分类真正生效
  13. 一套可以直接抄的分类方案
  14. 字段与操作符速查
  15. 站点:CookieCloud 同步与下载器绑定
  16. 规则与词表
  17. 媒体服务器与通知
  18. 重命名格式
  19. 插件与自启动
  20. 避坑清单
  21. 验收清单

这份指南讲的是哪一种部署
一台 Windows 主机跑 MoviePilot,同时管理 三个 qBittorrent 下载器(一台本机、两台局域网里的 fnOS 小主机);媒体库不在本地,而在挂载出来的云盘目录上,由 Emby 负责播放。
这个形态比单机单下载器复杂,踩的坑也集中——路径映射、整理方式、下载器分流的限制,本文都会讲到。如果你只是单机单下载器,绝大部分内容同样适用,跳过跨机相关的小节即可。

一、先看全局:这套配置要做什么

  整套系统里,MoviePilot 的角色是调度中枢:它从 PT 站找资源、把任务派给某台下载器、等下载完成后把文件按规则整理进媒体库、再通知 Emby 刷新。它自己不做下载,也不做播放。

角色 跑在哪 负责什么
主控 + 媒体服务 Windows 11 主机 MoviePilot v3、Emby、云盘挂载客户端、qBittorrent(01 号)、代理
下载机 2 fnOS 小主机 A qBittorrent(02 号)+ SMB 共享下载目录
下载机 3 fnOS 小主机 B qBittorrent(03 号)+ SMB 共享下载目录
媒体库 云盘(挂载为本地盘符) 电影 / 电视剧 / 音乐,由 Emby 扫描播放

  配置顺序上有一条主线:下载器和目录必须先于站点。因为站点要绑定下载器、整理要读目录,顺序反了会出现在下拉框里选不到东西的情况。

  • 安装与初始化——让服务跑起来,拿到管理员账号和 API Key。
  • 用户认证——不认证,搜索和下载功能全是灰的。
  • 三个下载器——连接测试通过,跨机的两个填好路径映射。
  • 目录结构——下载目录、媒体库目录,以及分类开关怎么设。
  • 自动分类策略——V3 的重头戏,分类树 + 规则 + 验证发布。
  • 站点、规则、媒体服务器、通知——把链路接通。
  • 插件与自启动——让它长期稳定地跑下去。

二、V3 与 V2 的 5 个关键差异

  先看这 5 条,决定你照哪份教程配。网上大部分中文教程还是 V2 的,直接照抄会踩坑。

差异 V2 的做法 V3 的做法
① 首次初始化 有独立设置向导,或靠环境变量 SUPERUSER / API_TOKEN 指定 不再提供设置向导。首次启动在 Web 初始化页面创建管理员和 API Key,这三项在配置文件里默认留空
② 配置载体 下载器、目录、媒体服务器、通知大量依赖环境变量 改为 Web UI 结构化配置,官方明确不建议写环境变量;只有前端没有入口的项才写配置文件
③ 音乐 没有独立音乐类型 音乐成为与电影、电视剧并列的独立媒体类型,有独立的重命名格式和分类体系
④ 分类策略 手写一份 YAML 文件,写完重启,效果靠猜 可视化规则引擎:分类树、可拖拽条件树、结果预览、影响分析、版本回退,全部在界面里完成
⑤ 菜单路径 设定 → 系统 → 存储 & 目录 设定 → 存储 & 目录(独立一级入口),整理、刮削、分类都在这里

一句话总结
V3 里「能点的都在界面上点,别再往配置文件里塞下载器地址和目录路径了」——那套写法是 V2 的,V3 写了要么不生效,要么和界面配置打架,排查起来极难。

三、安装与初始化

3.1 安装 Windows 版

  Windows 版是官方 Wiki「周边项目」收录的社区项目 developer-wlj/Windows-MoviePilot,不是第三方魔改,按仓库 README 下载发行包解压即可。建议解压到 D:\MoviePilot,不要放桌面或系统盘——保种和整理 IO 频繁,系统盘容易被拖慢。

  • Web 端口用 3000,API 端口用 3001,两者不能冲突。
  • 配置目录独立于程序目录存放,删程序不会丢配置。
  • 装好后先在「设定 → 系统」里把自动更新策略定为 release(只跟正式版),别用开发版——保种机不适合天天变。

3.2 首次启动初始化

  这是 V3 最明显的变化:没有设置向导了。第一次打开 http://主机地址:3000,只会看到一个初始化页面,创建唯一的超级管理员并生成 API Key。

图 1 V3 首次启动的初始化页面。没有向导、没有下一步,一次填完管理员账号和 API Key 就进主界面。

API Key 一定要当场记下来
它是三件事的唯一凭据:媒体服务器的 Webhook 回调、下载器下载完成后的即时整理回调、以及以后接入外部工具。丢了虽然能重置,但三处配置都得跟着改一遍。

3.3 配置文件只写界面上没有的项

  V3 的配置文件(app.env)只用来放界面上没有入口的项。下面这份是精简版,只留真正需要写的:

`# ---------- 基础 ----------
NGINX_PORT=3000
PORT=3001
TZ=Asia/Shanghai
# V3 不需要在这里写管理员账号和 API Token,初始化页面已生成

# ---------- 网络与代理 ----------
# 只给 MoviePilot 自己走代理:刮削元数据、检查更新用得上
# 代理软件保持「不开系统代理、不开 TUN」,PT 与播放流量绝不经过它
PROXY_HOST=http://127.0.0.1:7890

# ---------- 更新策略 ----------
MOVIEPILOT_AUTO_UPDATE=release
AUTO_UPDATE_RESOURCE=true

# ---------- 媒体整理(跨机场景必改) ----------
TRANSFER_THREADS=2
# 1 = 关闭多线程;跨机复制开 2 能明显缩短大文件整理时间

# ---------- 数据清理(可选,保种机建议开) ----------
DATA_CLEANUP_ENABLE=true
DATA_CLEANUP_MESSAGE_DAYS=90
DATA_CLEANUP_TRANSFER_HISTORY_DAYS=1095`

别写这些
DOWNLOAD_PATH、LIBRARY_PATH、TRANSFER_TYPE、QB_HOST、DOWNLOADER——这些在 V3 都是 Web UI 的结构化配置,写进配置文件属于给自己埋雷(两边不一致时排查极难)。

配置优先级(官方原文)
环境变量 > env 配置文件 == WEB 界面。只要某项已通过环境变量注入,前端界面和配置文件中的同名项都不会覆盖它。所以不要用环境变量去锁那些你以后想在界面上改的项。

四、用户认证

  V3 已经可以在界面上完成认证,不需要再配环境变量。用你手上任意一个支持认证的 PT 站账号即可。可认证的站点清单在「头像 → 关于 MoviePilot」里查看。

图 2 右上角头像 → 用户认证。站点、UID、Passkey 三样填完点「认证」,成功后整个系统的下载能力才打开。

为什么这一步不能跳
自动订阅、站点搜索、刷流、自动删种,全部建立在认证身份上。这一步跳过,后面大部分功能都是摆设——按钮是灰的,或者点了报「未认证」。

五、下载器:三台 qB 怎么配

  V3 的下载器在 Web UI 配置,而且原生支持多实例。三个实例都要加,但只有主控机上那台打开「默认」开关——默认下载器是「没被站点指定的任务」的兜底去处。

图 3 下载器列表。名称前的小绿点代表连接成功;只有主控机上那台亮着「默认」。

怎么判断连上了
保存后下载器名称前出现小绿点就是连上了。没有绿点,先在浏览器里直接打开那个 qB 的 WebUI 地址,确认它自己能访问——地址、账号、防火墙,按这个顺序排查。

5.1 三个实例的字段差异

字段 01 号(主控机) 02 / 03 号(下载机)
启用 开 开
默认 开(全系统只有一个) 关
地址 本机 127.0.0.1:8080 局域网地址 192.168.1.12:8080 / .13:8080
用户名 / 密码 本机 qB 账号;qB 5.2+ 可直接填 WebUI API Key,填了优先用它登录 对应下载机的 qB 账号
路径映射 不需要(同机,路径一致) 必填,见下
顺序下载 / 优先首尾文件 / 未完成文件后缀 建议全开 建议全开

5.2 路径映射:跨机场景最容易配错的一处

  下载机跑在 Linux 系统里。MoviePilot 在主控机上,看到的是网络共享路径(UNC);而下载机上的 qB 是 Linux 程序,只认它自己的本地路径。两边对不上,任务就会存到错误位置或直接失败。

图 4 下载器的路径映射。左边填主控机能访问的共享路径,右边填下载机上 qB 实际使用的本地路径。

不填的后果
MoviePilot 告诉 qB「把文件存到 \\192.168.1.12\Downloads」,而 qB 是 Linux 程序,这个路径根本不存在 → 任务报错或落到默认目录,后续整理整条链断掉。

前置条件:共享凭据要先存好
主控机要能读到那个共享路径,必须先在下载机上开好 SMB 共享,并在 Windows 的凭据管理器里存好访问凭据(用服务账户能读到的身份)。否则即使路径映射填对,整理阶段还是会报「文件找不到」。

5.3 下载完成即时整理

  官方推荐做法:让 qB 在下载完成后主动通知 MoviePilot 立刻整理,不用等轮询。这招在跨机多下载器场景下价值翻倍——它绕开了「默认只监控第 1 个下载器」的限制。

图 5 在每台 qB 的「下载完成时运行外部程序」里填这条回调,下载一完成就通知主控机整理。

官方关于多下载器的一条限制
「如启用了多个下载器,默认只会监控整理第 1 个下载器的下载任务。如果设定了下载器种子标签,则只有下载器中有对应标签的下载任务才会被自动整理。」
所以跨机场景有两个保险:① 保持下载器种子标签为默认的 MOVIEPILOT(下发的任务都带这个标签);② 三台 qB 都配上下载完成回调。两条都做,整理不会漏。

六、目录:资源目录与媒体库目录

  「设定 → 存储 & 目录」页从上到下是三块:存储、目录、整理 & 刮削。自动分类策略的入口也在这一页里(后文详解)。

6.1 目录卡片的两组:资源存储与媒体库存储

  目录页里有两组卡片,含义完全不同:

  • 资源存储(下载目录) ——下载器把文件先放在这里。三个下载器的目录都要登记,且路径必须与下载器实际使用的目录一致。
  • 媒体库存储——整理后的成品目录,也就是 Emby 扫描的那个目录(云盘挂载出来的盘符)。

图 6 目录页的两组卡片。上面是资源存储(下载目录,分类全关),下面是媒体库存储(开启分类,整理方式选复制)。

下载目录为什么不分类
下载目录是「临时落脚点」,任务完成后文件会被复制到媒体库。这里建一堆子目录只会让保种路径变乱,也让「媒体库目录不能是资源目录的子目录」这条规则更难守。分类只在媒体库侧做。

跨机场景的两条硬规定
整理方式必须选「复制」 ——硬链接和移动只能在同一文件系统内生效,跨机 + 网盘目标都不满足,必然失败。复制模式下原文件留在下载机继续保种,副本进媒体库,这正是我们想要的。
媒体库目录不能是资源目录的子目录——比如资源设 D:\、媒体库设 D:\媒体库,会导致目录监控出错、自动整理失效。你的场景里媒体库在云盘盘符、资源在本地盘和共享,天然隔离,但以后加目录时要一直守住这条。

6.2 按类型分类 / 按类别分类:四种组合

  目录卡片上有两个开关,它们决定「自动建几级目录」:

  • 按类型分类——自动建一级目录(电影 / 电视剧 / 音乐)。
  • 按类别分类——自动建二级目录,目录名就是分类策略里的分类名称。

图 7 两个开关的四种组合,对应四种目录形态。最常见的用法是「两个都开」,让一级和二级目录全自动生成。

  还有一个字段值得单独说:固定分类。它和「按类别分类」不是一回事——固定分类是手工把整个目录钉死在某个分类上,不参与自动匹配;按类别分类是开启自动。两者填了会冲突,选一个用。

  目录卡片和分类规则一样按顺序匹配,第一个符合条件的生效。所以想把某一类单独拆成一级目录,就把那条目录卡片拖到最前面——具体做法在第十二章。

七、先认路:V3 的菜单和设定页

  所有分类相关配置都在设置里。打开 MoviePilot 后,左侧是导航栏,分成五组:

图 8 V3 主界面与「设置」页的十个分区。分类相关配置都在存储 & 目录里。

  V3 的设置页一共十个分区:系统、存储 & 目录、站点、规则、搜索 & 下载、订阅、服务、缓存、通知、关于。

  注意一个容易找错的地方:自动分类策略不在「规则」分区里,而在「存储 & 目录」分区。因为分类的最终产物是目录结构,V3 把它和目录配置放在了一起。

八、分类策略在哪:三个工作区

  点进 设置 → 存储 & 目录,页面由上到下是三块内容:存储、目录、整理与刮削。在「目录」这块里有一个 自动分类策略 的入口按钮。

图 9 「存储 & 目录」页。目录卡片可以拖动排序,右侧的自动分类策略按钮就是入口。

  点开「自动分类策略」,会出现一个独立面板,标题是 「媒体自动分类」 :

图 10 自动分类策略面板。顶部是版本号和未保存状态,下面三个工作区:分类树 / 规则 / 验证发布。

  这三个工作区是一条直线流程,按顺序走完就配好了:

  • 分类树——先定义"有哪些分类"。每个分类是一个目录,要起名字、定路径。
  • 规则——再定义"什么片子进哪个分类"。条件从上往下匹配,第一条命中的生效。
  • 验证发布——最后检查。先预览某部片子会分到哪,再估算影响范围,然后发布。

和 V2 最大的三个区别

  1. 分类有独立编号,改名不影响引用;
  2. 规则是可拖拽的条件树,不再是"分类名 + 一堆字段"的写法;
  3. 发布是可回退的版本,每次发布生成新版本,历史不会被覆盖。

九、第一步:在「分类树」里建分类

  「分类树」工作区里,电影、电视剧、音乐是三个独立的分类列表——音乐在 V3 里已经是和影视平级的独立媒体类型,不是附属品。

  每个分类要填四样东西:

字段 说明 注意
分类名称 给人看的名字,显示在界面里 可以随时改
分类编号 稳定 ID,创建后不能修改 规则、默认分类、目录设置、历史版本都靠它识别这个分类,所以改名安全、改编号会断链
分类路径 用 / 分隔层级,决定生成几级目录 最多支持的层数界面会写明(如「最多 3 级」);不能有空层级
媒体类型 电影 / 电视剧 / 音乐 被引用后不能再改
启用分类 停用后不参与匹配 被引用后不能停用,要先清理引用

图 11 分类树。每个分类卡片显示名称、状态、分类路径,以及它被谁引用(规则 / 目录 / 默认分类)。

分类路径怎么填,决定目录长什么样

  分类路径不是随便写的字符串,它是相对于媒体类型根目录的路径段。举个最直观的例子——你想让动画电影单独放一层:

`分类名称:动画电影
分类路径:动画 / 电影
媒体类型:电影

最终生成:Z:\媒体库\电影\动画\电影\你的片子 (2024)\`

  路径写 华语电影,生成的就是 电影\华语电影\;写 动画 / 电影,就多一层 动画\电影。这就是 V3 相对 V2 的一处升级:V2 的二级分类只能固定两级,V3 的路径段可以自己拼,最多到界面标明的层数上限。

三个会拦住你的保护机制
V3 对分类做了引用保护,被引用的分类不能乱动:
· 分类被规则引用 → 不能删除;
· 分类被设为默认分类 → 不能删除;
· 分类被目录配置引用 → 不能删除。
想停用、改媒体类型或删除,界面会提示「此分类正在被引用」,必须先清理引用。这是防止你一个手滑把整条整理链路搞断。

  还有一个从 V2 升级过来的兼容点:如果你的旧配置里分类是按路径字符串存的(V2 的写法),V3 迁移时会尝试按路径匹配到新分类。匹配不到或匹配到多个时,界面会提示「旧分类路径无法匹配当前策略,保存前请重新选择」或「匹配到多个分类,无法自动绑定」——这时手动选一次就行,别硬保存。

十、第二步:在「规则」里写匹配条件

  分类建好了,接下来是规则。规则决定"什么样的片子归到哪个分类"。

  每条规则由五部分组成:

部分 界面位置 说明
规则名称 规则卡片标题 给自己看的,比如「国漫优先」
规则类型 切换规则类型 分类:命中后归入某个分类;标签:命中后只打标签,不改变归属
媒体类型 媒体类型 这条规则只管电影 / 电视剧 / 音乐,可多选;不选就是全部媒体
数据来源 数据来源 限定这条规则读哪个数据源的信息;不选就是全部来源。多个来源是「任一命中」,系统不会把多个来源的信息拼在一起
匹配条件 条件区 条件树,支持「全部满足 / 任一满足」,可以嵌套
命中后执行 归入分类 分类规则选目标分类;标签规则填要输出的标签

图 12 规则工作区。卡片可以拖拽排序,序号就是匹配优先级。「其他动漫」这类兜底规则必须排在具体规则之后。

条件怎么选:字段 + 操作符 + 值

  点「添加条件」,出现的是一个三段式的条件行——字段 → 操作符 → 值。字段和操作符都是下拉选择,值按字段类型变成输入框、多值标签或日期。

图 13 条件构建器。国家、语言、风格这类字段可以直接搜名称选,系统自动存对应代码;「来源风格」这类没有固定字典的字段按原值填。

三个必须记住的匹配规则

  1. 从上到下,第一条命中即生效。 顺序就是优先级,用卡片上的「上移 / 下移」或直接拖拽调整。范围大的兜底规则一定要放在具体的规则后面——这是最容易出错的地方。
  2. 系统先看限定条件,再看媒体信息。 先检查规则的媒体类型和数据来源是否适用,然后再读这条媒体记录实际提供的信息。数据源没提供的字段,规则匹配不到(界面会提示"当前数据源不提供这项信息")。
  3. 多个来源不是"合并"。​一条规则里选了多个数据来源,表示​任意一个来源命中即可,系统不会把 A 来源的国家和 B 来源的风格拼起来判断。

V2 迁移过来的规则会带「兼容字段」标记
从旧配置迁移的规则,条件上会标着兼容字段,保留原来的匹配方式。它们能继续工作,但如果你在改规则,建议顺手按新字段重写一遍——新字段的值可以从下拉里搜名称选,比手填代码更不容易错。

十一、第三步:验证、预览、发布

  「验证发布」工作区里有三个子页签:结果预览、影响分析、发布与历史。这三个是 V3 相对 V2 最有价值的升级——改规则之前就能知道会有什么后果。

11.1 结果预览:这部片子会被分到哪

  输入关键词搜一部电影或一张专辑,选中它,系统直接用这条媒体信息跑一遍规则,告诉你结果和完整的匹配过程。

图 14 结果预览。左边是媒体信息,右边是结论,下方逐条列出每个条件是否命中、哪条规则先命中。

  预览里还能切换「使用哪套规则」:选当前编辑中的规则看草稿效果,选已发布的规则看线上现状——两边一对比就知道改动值不值。

11.2 影响分析:这次改动会波及多少已有记录

  这一步是 V3 独有的。系统会读取近期下载和整理记录,按记录里的数据源和编号重新拉取完整媒体信息,再用「当前版本」和「待发布版本」各跑一遍,把差异列出来。

图 15 影响分析。用数字告诉你「这次改动影响 12 条、174 条不变、14 条拿不到详情」,下方列出具体是哪些变了。

11.3 发布:三道门禁,都过了才能发

  发布不是点一下就走,V3 设了三道门禁:

图 16 发布与历史。四项前置条件逐条打勾,最后一步要手动确认「我已审阅最新影响分析」。

发布只保存分类配置,不移动文件
这是 V3 明确写的:发布只保存分类配置,不会移动文件。文件怎么走,是「目录」那块配置在整理时决定的。
也就是说,改分类策略不会立刻重排你现有的媒体库——它影响的是之后新整理的文件。想重排已有的,得走文件管理里的手动整理。

十二、回到目录:让分类真正生效

  分类策略配好只是"定义",真正让文件按分类落盘的,是目录卡片上的两个开关。回到 设置 → 存储 & 目录,看目录卡片:

图 17 目录卡片。分类策略配好后,这里的按类型分类 / 按类别分类才真正把分类变成目录层级。

  四种常见组合,对应四种目录形态:

按类型分类 按类别分类 生成结果
关 关 不建子目录,全部堆在你设的路径下
开 开 一级(电影 / 电视剧)+ 二级(分类名)都自动建
关 开 只建二级目录,一级要自己写进路径里
开 关 只按媒体类型分,不做分类

「固定分类」和「按类别分类」是两回事
固定分类是手工指定:这个目录专收某个分类的东西,不跑自动匹配。
按类别分类是开启自动:让规则跑起来,按结果建目录。
两个都填会冲突,选一个用。另外,目录卡片和分类一样按顺序匹配,第一个符合条件的生效——想把动漫单独拆一级目录,就把那条目录卡片拖到前面。

十三、一套可以直接抄的分类方案

  下面是按常见家庭媒体库整理习惯写的一套方案,覆盖电影和电视剧。照着建分类、照着重写规则即可。

13.1 分类表

媒体类型 分类名称 分类路径 说明
电影 动画电影 动画电影 风格含动画
华语电影 华语电影 语言为中文
外语电影 外语电影 兜底
纪录片 纪录片 可选
电视剧 国漫 国漫 动画 + 中国
日番 日番 动画 + 日本
欧美动漫 欧美动漫 动画 + 欧美
纪录片 纪录片 风格含纪录
综艺 综艺 风格含综艺
国产剧 国产剧 中国
日韩剧 日韩剧 日 / 韩 / 泰 等
欧美剧 欧美剧 兜底

13.2 规则表(按顺序建,顺序即优先级)

## 规则名 媒体类型 条件(全部满足) 归入分类
1 国漫 电视剧 统一风格 包含 动画 且 国家或地区 属于 中国、中国台湾、中国香港 国漫
2 日番 电视剧 统一风格 包含 动画 且 国家或地区 属于 日本 日番
3 欧美动漫 电视剧 统一风格 包含 动画 且 国家或地区 属于 美国、英国、法国、德国 欧美动漫
4 纪录片 电视剧 统一风格 包含 纪录 纪录片
5 综艺 电视剧 统一风格 包含 综艺 综艺
6 国产剧 电视剧 国家或地区 属于 中国、中国台湾、中国香港 国产剧
7 日韩剧 电视剧 国家或地区 属于 日本、韩国、泰国 日韩剧
8 动画电影 电影 统一风格 包含 动画 动画电影
9 华语电影 电影 原始语言 属于 zh、cn 华语电影

这张表的两个关键点
**第一,动画类规则必须排在国家/地区类规则前面。**​**如果「国产剧」写在「国漫」前面,那所有国产动画都会被国产剧先抢走——因为动画片的国家也是中国,第一条就命中了。​第二,最后一个分类不用写规则。**​ 「外语电影」「欧美剧」设为媒体类型的​默认分类即可,所有规则都没命中时自动归到那里。

13.3 推荐的发布节奏

  1. 先只建分类 + 默认分类,规则一条不写,发布第 1 版。此时所有片子都进默认分类,先确认目录结构对不对。
  2. 加 2~3 条最确定的规则(比如动画类),用「结果预览」逐条验证命中,发布第 2 版。
  3. 补齐其余规则,跑「影响分析」看会改动多少条已有记录,确认可接受再发布第 3 版。
  4. 之后每次调整都走「改草稿 → 预览 → 影响分析 → 发布」,出问题就用版本历史回退。

十四、字段与操作符速查

14.1 常用字段

字段 适用 说明
媒体类型 全部 电影 / 电视剧 / 音乐
标题 全部 标准标题
年份 影视 支持范围比较(大于 / 介于)
语言 影视 原始语言,如 zh、ja、en
国家或地区 影视 中国、日本、美国……可直接搜名称选
统一风格 影视 系统规范化后的风格,推荐优先用它
风格 影视 数据源原始风格名,可能不统一
内容分级 影视 如 PG-13、R
时长 影视 分钟,可做范围判断
出品公司 / 电视台·平台 影视 可用于识别平台自制剧
音乐类型 / 专辑类型 音乐 专辑、单曲等
音乐流派 / 音乐标签 音乐 标准化流派与数据源标签
艺术家 / 艺术家国家·地区 音乐 可用于华语 / 欧美音乐分家
数据源补充信息 全部 插件扩展字段,按数据源命名空间隔离

14.2 操作符

类别 操作符
相等判断 等于、不等于
集合判断 属于、不属于
文本匹配 包含、包含任一、包含全部、不包含任一
数值 / 年份比较 大于、大于等于、小于、小于等于、介于
布尔与存在性 为真、为假、存在、不存在

选字段时的一个技巧
条件构建器里会判断字段是否同时适用于规则当前选择的全部媒体类型。如果某条规则同时管电影和电视剧,就不要用只在剧集上有的字段——拆成两条规则更清楚。
另外,「统一风格」是系统规范化过的值,「风格」是数据源原值。做分类判断优先用「统一风格」,能少踩一堆数据源差异的坑。

十五、站点:CookieCloud 同步与下载器绑定

  站点配置分两步:先把浏览器的登录状态同步进来,再逐站做设置。CookieCloud 是官方支持的方式,省去手工复制 Cookie。

  1. 浏览器装 CookieCloud 扩展,把 8 个站点都登录一遍,同步一次。
  2. MoviePilot 里:设定 → 站点 → CookieCloud,勾选「启用本地 CookieCloud 服务器」,填入用户 KEY 与端对端加密密码。
  3. 捷径 → 服务 → 同步 CookieCloud 站点 → 执行,跑一次。
  4. 回到站点管理,确认 8 个站都已就位。

图 18 站点管理。每个站点编辑里都有「此站点使用的下载器」字段,这就是三下载器分流的落点。

15.1 逐站关键字段

字段 建议值 说明
此站点使用的下载器 按分配表指定一台 三下载器分流的落点。不指定就全落到默认下载器
站点地址 站点首页 URL 格式 https://xxx.org/,末尾斜杠别漏
优先级 越小越优先 多个站点都有同一资源时的择优顺序
超时时间 留空(0 = 不限制) 网络差的站可以放宽
使用代理访问 全部关闭 PT 流量过代理会断种,也可能被站点判定异常
限制站点访问频率 建议开 降低被风控的概率
浏览器仿真 默认关 遇到 Cloudflare 类验证才开

15.2 三个下载器怎么分配

下载器 适合承接 理由
01 号(主控机) 需要与 MoviePilot 强联动的站:自动订阅、刷流 同机,链路最短
02 号(下载机 A) 保种要求高、任务量小的站 低功耗小主机适合长期挂种
03 号(下载机 B) 大体积、多并发的站 把 IO 与带宽压力从主控机拆走

一条铁律
同一个站点的任务不要分散到多台下载器——上传统计会被摊薄,冲榜和保种数据都吃亏。一个站只认一台下载器。

十六、规则与词表

16.1 优先级规则

  订阅、搜索、洗版各有一套规则组,用来从多个候选资源里挑出最该下的那个。五条要点:

  1. 不设置 = 不启用过滤。
  2. 按顺序匹配,匹配通过的第一条即优先级;全不匹配的资源会被过滤掉。
  3. 优先级数字越小越优先。
  4. 同一条内各规则项是与关系;同类型规则项不能同时选。
  5. 要全局排除某项,每条规则里都得排除它。

  官方示例(优先特效字幕与中文字幕,排除蓝光原盘和杜比,只要 4K / 1080P,1080P 优先):

`SPECSUB & !BLU & !DOLBY & 1080P
  > CNSUB & !BLU & !DOLBY & 1080P
  > SPECSUB & BLU & !DOLBY & 4K
  > CNSUB & !BLU & !DOLBY & 4K`

  规则支持「分享」导出和「导入」——可以直接吃进别人调好的规则组,省去从零试错。

16.2 词表:解决识别不准

  词表在「捷径 → 词表」里维护,四种写法:

写法 作用
屏蔽词 直接过滤掉命中这个词的资源
被替换词 => 替换词 把识别错的标题片段替换成正确的
前定位词 <> 后定位词 >> EP+1 从标题里截取季集号,并做偏移修正
{[tmdbid=xxx;type=movie;s=1;e=2]} 替换词直接指定媒体 ID,强制指向某条记录

  最后一种写法也支持 doubanid / bangumiid / anilistid。遇到「怎么都识别不对」的冷门片,直接钉 ID 是最省事的办法。

十七、媒体服务器与通知

17.1 接入 Emby

  媒体服务器在 设定 → 媒体服务器 里添加,填入 Emby 的地址和 API Key,打开同步媒体库。整理完成后 MoviePilot 会通知 Emby 刷新,新片立刻可见。

图 19 媒体服务器与通知。Emby 负责播放,飞书负责把「下载完成 / 整理失败 / 认证失效」这些事件推到你手机上。

17.2 飞书通知

  V3 官方已支持飞书渠道,字段是 App ID / App Secret / 默认用户 Open ID / 默认群聊 Chat ID / 管理员白名单 / Verification Token / Encrypt Key。Open ID 和 Chat ID 二选一即可;管理员白名单用于允许哪些人通过飞书执行命令。

  建议开启这几类事件:下载开始、下载完成、整理入库失败、订阅更新、认证失效。后两类尤其重要——认证失效不通知,你会发现订阅悄悄停了。

关于回调地址
多配置时可以在末尾加 &source=配置名称 区分。消息接收类回调用 /api/v1/message/?token=<API_TOKEN>。

十八、重命名格式

  电影、电视剧、音乐三种类型各有一套重命名格式,用 Jinja2 语法写,/ 表示目录层级。官方默认输出长这样:

`电影:星际穿越 (2014)/星际穿越 (2014)-1 - 4K.mkv
剧集:狂飙 (2023)/Season 1/狂飙 - S01E05-1 - 第 5 集.mkv
音乐:艺术家/专辑 (年份)/01 - 曲名.flac`

  信息更全、层级更短的推荐写法:

`# 电影
{{title}}{% if year %} ({{year}}){% endif %}/{{title}}{% if year %} ({{year}}){% endif %}{% if videoFormat %} - {{videoFormat}}{% endif %}{% if videoCodec %} {{videoCodec}}{% endif %}{{fileExt}}

# 电视剧
{{title}}{% if year %} ({{year}}){% endif %}/Season {{season}}/{{title}} - {{season_episode}}{% if episode_title %} - {{episode_title}}{% endif %}{{fileExt}}`
  • 用变量前先 {% if %} 判空,否则会出现「片名 ( ) - .mkv」这种残缺文件名。
  • 音乐优先读音频内嵌标签,不依赖影视命名规范;同目录同名的歌词文件(.lrc / .txt / .lyricsfile.yaml)会一起搬走。

十九、插件与自启动

19.1 插件怎么选

插件 建议 说明
二级分类策略 装 在界面里维护分类策略(V3 已内置自动分类编辑器,此插件用于扩展场景)
自动删种 装 按分享率 / 时间自动清理,避免下载盘撑爆
站点数据刷新 装 保持站点上传下载数据准确
站点签到 看站点 需要签到的站才装
共享识别词 看片源 冷门片识别不准时有用
刷流 按需 冲魔力值 / 上传量时开
目录监控 不装 靠文件系统事件,对网络共享路径不可靠;用「下载器监控 + 下载完成回调」代替

19.2 自启动:让它在重启后自己回来

  • 用任务计划程序或 NSSM 把 MoviePilot 注册成开机自启(勾选「不管用户是否登录都运行」「使用最高权限」,并设置失败后自动重启)。
  • 给 MoviePilot 加 1 分钟延迟启动——等云盘挂载先就绪,否则首次扫描读不到媒体库目录。
  • 系统更新改为手动确认,避免半夜自动重启杀掉保种。
  • 配置自动登录,避免重启后卡在登录界面。
  • 电源策略设为永不睡眠;BIOS 里把断电恢复设为自动开机。

二十、避坑清单

## 坑 后果 / 正确做法
1 跨机下载器没填路径映射 任务存错位置或直接失败;必须填「主控机视角 ↔ 下载机本机」的对应关系
2 整理方式选了硬链接或移动 跨机 + 网盘目标都不支持,必然失败;必须选「复制」
3 媒体库目录是资源目录的子目录 目录监控出错、自动整理失效
4 把 V2 的环境变量照抄进 V3 界面与配置两边不一致,排查极难
5 凭据管理器没存下载机的共享凭据 路径映射对了仍报「文件找不到」
6 忘了配下载完成回调 整理要等轮询,多下载器场景可能漏整理
7 站点开了「使用代理访问」 断种,或被站点判定异常
8 站点没指定「此站点使用的下载器」 任务全落到默认下载器,分流失效
9 同一个站点的任务分到多台下载器 上传统计被摊薄,冲榜吃亏
10 兜底分类规则放在具体规则前面 具体规则永远不生效;范围大的规则排最后
11 动画类规则排在国家/地区类规则后面 国产动画会被「国产剧」先抢走;动画规则要往前放
12 删掉被规则/目录/默认分类引用的分类 界面会拦住;强行处理会断链,先清理引用再删
13 改了分类草稿不发布 界面一直显示「有未保存修改」,实际没生效
14 以为发布分类就会重排媒体库 发布只保存配置,老文件纹丝不动;重排走手动整理
15 同时开「固定分类」和「按类别分类」 规则冲突,行为不可预期;二选一
16 目录卡片顺序不对 细化的目录被通用目录抢走;需要细化的拖到最前
17 一条规则选多个数据源以为能互补 实际是「任一命中」,不会合并信息
18 媒体信息不完整导致规则匹配不到 片子掉进默认分类;打开「补充缺少的信息」或放宽条件
19 Emby 开着媒体库实时监控 云盘整库遍历,风控概率上升;交给伴侣插件定向刷新
20 MoviePilot 比云盘挂载先启动 首次扫描读不到媒体库目录;加延迟启动

二十一、验收清单

  全部配置完成后,按这个顺序跑一遍,能自己判断有没有配对。

基础链路

  • MoviePilot 能登录,管理员密码与 API Key 已妥善记录。
  • 用户认证完成,搜索和下载按钮不再是灰的。
  • 三个下载器名称前都有小绿点,默认下载器是主控机上那台。
  • 跨机的两个下载器路径映射已填,且下载机侧路径与文件管理器里看到的一致。
  • 三台下载器都配了下载完成回调。
  • 目录卡片顺序正确,媒体库卡片开启了分类、整理方式为复制。
  • 站点齐全,每站已绑定下载器,且全部关闭「使用代理访问」。
  • 媒体服务器已接入;通知测试能收到消息。

分类策略

  • 分类树里三个媒体类型的分类都已建好,路径符合预期。
  • 每个媒体类型的默认分类都已设置。
  • 规则顺序正确——兜底规则在最后,用「结果预览」抽查过 3 部以上不同类型的片子。
  • 预览结果里的「规则匹配说明」逐条都是条件命中,没有意外未命中。
  • 影响分析跑过,变化条数在可接受范围,「无法获取详情」的条数心里有数。
  • 发布成功,顶部版本号 +1,版本历史里能看到刚才那一版。

端到端

  • 搜一部片子 → 下载 → 任务出现在指定的那台下载器里。
  • 下载完成 → 自动整理 → 文件进媒体库的对应分类目录。
  • 媒体服务器能看到新片,刮削的海报和简介齐全。
  • 重启主控机后,云盘挂载 → MoviePilot → 媒体服务器能自动恢复。

写在最后

  V3 这次最大的变化,是把「配置」这件事从文件搬回了界面,并且给分类策略配了一整套定义(分类树)、逻辑(规则)、验证(预览与影响分析)、回滚(版本历史) 的闭环。

  真正值得花时间的是那一步「结果预览」——它把以前只能靠猜的匹配逻辑摊开给你看,逐条告诉你哪个条件命中了、哪条规则先匹配上。配置一次,以后维护起来心里有底。

  而跨机三下载器这套结构,难点其实只有三个:路径映射、整理方式选复制、下载完成回调。这三处配对,剩下的都是水到渠成。

  本文界面结构与字段名取自 MoviePilot V3 前端源码与官方 Wiki,界面配图为按真实结构还原的示意图(非官方截图),配色为示意。软件行为以你实际使用的版本为准。

上一篇 家庭影音与AI助理部署全记录-博客版
下一篇 沙丘2