使用

本页介绍 PosterPilot 在 安装 和 配置 完成后的日常工作流程。

首次安装向导

在全新安装时，一个横幅会指向位于 /setup 的向导。它会按顺序 带你完成六个步骤，并随着你的操作逐步持久化每一步：

1. 语言 — 选择界面区域设置。
2. 媒体服务器 — 选择 Plex、Jellyfin 或 Emby。对于 Plex，你可以用 PIN 登录（PosterPilot 会显示一个代码和一个授权链接，然后为你存储 获取到的 token），并选择一个发现到的 local/remote 连接；Jellyfin 和 Emby 则使用服务器 URL，并让你 用用户名和密码登录——PosterPilot 会用它们换取一个访问令牌，这样你就永远不必去翻找 API 密钥（密码 仅用于那一次请求，绝不会被存储；手动粘贴密钥仍可作为后备方式）。 Test 按钮会验证连接。
3. TMDB — 粘贴一个 TMDB API 密钥（页面提供了指向 TMDB API 设置的链接）。
4. 提供方 — 切换封面提供方（MediUX、TMDB、Fanart.tv、 ThePosterDB），如果你使用 Fanart.tv，则输入它的密钥。
5. 媒体库 — 连接成功后，向导会列出你的电影和剧集媒体库； 勾选要同步的那些（默认全选，这也会自动纳入你之后添加的媒体库）。
6. 首次同步 — 运行初始同步，然后跳转到仪表板。

该向导在任何环节都 可跳过（跳过 链接会直接进入 仪表板）——它覆盖的所有内容也都可以在 设置 中找到。

同步媒体库

同步会将你的电影和剧集媒体库从活动媒体服务器拉取到 PosterPilot 的本地缓存中，并将每个标题解析为 TMDB id，以便可以查询封面 提供方。

1. 确保活动服务器类型的凭据和一个 TMDB 密钥都已配置。 如果未配置，同步会被阻止（并带有关于缺失内容的明确提示）。
2. 可选地从 要同步的媒体库 清单（在向导或设置 → 媒体服务器中） 或用 INCLUDED_SECTIONS 缩小要同步的分区范围——将其留空可 同步所有电影和剧集分区，包括你之后添加的那些。
3. 从 仪表板 运行同步（同步 按钮）。它作为后台任务运行， 实时进度就显示在那里；统计卡片（条目、电影、剧集、已解析、 含 MediUX、已应用）会随着运行而增长。

每个条目返回时都带有其标题、年份、类型、外部 GUID（存在时包含 tmdb/imdb/tvdb）， 以及当前海报。没有外部 GUID 的条目仍会被列出， 但会被标记为无法用于提供方查找，而不是被丢弃。

重复同步默认是 增量 的：PosterPilot 会将每个条目与媒体服务器的 最后修改时间戳进行比对，只重新解析和重新丰富自上次同步以来发生变更的 那些条目，因此例行重扫会比首次快得多。重新处理所有内容的 完整重扫 仍然可用，你也可以完全关闭增量同步（参见 配置 → 性能与调优）。

库墙

已同步的媒体库以海报网格形式呈现，并带有一个 Notion 风格的工具栏。你可以：

• 按标题 搜索。
• 从 筛选 弹出框中 筛选：媒体类型（电影 / 剧集）、最低评分、 类型、缺少海报、MediUX 可用性（有候选项）、变更状态 （未变更 / 仍在使用默认海报），以及忽略状态。筛选按钮上会显示一个徽章， 标注活动分面的数量。
• 从 排序 弹出框中按标题、发行年份、评分、时长、最近变更， 或添加到媒体服务器的日期进行 排序，并带有一个独立的升序/降序切换。 库墙打开时使用在 设置 → Kometa 与高级 中配置的排序（默认：标题）； 工具栏中的显式选择始终优先。
• 每个活动筛选项和排序都会作为 可移除的标签芯片 显示在工具栏下方—— 点击某个芯片的 ✕ 只移除那一个，或点击 全部清除 重置所有内容。
• 切换 自动应用（⚡ 按钮）：开启时，每次变更都会立即跳转；关闭时， 变更会被暂存，直到你点击 应用。该选择会被记住。
• 忽略 一个你希望保持不动的条目——被忽略的条目会被发现、应用和 自动选择跳过，会在库墙上以视觉方式标记，并可在筛选弹出框中筛入或 筛出。随时再次切换关闭它，即可让该条目重新回到工作流程中。
• 查看 聚光横幅——一旦至少应用了一个封面， 库墙上方会显示某个最近变更条目的背景图。

