使用

这是完成安装和配置后的日常流程。

设置与首次同步

/setup 依次处理语言、服务器、TMDB、提供方、媒体库和首次同步。Plex 支持 PIN／连接发现；Jellyfin／Emby 支持用户名密码或密钥。每一步只有服务器接受后才前进。跳过会离开向导；首次同步会跟踪到终态，失败时显示详情和重试。

同步与完整重新扫描

仪表板的同步从当前命名服务器导入电影／剧集，解析 TMDB 并更新元数据。INCLUDED_SECTIONS 或媒体库列表限制范围。没有 GUID 的项目仍会显示为未解析。

普通同步默认增量，只重新解析自上次同步以来变化过的项目。有一类项目刻意不受这个跳过约束：存储的 TMDB 身份与媒体服务器自身的电影／剧集类型相矛盾的项目每次都会重新处理，因此陈旧的错配不可能永远躲过增量同步（参阅修正 TMDB 匹配）。完整重新扫描重新读取全部项目、核对已删除项目并发现外部海报变化，但不会删除快照／修订，也不会自动应用海报。

任务会实时显示排队、阶段、进度、尝试和结果。刷新页面不会取消；等价请求会复用活动任务。

大型媒体库操作

媒体库在服务器端按类型、媒体库、活动／忽略、缺少海报、全部候选、MediUX 候选、变化、评分和流派搜索筛选。可按标题、年份、评分、时长、最近变化或添加日期排序；打开项目再返回会保留 URL 条件。

另有一个独立的图片覆盖筛选：已应用到此服务器、已导出到 Kometa、需要图片、覆盖状态未知。Review 使用同一个控件，取值在两处含义相同，所以链接可以互换。依赖它们之前请先读图片覆盖：它们陈述的是 PosterPilot 做过什么，而不是标题有没有海报。

批量操作可选择本页或选择全部结果，并显示已加载与总数。全部结果由精确筛选在服务器端物化；更改查询会使选择失效。

Review 收件箱

Review 按新项目、未解析、无候选、建议就绪、已暂存、部分失败、外部变化、忽略、完成组织。可筛选、排序并保存视图。打开项目后，上一个／下一个／返回会保留上下文。状态筛选旁边就是图片覆盖筛选，两者回答的问题不同：“状态”是你在流程里走到了哪一步，“覆盖”是目的地上实际发生了什么。

按槽位比较当前、建议和暂存海报。接受建议是明确操作；仅打开页面不会保存。键盘快捷键不会在编辑控件或模态框中触发。

应用并下一个使用普通预览／确认，等待任务和写入后验证，只有全部选定目的地成功才前进。失败、跳过或部分结果会留在当前项目并显示详情与重试。

修正 TMDB 匹配

下游的一切——会去找哪些图片、写入哪条 Kometa 条目、同一标题的两个副本如何被认作同一个——都取决于 PosterPilot 为项目解析出的 TMDB 身份。

TMDB 给电影和剧集分别编号：电影 105 与剧集 105 是两个毫不相干的标题。媒体服务器已经知道项目属于哪一种，PosterPilot 以此为准，只在该命名空间内解析。项目携带的 GUID 按固定优先级尝试：先 TMDB ID，再 IMDb，最后 TVDB。直接给出的 TMDB ID 会从对应端点回读校验——剧集按剧集查、电影按电影查——只存在于另一命名空间的 ID 解析不成功。IMDb 或 TVDB ID 走 TMDB 的 find 端点，并且只接受对应的结果分组，命中另一分组会被丢弃而不是借用。实际效果是剧集库不可能再解析成电影。TMDB 回答“不在此命名空间”会让项目保持未解析，这与网络或凭据失败不同：后者会让项目既未解析又未同步，下次同步会重试，而不是接受一个错误答案。

规范化横幅

命名空间保护出现之前的版本可能已经存下了类型错误的 TMDB 身份，而修好解析器并不会追溯修正数据库里已有的行。所以升级之后 PosterPilot 会统计它们，并在每个页面顶部的横幅里说明——“有 N 个旧版 TMDB 匹配需要规范化。”——附带规范化匹配操作，并注明这次定向修复会纠正电影和剧集身份，无需完整重新扫描，也不会应用图片。

