UHD_Media_Tool/docs/porting/moviepilot-tmdb-cache.md

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):

项	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 一次