每个图块会显示该条目的评分和一个状态徽章（例如 MediUX 可用、 已变更），标题和年份则在悬停时显示。

查找封面

打开一个条目即可查看其详情视图：带有条目徽标（或在 没有徽标时显示其标题）的背景主视觉、评分、年份、时长（对于 剧集则显示季/集数量）、类型和概述，以及主要演职人员。

• 如果尚未发现封面，使用 查找封面 为 该条目运行发现。
• 发现会跨所有启用的提供方发散查找，并存储它们候选项的并集， 每个候选项都带有其提供方标记。
• 候选项 首先按提供方，然后按套图 分组。每个套图会显示其 上传者署名，并将海报和背景放在一起。对于剧集，该视图 还会呈现季海报套图和标题卡套图。
• 提供方分区、单个套图卡片，以及（对于剧集）季分组都是 可折叠 的。 首次加载时，第一个提供方及其第一个套图会展开，其余一切都会折叠； 你的折叠/展开选择会在浏览器中持久保存，跨重新加载以及在条目之间 切换时都保持不变。
• 当启用 建议封面 时，每个槽位中得分最高的候选项会被预选为一个 清晰标记的建议，你可以接受或覆盖它。候选项会根据提供方质量、分辨率 和宽高比贴合度进行评分；可在设置中调整权重——或关闭预选（参见 配置 → 性能与调优）。

你可以暂存整个套图（“使用此套图”），或从一个套图中取用单张海报、 从另一个套图中取用背景——这两个槽位是相互独立的。

季与集封面

对于剧集，封面是按槽位暂存的，因此剧集封面、每一季的海报， 以及每一集的标题卡都是彼此独立的：

• 一个套图的封面会被组织为一个 剧集分组（海报和背景），以及 每季一个分组。每个季分组容纳该季的海报及其各集的标题卡。 （模型中存在一个季背景槽位，但不会显示，因为目前没有提供方 提供季背景。）
• 在某个季或集槽位内选择一个候选项，只会暂存那一个槽位，而不会 触及剧集级别或任何其他槽位。再次选择某个槽位中已暂存的候选项 会再次将其清除。
• 使用此套图 会一次性填充该套图覆盖的每一个槽位——剧集、每一季 和每一集——按季号和集号匹配。随后你可以覆盖任意单个槽位，并让 套图的其余部分保持暂存。

固定的构建器会汇总当前暂存的所有内容——剧集海报/背景，再加上已暂存 的季数和集数统计——而单次 应用 会在一次操作中写入所有这些内容 （参见 应用封面）。

应用封面

使用你选择的方法应用已暂存的选择，每次应用操作都可单独选择方法， 并带有可配置的默认值（DEFAULT_APPLY_METHOD，默认为 both）：

• 媒体服务器（直接）。 通过活动媒体服务器提供方上传海报 （和背景），并锁定该字段，使服务器的自动 代理不会覆盖它。变更几乎是即时的。会被记录为 一次带有提供方类型的服务器应用。
• Kometa 导出。 将 Kometa/PMM 兼容的 YAML——url_poster（以及 在暂存了背景时的 url_background），以 TMDB id 为键——写入 配置的 Kometa 资产目录，而不联系媒体服务器。你 现有的 Kometa 实例会在下次运行时应用这些封面。重新应用会就地 更新条目，而不是重复它。
• 两者。 同时执行直接上传 和 写入 Kometa YAML，并独立记录每个 结果，以便部分失败时可见。

单次应用会用所选方法写入 每一个已暂存的槽位——剧集、各季和各集。 对于直接上传，PosterPilot 会按编号在媒体服务器上解析每一季和每一集的 子项并向其上传；某个已暂存槽位的季或集在服务器上没有匹配的子项时， 会被跳过并报告，而不会使整个应用失败，且某一个子项的失败绝不会中止 其余部分。Kometa 导出会将已暂存的季海报嵌套在 seasons: 下（以季号 为键），将已暂存的集标题卡嵌套在 episodes: 下（以集号为键），与 剧集级别的 url_poster / url_background 并列。季 背景 仅通过 直接方法应用——它会从 YAML 中被省略。

每次应用——无论成功或失败——都会连同条目、资产 URL、 方法、结果和时间戳一起记录，因此历史可查询，并且重新应用 可被检测到。

Kometa 如何使用导出

PosterPilot 会将单个元数据文件（默认 posterpilot.yml）写入 KOMETA_ASSETS_DIR，以 TMDB id 为键，带有 url_poster / url_background 条目。将该文件添加到你的 Kometa 库配置中（例如在 metadata_path / metadata_files 下），以便 Kometa 在下次运行时应用这些封面。