计数范围刻意收得很窄：只包含当前服务器上、存储的 TMDB 媒体类型与媒体服务器自身类型相矛盾的项目；不包含手动固定的项目，因为固定是你对身份的声明，优先于任何自动修复；也不包含已经离开媒体库的副本。这个数字每次显示都会从数据库重新统计，因此恢复备份或手工改动数据行都不需要额外修复标志位，而没有待处理项时横幅会自行消失。

规范化匹配会派发一个范围恰好限定为这些项目的修复任务：在正确的命名空间内重新解析并重新补全元数据，仅此而已——它不应用图片、不改动已暂存的选择，也不遍历媒体库的其余部分。任务运行期间横幅会显示进度并链接到仪表板；任务以失败、部分完成、取消或中断结束时，控件会变成重试规范化。每台服务器同时只能运行一个修复任务，再启动一个会指出已经占用该范围的那个任务。

为什么完整重新扫描是后备手段，而不是修复手段

仪表板的完整重新扫描会重新读取整个服务器媒体库：核对、重新解析、重新补全每一个项目，并重新观察它当前的图片（服务器上被改动过的会标记为待审核）。它保留原图与历史，绝不自动应用图片。当你怀疑本地缓存整体已经失真时——恢复备份之后，或者在媒体服务器上做过大规模修改之后——它才是对的工具。

对身份错配它是错的工具，原因有两个。其一，PosterPilot 已经能点名受影响的项目：定向修复只触碰这些行，而完整重新扫描要为同一个结果付出遍历整个媒体库、外加一整轮媒体服务器和 TMDB 请求的代价。其二，等待同样有效：待处理的类型不匹配不受增量跳过约束，普通同步下次扫到它们时就会重新处理，修复任务只是让你现在就修好，而不是它们唯一的修复途径。

当问题是“我的本地副本整体还准确吗”时才用完整重新扫描——而不是在答案已经是一份名单的时候。

手动固定匹配

按标题、年份和电影／剧集类型搜索未解析或匹配错误的项目。结果包含 TMDB 身份与用于区分的元数据。确认前会立即从 TMDB 重新读取该身份，因此在搜索与确认之间消失的候选会被拒绝而不是被固定，TMDB 无法访问时你当前的匹配也不受影响。确认成功会固定该身份、让旧身份下发现的候选退役，并记录一条审计事件。不会应用任何图片——请重新运行查找封面，为新身份发现图片。

固定具有权威性：同步不会覆盖它，规范化清理也会跳过它。替换和清除同样必须是明确操作。清除会立即改用项目自身存储的 IMDb／TVDB ID 重试自动解析——TMDB ID 那一列属于固定值，只有这些独立 ID 可以安全复用——并报告结果：恢复了自动匹配、没有找到匹配，或者无法执行解析。两个 ID 都没有的项目只是重新变得可解析，之后的同步可以补上新的 TMDB GUID。每一次转换（固定、替换、清除、已解析、未解析）都保留在项目的匹配审计记录里。

提供方故障相互隔离。临时故障时可以保留该提供方最后已知可用的候选并标记为陈旧；之后一次成功返回的空结果会清除它们，而不是把“没有候选”当成故障。

发现并暂存海报

项目中的查找封面会查询启用的提供方，按提供方／套装分组海报与背景，剧集还包含季海报和标题卡。可以暂存单个槽位、整个套装或混合选择。最高评分候选会标记，但仍需明确接受。

提供方卡片按你在设置 → 元数据与提供方里配置的顺序排列，而不是按发现恰好完成的顺序——后者只记录了哪个提供方先响应。这个顺序既是展示顺序，也是得分完全相同的候选之间的决胜条件；它绝不会推翻不相等的得分，所以你排在最后的提供方给出更清晰的图片，仍然会赢得建议。详见配置里的提供方顺序。

提供方分区、单个套装卡片以及剧集的季分组都可以折叠。首次加载时展开第一个提供方及其第一个套装——ThePosterDB 有结果时也一并展开，因为它以单个扁平套装返回——其余保持折叠；你的折叠／展开选择会在浏览器中跨刷新、跨项目保留。

每个提供方分组都有自己的 ⟳ 重新搜索控件，只对该提供方重新运行发现并绕过 HTTP 缓存，用新结果替换该提供方已存候选，其他提供方不受影响。

