# MoviePilot 缓存移植对照(TMDB 缓存 / 通用缓存 / 图片缓存)

上游:`/opt/moviepilot-plus/upstream/MoviePilot/app`。原则:接口与行为照搬,只把存储从进程内存 / 文件换成 PG。

## 通用缓存层:`app/runtime/cache.py` → `packages/db/src/cache.ts`

| 上游 | 我们 | 说明 |
|---|---|---|
| `MemoryBackend` + `_MemoryTLRUCache`(按 region 分区的 cachetools `TLRUCache`) | `PgCache`(表 `kv_cache`,迁移 0042) | region 分区、每 key 独立 TTL |
| `set(key, value, ttl, region, maxsize)`;`ttl <= 0` 删除 key | `PgCache.set(region, key, value, {ttl, maxsize})` | 同;TTL 单位秒 |
| TLRU 淘汰:写入时先 `expire()` 过期项,再按最近使用淘汰到 maxsize | `evict()`:删 region 内过期行,再按 `accessed_at` 从旧到新删到 maxsize | get 命中刷新 `accessed_at`(TLRU 的"使用") |
| `get` 未命中返回 None | `get` 返回 null | |
| `exists / delete / clear(region) / items(region)` | 同名方法 | `items` 额外带过期时间与字节数(管理界面) |
| `DEFAULT_CACHE_TTL = 365 天`、`DEFAULT_CACHE_SIZE = 1024` | 同名常量 | |
| `@cached(region, maxsize, ttl, skip_none, skip_empty, skip_if, empty_ttl, empty_if)` | `cachedCall(cache, key, opts, fn)` | should_cache / get_cache_ttl 逻辑逐条对应 |
| `fresh()` 上下文 | `opts.fresh` | 跳过读、照常写 |

偏离(仅存储介质与 TTL 取值):值用 JSON(jsonb)代替 pickle;TTL 值来自 `settings.storage.cacheTtl`(CACHE-2,见 runbook/storage.md),
追踪中的作品详情命中时续期(`PgCache.renew`,只延长);过期行需要物理删除,加定时任务 `cache.sweep`(每 10 分钟);
PG 读写失败时 TMDB 路径按未命中处理(内存缓存不会失败)。

## TMDB 请求缓存:`tmdbv3api/tmdb.py TMDb.request` 的 `@cached` → `packages/adapters/src/tmdb/client.ts`

| 上游 | 我们 |
|---|---|
| `maxsize = CONF.tmdb`(256;大内存 1024) | 设置 `cache.tmdbMaxSize`(缺省 5000,存 PG 不受进程内存约束) |
| `ttl = CONF.meta = META_CACHE_EXPIRE 小时`(缺省 24) | CACHE-2 起按请求类别取设置:`/search/`、`/find/` 用 `storage.cacheTtl.tmdbSearchDays`(7 天),其余用 `tmdbDetailDays`(30 天) |
| `empty_ttl = EMPTY_RESULT_CACHE_TTL`(1800 秒),`empty_if = results 为空列表` | `storage.cacheTtl.tmdbMissDays`(1 天);`isEmptyResult` 同判定 |
| `skip_none`(连接失败不缓存)、`skip_if = success:false`(业务失败不缓存) | 这两类在 `fetchWithRetry` 抛错,不会写缓存 |
| 键 = 函数名 + (method, url, params) | 键 = `path?query`(参数排序,不含 api_key / token) |
| region 自动生成 | region `tmdb.request` |

## TMDB 识别缓存:`modules/themoviedb/cache.py TmdbCache` → `apps/server/src/modules/sources-identity/service/tmdb-recognize-cache.ts`