还原

每一个已应用的封面都可以从条目详情视图中还原：

• 还原为原始 会在一次操作中还原剧集级别的封面 以及每一个已应用的季 和集，恢复 PosterPilot 更改之前媒体服务器所拥有的内容。
• 每个季分组都有自己的 还原此季 控件，只还原该季的海报/背景及其各集的 标题卡，而保留剧集级别和其他季的封面不变。

还原会像应用一样按编号重新解析季和集的子项。

自定义套图

条目详情视图有一个持久、固定的 构建器，带有一个海报槽位和一个 背景槽位，二者共同组成一个自定义”套图”：

• 点击海报候选项会将其路由到海报槽位；点击背景 候选项会将其路由到背景槽位——自动按类型路由。
• 每个槽位也可以通过 粘贴的图像 URL 或 上传的图像 文件 填充。
• 应用构建器会通过你选择的方法在一次操作中应用两个已暂存的部分。

上传仅限服务器

基于 URL 的自定义封面可以同时通过媒体服务器和 Kometa 应用。 上传的文件 只能通过媒体服务器应用——二进制上传 无法表示为 Kometa YAML URL，因此它会从 Kometa 导出中被省略， 并且该限制会被明确显示，而不是写入一个无效条目。

批量操作

选择多个条目，并将发现和/或应用作为单个后台任务跨整个选择运行。 带自动选择的批量应用会（在需要时）进行发现、 自动选择，并为每个选中的条目应用封面，并带有实时进度。

自动选择会跨所有启用的提供方为每个候选项评分——综合提供方质量、 分辨率和宽高比贴合度——并为每个条目挑选得分最高的海报（以及在可用时 的背景），与条目视图上驱动建议预选的评分相同。被忽略的条目会被排除在 选择之外。

在批量应用运行之前，一次 演练预览 会准确地汇总将会发生的事情—— 计划中的上传、Kometa 导出，以及任何将被跳过的条目或槽位——以便你在写入 任何内容之前进行确认。随后，批量应用会 并发 处理各个条目（受应用并发 设置约束），因此大批量会更快完成，并带有同样的实时进度和取消。

FUN：随机电影/剧集抽选器

FUN 是一个可自愿启用的媒体库实验板块（用 设置 → Kometa 与高级 中的 FUN 开关，或 FUN_ENABLED=true 启用它）。在此之前它完全保持 隐藏——没有导航入口，其页面会返回 404。

它的第一个工具回答”今晚我们看什么？“：一次点击即可从你已同步的媒体库 中随机抽取一个标题，并以图像为先的方式呈现——背景图、海报、类型、评分 和概述——附带一个指向该条目的链接，以及一个在相同筛选条件下再次抽取的 再抽一次 按钮。你可以通过以下方式约束抽取：

• 媒体类型 — 电影、剧集或两者。
• 类型 — 你媒体库中的某一个类型，或全部。
• 年份范围 — 可选的最低和/或最高发行年份。
• 已观看 — 跳过你已经看过的标题。观看状态会在媒体库同步期间捕获 （Plex 的播放次数；Jellyfin/Emby 的已播放标志——一部剧集只有在每一集 都已播放时才算已观看）。

注意

在 Jellyfin/Emby 上，已播放标志需要用户上下文，因此请用用户名/密码登录， 而不是仅使用 API 密钥——只有 API 密钥时，所有内容都会被同步为未观看， 跳过已观看的筛选器将没有任何可排除的内容。

仪表板与任务

仪表板 是大本营。它会显示库统计卡片、同步 按钮，以及 任何正在运行的任务，并带有一个可 取消 的 实时进度条 （通过 Server-Sent Events 更新，无需刷新）。仪表板旁边的导航徽章 会反映当前有多少个活动任务。下方有一个 近期任务 表格， 列出最新的任务及其类型、已处理/总数，以及最终状态。 没有单独的任务页面——实时进度和近期历史都位于仪表板上。

活动日志

细粒度的事件日志位于 设置 → 活动。每一个操作事件都会记录在 那里（并镜像到容器控制台和一个滚动的文件日志）。你可以：

• 按级别筛选——全部 / 信息 / 警告 / 错误。
• 用 加载更多 翻阅历史。
• 清除活动 以清空应用内的表（这不会删除磁盘上的日志文件）。

该表的行数上限为 EVENT_RETENTION（默认 2000）；更早的行会被 自动修剪。关于文件日志和保留细节，参见 配置 → 日志与活动日志。