固定构建器汇总主海报、背景、季和单集槽位。自定义 URL 也是普通槽位。文件上传先预览／确认，并且只能直接写服务器，因为二进制无法表示为 Kometa YAML URL。自定义 URL 由 PosterPilot 自行下载以校验确切字节，因此 URL 必须能从 PosterPilot 容器访问（仅媒体服务器可见的地址不行）；不可校验的写入是有意不支持的。

展开更多，而不必加载全部

一部大片可能带着数百张封面，无论你会不会滚动到那里，一次性渲染全部都很昂贵。所以每个网格先显示 24 张，加载更多再放出 24 张（或剩下的全部），并说明放完之后还有多少仍被隐藏。选 24 是因为它能整除页面用到的每一种网格——背景两列、标题卡四列、季海报八列——所以每次展开都不会留下参差的半行。控件旁边的说明始终给出算式：已显示多少、共多少、还隐藏多少。

每个网格各自独立展开：放出更多海报不会连带放出背景，同一提供方的两个套装分别展开，每一季的海报和标题卡各自计数。尚未放出的图块根本不会渲染，而不是延迟加载——延迟加载的图片仍然要占一个元素。

展开不产生任何网络开销：该项目保留的全部清单已经在页面里了。网格够不到的，是 PosterPilot 没有保留的那部分。TMDB 会返回它持有的每一张图片，而采集对每种图片类型设有 200 个候选的防御性上限；网格停在这个上限时会明说——“该提供方返回的封面超过 PosterPilot 保留的数量；此网格并非完整列表。”——而不是暗示你看到的就是存在的全部。详见配置里的候选清单与“加载更多”。

放大查看候选

每张图块的图片下方都有自己的放大控件，与暂存它的控件分开。放大只是看一眼，绝不是一次选择：它不暂存、不保存，也不改动任何槽位。

对话框显示的是规范资源——正是会上传到你的服务器或写进 Kometa YAML 的那个文件——完整且未经裁切，并附上裸图片无法传达的来源信息：提供方、像素尺寸，以及提供方报告了语言时的语言。从不标注语言的提供方（MediUX、ThePosterDB）不显示语言行，因为“无语言标记”描述的是来源而不是这张图片。

←／→ 或方向键遍历序列，Esc 或 ✕ 关闭对话框并把焦点还给你打开它的那张图块。你在序列中的位置显示在两个控件之间，并会随变化播报；控件到两端即停而不循环——一个跳回第一张的“下一张”会与你正在读的位置自相矛盾。序列就是屏幕上的内容：同样的提供方顺序、同样已展开的套装、同样的语言筛选、同样已放出的图块，“下一张”永远够不到页面本身正在隐藏的图片。如果网格在预览打开期间变了——你又放出了一批，或者后台任务完成了——对话框会跟随你正在看的那张图片，只有在确实没有内容可显示时才关闭。无法以原始尺寸加载的资源会明说，而不是在新候选的说明下显示上一张候选的图片。

浏览时实际下载了什么

每个候选都有一个规范资源——真正会被应用的那个文件——有些提供方还会同时发布一个较小的版本。PosterPilot 对取哪一个、什么时候取有明确取舍。网格在提供方提供优化版本时取优化版本——TMDB 提供 w500 海报和 w1280 背景而不是原图——并且经过 PosterPilot 自己的缩略图缓存，因此这些字节只从提供方取一次，之后在多次页面加载、多个项目以及使用该实例的所有人之间复用。MediUX、Fanart.tv 和 ThePosterDB 不发布单独的预览图，它们的图块使用规范 URL——同样经过该缓存，所以反复浏览也不会一直去打扰提供方。放大预览和应用路径使用规范资源，直接从提供方获取；预览刻意绕过缩略图缓存，因为该缓存是为网格尺寸的图片准备的，用原图把它填满会挤掉它本该提供的缩略图。

放大的图片只在对话框打开期间存在，所以一个有一百张 TMDB 图块的网格会下载一百张缩略图和零张原图，直到你主动要求其中一张为止。对于不发布预览版本的提供方，网格那一次缓存获取就是全部，无论你回访多少次。缓存的有效期与大小由 THUMB_CACHE_TTL_DAYS 和 THUMB_CACHE_MAX_MB 控制，参阅配置。

图片语言

