MoviePilot如何自定义添加探索标签？

Question

在使用 MoviePilot 过程中，用户常遇到“如何自定义添加探索标签”的问题。默认的探索页面标签如“热门”、“最新”等较为固定，难以满足个性化内容分类需求。许多用户希望根据自己的媒体库结构（如按地区、语言、家庭观影等）添加自定义标签，但系统未提供图形化操作入口。技术难点在于需手动修改配置文件或数据库，涉及 YAML 编辑或 SQLite 操作，存在配置错误导致服务无法启动的风险。此外，自定义标签需关联对应的筛选规则（如分类、元数据字段），对新手不够友好。如何安全、正确地实现探索页面的标签扩展，成为进阶用户关注的核心问题。

Answer 1

1. 探索标签的默认机制与扩展需求

MoviePilot 的探索页面通过预设标签（如“热门”、“最新”、“推荐”）组织媒体内容，底层依赖于元数据服务和分类规则引擎。这些标签通常由系统内置的 explore.yml 配置文件驱动，其结构为 YAML 格式，定义了每个标签的名称、排序方式、筛选条件等参数。由于缺乏图形化配置界面，用户无法直接在 Web UI 中添加或修改标签，必须深入系统配置层进行干预。

标签名	筛选字段	排序方式	数据源
热门	vote_count	desc	TMDb
最新	release_date	desc	本地元数据
推荐	score	desc	AI评分模型

2. 自定义标签的技术路径分析

实现自定义探索标签的核心在于理解 MoviePilot 的配置加载机制。系统启动时会读取 /config/explore.yml 文件（若不存在则使用内置默认值），并将其解析为前端可渲染的标签列表。因此，用户可通过编辑该文件实现标签扩展。然而，YAML 对缩进和语法极为敏感，错误的格式可能导致服务启动失败。

1. 确认配置目录挂载路径（Docker 环境下需检查 volume 映射）
2. 备份原始 explore.yml 文件
3. 启用 YAML 语法高亮编辑器（如 VS Code + YAML 插件）
4. 遵循 schema 定义新增标签节点
5. 验证 YAML 合法性（使用 yamllint 工具）
6. 重启服务并观察日志输出

3. 配置文件修改示例：按地区分类

以下代码展示了如何添加一个名为“华语电影”的自定义标签，筛选条件为原产国包含 CN 或 HK 的影片：

-
  name: 华语电影
  type: movie
  sort_method: release_date
  sort_order: desc
  filters:
    - field: "production_countries"
      value: ["CN", "HK"]
      method: contains_any
-
  name: 家庭观影
  type: movie
  sort_method: vote_average
  sort_order: desc
  filters:
    - field: "genres"
      value: ["Family", "Animation"]
      method: contains_all

4. 数据库层面的高级控制（SQLite）

对于更复杂的筛选逻辑（如基于播放记录或用户评分），可直接操作 moviepilot.db 中的 EXPLORE_TAGS 表。但此方法风险较高，建议仅在熟悉 SQLite 结构的前提下使用。

INSERT INTO EXPLORE_TAGS 
(name, type, filter_json, sort_field, sort_desc) 
VALUES (
  '外语学习',
  'tv',
  '{"original_language": ["fr", "de", "es"]}',
  'title',
  0
);

5. 安全性与调试策略

为降低配置错误带来的系统风险，建议采用分阶段验证流程：

graph TD A[创建explore.yml.bak] --> B[编辑新标签] B --> C[使用yamllint校验] C --> D[停止容器] D --> E[替换配置文件] E --> F[启动服务] F --> G{日志是否报错?} G -- 是 --> H[恢复备份并排查] G -- 否 --> I[访问探索页验证]

6. 元数据字段的可筛选性分析

并非所有元数据字段都支持作为筛选条件。以下是常用可过滤字段及其数据类型：

字段名	数据类型	多值支持	来源	示例值
genres	list	是	TMDb	Action, Drama
original_language	string	否	TMDb	en, ja
production_countries	list	是	TMDb	US, JP
vote_average	float	否	TMDb	7.8
release_year	int	否	解析器	2023
media_path	string	否	本地	/Movies/Anime/
edition	string	否	解析器	4K.UHD
studio	list	是	TMDb	Disney, Pixar
tmdb_id	int	否	TMDb	12345
imdb_id	string	否	IMDb	tt1234567