docs(runbook): storage budgets and retention runbook (CACHE-2)

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/porting/moviepilot-tmdb-cache.md

@@ -15,7 +15,8 @@
 | `@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` | 跳过读、照常写 |
 
-偏离(仅存储介质):值用 JSON(jsonb)代替 pickle;过期行需要物理删除,加定时任务 `cache.sweep`(每 10 分钟);
+偏离(仅存储介质与 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`
@@ -23,8 +24,8 @@ PG 读写失败时 TMDB 路径按未命中处理(内存缓存不会失败)。
 | 上游 | 我们 |
 |---|---|
 | `maxsize = CONF.tmdb`(256;大内存 1024) | 设置 `cache.tmdbMaxSize`(缺省 256) |
-| `ttl = CONF.meta = META_CACHE_EXPIRE 小时`(缺省 24) | 设置 `cache.tmdbTtlHours`(缺省 24) |
-| `empty_ttl = EMPTY_RESULT_CACHE_TTL`(1800 秒),`empty_if = results 为空列表` | 设置 `cache.emptyResultTtlSec`(缺省 1800);`isEmptyResult` 同判定 |
+| `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` |
@@ -39,7 +40,7 @@ PG 读写失败时 TMDB 路径按未命中处理(内存缓存不会失败)。
 | `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` | 同设置;`kv_cache.expires_at` 每条独立 |
+| `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` 分支 | 忽略 |
@@ -68,5 +69,6 @@ PG 读写失败时 TMDB 路径按未命中处理(内存缓存不会失败)。
 | `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(前端回退占位);MP 按配置走代理服务器,我们直连(TMDB API 也未走代理);
+偏离:MP 失败时返回空响应,我们回 502(前端回退占位);CACHE-2 加了容量 LRU(`cache.images_lru`,按 atime,预算 `storage.budgets.imagesGb`),
+按天清理保留作兜底;MP 按配置走代理服务器,我们直连(TMDB API 也未走代理);
 MP 只在启动时清理,我们改为每天一次的定时任务。