moviepilot过滤规则格式不生效？

Question

在使用MoviePilot时，部分用户反馈自定义过滤规则（如排除特定分辨率或来源站点）未生效，导致下载内容仍包含应被过滤的条目。常见原因包括：规则语法格式错误（如未使用正确的正则表达式或字段命名不规范）、过滤条件未启用、或规则优先级设置不当。此外，MoviePilot版本更新可能导致原有规则格式不再兼容，而用户未及时调整。建议检查配置文件中`filter`字段是否符合官方文档示例，确认关键词、排除项书写无误，并在日志中查看规则匹配过程，以定位具体失效环节。

Answer 1

MoviePilot 自定义过滤规则失效问题深度解析

1. 问题现象与背景分析

在使用 MoviePilot 进行自动化媒体资源抓取时，部分用户反馈其配置的自定义过滤规则未能按预期生效。典型表现为：尽管设置了排除特定分辨率（如 480p）或屏蔽某些来源站点（如 PTChina、HDHome），系统仍会将这些本应被过滤的条目纳入下载队列。

此类问题不仅影响用户体验，还可能导致存储资源浪费和后续整理成本上升。从技术角度看，该问题通常涉及配置语法、执行逻辑与系统兼容性等多层因素。

2. 常见原因分类与排查路径

• 规则语法格式错误：未遵循正则表达式规范或字段命名不一致（如误用resolution而非video_resolution）
• 过滤条件未启用：规则虽存在但未在主配置中激活，或作用域设置错误
• 优先级冲突：多个过滤器之间存在覆盖关系，高优先级规则未正确排序
• 版本兼容性问题：MoviePilot 升级后，旧版filter结构不再支持
• 日志追踪缺失：缺乏对匹配过程的日志输出，难以定位失败环节

3. 配置文件结构与语法规则详解

MoviePilot 的过滤规则主要定义于配置文件中的 filter 字段。以下为标准格式示例：

filters:
  exclude:
    - name: "Block 480p"
      type: "regex"
      field: "video_resolution"
      value: "480p"
      enabled: true
    - name: "Exclude HDHome"
      type: "string"
      field: "site"
      value: "HDHome"
      enabled: true
priority: [ "Block 480p", "Exclude HDHome" ]
    

关键点包括：field 必须与数据模型字段完全匹配，enabled 显式开启，且 priority 数组决定执行顺序。

4. 分析流程图：过滤规则匹配机制

graph TD
            A[开始匹配资源] --> B{是否有启用的过滤器?}
            B -->|否| C[直接加入候选列表]
            B -->|是| D[按priority顺序遍历规则]
            D --> E[获取当前规则条件]
            E --> F{字段值是否匹配?}
            F -->|是| G[排除该资源]
            F -->|否| H[继续下一规则]
            H --> I{所有规则处理完毕?}
            I -->|否| D
            I -->|是| J[保留资源进入下载队列]

5. 实际案例与调试方法

场景	配置错误	正确写法	日志提示
排除480p视频	field: resolution	field: video_resolution	"No match for field 'resolution'"
屏蔽某站点	value: hdhome（大小写敏感）	value: HDHome	"Site name mismatch: got 'HDHome', expected 'hdhome'"
正则排除多站点	type: string	type: regex, value: "(PTChina|OurBits)"	"String matcher cannot evaluate pattern"
规则未生效	enabled: false	enabled: true	"Filter 'Block 480p' is disabled, skipping"
优先级错乱	priority 缺失	显式声明 priority 数组	"Using default rule order"

6. 版本演进带来的兼容性挑战

随着 MoviePilot v2.3+ 引入新的元数据模型，原有基于 title 字段进行模糊匹配的方式已被弃用。新版本要求使用结构化解析字段，例如：

• 旧：field: title, value: ".*480p.*", type: regex
• 新：field: video_resolution, value: "480p", type: string

升级后若未同步调整规则，系统将无法识别旧格式，导致“看似配置正确却无效”的假象。

7. 日志分析与诊断建议

启用 debug 模式后，可通过日志观察每条规则的匹配过程。关键日志片段示例如下：

[DEBUG] Applying filter 'Block 480p' on item 'The.Matrix.1999.480p.BluRay'
[DEBUG] Field 'video_resolution' = '480p', matches value '480p' → EXCLUDED
[DEBUG] Filter 'Exclude HDHome' applied to site 'HDHome' → MATCHED, resource dropped
    

若未见相关日志输出，则说明规则未被加载或处于禁用状态。

8. 最佳实践与自动化检测方案

1. 定期审查 config.yaml 中的 filter 配置项
2. 使用 CI 脚本校验 YAML 格式与字段合法性
3. 建立规则测试集，模拟不同资源输入验证排除效果
4. 在部署前通过命令行工具执行 dry-run 测试
5. 结合 Prometheus + Grafana 监控过滤命中率
6. 为关键规则添加注释说明适用范围与维护人
7. 利用 Git 管理配置变更历史，便于回滚与审计
8. 开发插件式规则引擎接口，提升可扩展性