配置了 TMDB 图片语言时，项目页会按该语言筛选各个网格并在上方说明——写出语言名，以及有多少封面被隐藏在其他语言里——同时提供显示所有语言开关。这个开关只作用于当前页面，绝不会改动你保存的偏好（用“仅显示〈语言〉”切回去）。如果这个标题没有任何匹配项，页面会说明其他语言里有多少封面并给出同样的出口，而不是给你一个空网格。该偏好只管 TMDB 图片，设置之前值得先读配置里的 TMDB 图片语言。

预览并应用

选择方式（初始为 DEFAULT_APPLY_METHOD）：

• 直接服务器 (plex) — 保存先前状态，通过当前 Plex／Jellyfin／Emby 写入，在支持时锁定并验证。
• Kometa — 更新 posterpilot-movies.yml 或 posterpilot-shows.yml，保留无关内容并验证 YAML。
• 二者 — 目的地独立；一处失败不会隐藏另一处结果。

先生成项目、槽位、候选、当前状态、目的地和跳过项的精确预览。独立确认使用会过期、单次使用并绑定选择／指纹的计划。任一内容变化都会拒绝写入并要求重新预览。无警告的计划——没有跳过项且至少有一次写入——一键即可应用：PosterPilot 会在同一操作中自行确认。存在跳过项会恢复显式确认，应用并转到下一项始终保留其对话框。

批量预览冻结全部 ID，并可为构建计划进行无破坏发现；执行时不重新发现或替换。找不到对应子项的季／单集会跳过，一个槽位失败不会中止其他槽位。

Kometa 如何使用导出

posterpilot-movies.yml 使用 TMDB ID，没有时回退到 IMDb；posterpilot-shows.yml 使用 TVDB ID，没有时也回退到 IMDb，并嵌套季和单集。请把对应文件加入 Kometa 媒体库的 metadata_files。Kometa 管理器可以维护引用，并说明物理路径与 Kometa 运行时可见的 file: 前缀之间的区别。

图片覆盖

图片时间线回答的是“PosterPilot 做了什么”，覆盖回答的是另一个问题——“现在的事实是什么”——两者可能不一致，这正是它们分开的理由。每个项目页的主视觉下方都有图片覆盖面板，库墙和 Review 也可以按它筛选。

覆盖始终按目的地分成并排的两块报告：媒体服务器是 PosterPilot 上传到 Plex、Jellyfin 或 Emby 的图片，Kometa 元数据是 PosterPilot 写进它的 Kometa YAML 文件的条目。两块永远不会合并成一个结论，计数也绝不相加。整个面板存在的意义就是守住这条区分：

导出到 Kometa 不等于应用图片

导出只是磁盘上某个 YAML 文件里的一行。写下这一行只证明文件被写了，并不证明 Kometa 运行过、Kometa 读过这个文件、你的媒体服务器接受了结果，或者那个 URL 现在仍然可用。面板会照实说明——“已导出到 Kometa 文件。PosterPilot 无法确认 Kometa 是否已应用。”——并且绝不会把一次导出提升成服务器侧的结论。如果你只用 Kometa 方式应用，媒体服务器那一块会一直说那里没有应用过任何东西；这是正确的陈述，不是缺陷。

同一标题的多个副本适用同样的规则。一部电影同时存在于两台服务器上，或者因为同时位于 Movies 和 Movies 4K 而在同一台服务器上出现两次，就是多个各自独立取证的副本——给其中一个应用了海报，并不能证明另一个的情况。标题有多个副本时，标题栏按目的地报告计数（“2 个副本中有 1 个已覆盖”），而不是一个合并数字：一个副本应用到服务器、另一个副本导出到 Kometa，并不等于“2 个中有 2 个”。

面板里的每个槽位——海报、背景、每一季、每一集——也各自保留自己的状态。剧集海报在服务器上已验证而分集标题卡没有，面板就照实这么说，而不是收敛成一个徽章。

各状态的含义

状态	含义
已应用到此服务器	我们写入过，而且我们期望的指纹与服务器此刻提供的内容仍然一致。这是媒体服务器上唯一一个肯定且经过验证的状态。
已导出到 Kometa	当前的元数据文件里有这个槽位的 URL。磁盘上的一个文件——见上面的提醒。
已应用，未验证	我们写入过，但无法检查服务器当前的状态。有历史记录，没有证明。
已在 PosterPilot 之外被更改	我们写入过，之后有东西把它换掉了。这是它自己的状态，不是任何别的状态的同义词。
PosterPilot 未应用	一次可靠的观察没有找到我们在这里写过图片的证据。
覆盖状态未知	我们没能可靠地观察——Kometa 文件读不了、媒体服务器连不上、历史不完整。