| 上游 | 我们 |
|---|---|
| `__get_key`:`[{meta.type.value 或 '未知'}][{TMDB_LOCALE}]{media_id 或 meta.name}-{meta.year}-{meta.begin_season}` | `recognizeKey`:同格式;类型用 MP 的中文值(电影 / 电视剧 / 未知),语言取 TMDB 客户端首选语言,None 写作 `None` |
| `meta.name`:中文名全是汉字优先,否则英文名,再退中文名 | `recognizeMetaOf` 同规则;有季或集即"电视剧",否则"未知"(MetaVideo) |
| 值 `{id, type, year, title, poster_path, backdrop_path}` | 同字段(type 用 movie / tv) |
| `update(meta, info)`:info 非空写正常条目(默认 ttl);`{}` 写负缓存 `{"id": 0}`(`EMPTY_RESULT_CACHE_TTL`);None 不写 | `saveRecognizeCache(meta, info)`:info / null / undefined 三态一一对应 |
| `get(meta)` 读;类型冲突(元数据电视剧、缓存电影)删除后按未命中 | `loadRecognizeCache` 同 |
| `update` 时类型冲突拒绝写入 | 同 |
| `maxsize = CONF.tmdb`、`ttl = CONF.meta`,每条独立 `expires_at` | 条数同设置;正常条目 TTL 取 `tmdbSearchDays`,负缓存取 `tmdbMissDays`;`kv_cache.expires_at` 每条独立 |
| `_restore / save`:pickle 文件持久化与恢复 | 不需要:表本身就是持久化(UNLOGGED 在 PG 崩溃时清空,等价于缓存丢失) |
| `list_items / delete / clear` | `GET /cache/tmdb`、`POST /cache/tmdb/clear`(清空时同时清请求缓存,对应 MP `clear_cache()`) |
| `is_redis` 分支 | 忽略 |

调用点(`modules/themoviedb/__init__.py`):

| 上游 | 我们(`service/resolve.ts`、`service/identity-admin.ts`) |
|---|---|
| `_recognize_steps`:LOAD_CACHE(`cache=True` 时)→ 命中且有 title 则 LOAD_DETAILS(按缓存 id / type 取详情);命中负缓存 → 未识别 | `tmdbCandidates`:命中且有标题 → `details(type, id)` 作唯一远端候选;命中 `{id:0}` → 远端候选为空 |
| 未命中:按名称搜索(中文名、简体、英文名依次)→ SAVE_CACHE(info) | 未命中:按解析名搜索 → 识别结论为 TMDB 条目写正常条目,`no_match` 写负缓存,TMDB 出错 / 有歧义不写 |
| `recognize_media(cache=False)` 不读缓存 | 强制复查(`force`)不读缓存,照常回写 |
| `update_recognize_cache(meta, mediainfo)`:共享识别后回填 | 人工认定资源身份后 `backfillRecognizeCache` 回填 |

偏离:我们的识别有本地作品优先与歧义(需人工确认)两个 MP 没有的结论。歧义时不写缓存(MP 没有这一态);
本地作品胜出时不写(MP 无本地召回)。

## 图片缓存:`application/image.py ImageHelper` + `api/endpoints/system.py fetch_image` → `apps/server/src/modules/cache/images.ts`

| 上游 | 我们 |
|---|---|
| 缓存路径 `SecurityUtils.sanitize_url_path(url)`:URL 路径编码,超 120 字符换 `compressed_<sha256 前 16><ext>`,无后缀补 `.jpg`;放在 `CACHE_PATH/images/` | `imageCachePath`,放在 `DATA_DIR/cache/images/` |
| `use_cache` 才读缓存;拉到的合法图片总会 `file_cache.set` | 同 |
| `/cache/image`:`use_cache = GLOBAL_IMAGE_CACHE`(缺省 False) | 设置 `cache.globalImageCache`(缺省关闭) |
| `get_image_mime_type`:Pillow 识别,拒绝非图片与 SVG | 按文件头识别 jpeg / png / webp / gif,其余拒绝 |
| `ETag = md5(content)`,`Cache-Control: public, max-age=604800`,If-None-Match 相同回 304 | 同 |
| `SECURITY_IMAGE_DOMAINS` 白名单 | 只代理 `image.tmdb.org`,尺寸与文件名走白名单 |
| `clear_temp`:删除 `CACHE_PATH/images` 下 mtime 超过 `GLOBAL_IMAGE_CACHE_DAYS`(7)天的文件与空目录 | 设置 `cache.globalImageCacheDays`(缺省 7);定时任务 `cache.images_clean` 每天执行 |