其中三种措辞是承重的，读得随意就会被误导：

“PosterPilot 未应用”不是“没有图片”。 它陈述的是我们做过什么，绝不是你的服务器上有什么。多年前你在 Plex 里手工换过海报的标题在这里显示为未应用——而它有一张好好的海报。系统里刻意没有任何覆盖状态、也没有任何筛选值声称某个标题没有图片，因为 PosterPilot 无从知道这件事。

“已在 PosterPilot 之外被更改”是它自己的答案。 有东西替换了我们的图片——Plex 自己的代理、另一个工具，或者某个人。把它读成“缺失”并重新应用，就永远查不出到底是谁在不停覆盖你的媒体库。

读取失败是“未知”，绝不是“未应用”。“我们没能检查”和“我们检查了，它不在那里”是两件不同的事实；把它们混为一谈，一个覆盖完好的媒体库就会被报成空的，并诱使你把一切重新导出一遍。所以读不了的 Kometa 文件、无法解析的目录，或者没能完整读取的历史，都会得出“覆盖状态未知”；而文件不存在是一次可靠的观察，不会。

按覆盖筛选

库墙与 Review 共用同一个图片覆盖控件：已应用到此服务器表示至少有一个槽位在当前服务器上已验证；已导出到 Kometa 表示至少有一个槽位出现在当前的元数据文件里；需要图片表示两个目的地都没有覆盖——PosterPilot 从未碰过的标题也会命中，这是单纯查状态做不到的；覆盖状态未知表示至少有一个槽位的证据不确定，即任一目的地为“覆盖状态未知”，或服务器上为“已应用，未验证”。

请注意“至少有一个槽位”：应用了海报但没有标题卡的剧集会命中“已应用到此服务器”。筛选用来找出值得打开的标题，逐槽位的事实在项目页的面板里。覆盖以副本所属的服务器为范围，所以切换当前服务器会改变答案。筛选没有结果时，空状态会说明并提供一键返回“任意覆盖状态”，而不是把你留在一片空白的网格前，猜是哪个控件把它清空了。

覆盖如何保持最新

覆盖是从三份它并不拥有的来源重建出来的投影：只追加的修订账本、对你服务器逐槽位的当前观察，以及磁盘上的 Kometa 文件。应用、撤销、同步以及 Kometa 迁移或配置写入之后都会重新推导；并且因为没有谁会在别人直接在 Plex 里换海报时通知 PosterPilot，证据超过 15 分钟的项目页会在你打开它时重新观察服务器。

由此产生两个刻意的结果。刷新绝不会拖垮触发它的操作：一次成功了却没能更新投影的应用仍然是一次成功的应用，代价只是数据陈旧，下一次触发就会修好。核对覆盖不会改动其他任何东西：它不写图片、不写 YAML、不写匹配，也绝不把任何东西标记为已审核。你在队列里的位置是你的声明，某个目的地上的事实是 PosterPilot 的声明——两者不得互相编辑。

验证、历史与撤销

时间线记录每个目的地／槽位、来源、先前状态、结果以及精确／尽力验证。失败或证据不可用绝不会显示为验证成功。

可以预览撤销某个可用修订、某一季或整个项目。确认只恢复冻结快照／值，在支持时验证并追加新修订。部分撤销会保留成功恢复。参阅安全、验证与撤销。

失败与重试

任务详情按目的地／槽位显示成功、失败、跳过、中断与已净化错误。仅重试失败项只为可重试失败创建关联工作，不重复成功。配置或计划错误需要修正并重新预览。

FUN、合集与多服务器

FUN 包含最多三选一、盲选／胶囊、Poster Match、画廊和时长预算。合集显示成员、来源、一致性、系列覆盖和单项覆盖，并可一键重新搜索全部成员。二者都不会自动应用。参阅 FUN 与合集。

多服务器使用切换器，媒体库、任务、Review、合集和自动化保持隔离。参阅多服务器迁移。

详细运行记录在设置 → 活动；诊断、自动化、备份和恢复见自动化与恢复。