偏离:MP 失败时返回空响应,我们回 502(前端回退占位);CACHE-2 加了容量 LRU(`cache.images_lru`,按 atime,预算 `storage.budgets.imagesGb`),
按天清理保留作兜底;MP 按配置走代理服务器,我们直连(TMDB API 也未走代理);
MP 只在启动时清理,我们改为每天一次的定时任务。

## 统一元数据缓存(2026-10-06)与 MP 的差异

用户定:TMDB / 豆瓣 / Bangumi 共用一套缓存策略,更积极地缓存,不上 Redis(PG `kv_cache` 二级 + 进程内存一级)。
键、TTL 语义(正常 / 空结果短 TTL)、失败不缓存与上面各表一致;以下是 MP 没有、我们加的部分(详见 [runbook/cache.md](../runbook/cache.md)):

| 项 | MP | 我们 | 理由 |
|---|---|---|---|
| 存储层级 | 单进程内存 `TLRUCache`(可选 Redis) | L1 进程内存(每 region 1000 条、5 分钟)+ L2 PG `kv_cache`;读 L1 → L2 → 源,写两级 | 三个进程共享 L2,热点走 L1 少一次 PG 往返 |
| TTL | `META_CACHE_EXPIRE` 一个值 + `EMPTY_RESULT_CACHE_TTL` | 「来源 × 资源类型」策略表:搜索 7 天 / 详情 30 天 / 列表 6 小时 / 人物与图片 90 天,空结果 1 天(列表 1 小时),取 `storage.cacheTtl` | 用户要求更积极地缓存,不同资源变化频率差很多 |
| 过期 | 过期即未命中 | 宽限期(TTL 的 50%,最多 7 天)内先返回旧值、后台刷新;刷新失败继续用旧值并记警告 | 元数据过期后通常仍可用,不让请求等外站;外站故障时不降级 |
| 并发 | `@cached` 无合并(TMDB 客户端内存 LRU 有) | 同进程同 key 只回源一次(含后台刷新) | 列表页 / 批量识别并发多 |
| 淘汰 | TLRU | TLRU,但关注中作品的 TMDB 条目 `pinned` 不参与 LRU,命中续期 | 关注作品的详情 / 季 / 剧集组要一直在 |
| 预热 | 无 | 作品进入关注时排 `prewarmMetadata`:详情、各季、剧集组、海报 / 背景 / 标志 | 订阅 / 下载后马上要刷新与刮削 |
| 失效 | 进程内,`clear_cache()` | `PgCache.delete / clear` 发 `pg_notify('umt_cache_invalidate')`,各进程丢 L1;监听断开时 L1 停用,重连后整体清空 | 多进程下 L1 不能拿旧值 |
| 统计 | 无 | 按 region 计 L1 / L2 / 旧值 / 未命中 / 回源失败 / 后台刷新,每分钟写 `cache_stat`,设置页显示近 7 天命中率 | 看缓存是否起作用 |
| 豆瓣 / bgm 条目查询失败 | `DoubanApi` / `BangumiApi` 失败不缓存 | 同;只有「条目不存在」写 `meta.subject_miss`(以前网络失败也记 6 小时负缓存),失败后本进程同一条目冷却 30 分钟 | 策略表「失败不缓存」 |
| TMDB 详情请求 | `append_to_response` 不含 images | 富详情加 `images`(`include_image_language=zh,en,null`),原语言不是中英文时另取 `/images`,选标志写 `clearlogo.png` | 用户定:不接 fanart.tv,用 TMDB logos;请求键变化后旧的富详情缓存会各自 miss 一次 |