Merge branch 'c2a'

docs/porting/moviepilot-tmdb-cache.md

@@ -0,0 +1,72 @@
+# 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` | 跳过读、照常写 |
+
+偏离(仅存储介质):值用 JSON(jsonb)代替 pickle;过期行需要物理删除,加定时任务 `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`(缺省 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` 同判定 |
+| `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` | 同设置;`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(前端回退占位);MP 按配置走代理服务器,我们直连(TMDB API 也未走代理);
+MP 只在启动时清理,我们改为每天一次的定时任务。

docs/runbook/cache.md

@@ -0,0 +1,61 @@
+# 缓存与限流运行手册(C2-A)
+
+不引入 Redis / Deno KV。跨进程共享的状态都放 PG:站点限流令牌桶、TMDB 缓存。缓存语义照搬 MoviePilot,
+对照与偏离见 [docs/porting/moviepilot-tmdb-cache.md](../porting/moviepilot-tmdb-cache.md)。
+
+## 跨进程站点限流
+
+- 表 `rate_limit_bucket`(迁移 `0041_rate_limit`):key `site:<站点 id>`,tokens / capacity / refill_per_sec / blocked_until。
+- `@umt/db` 的 `PgTokenBucket.acquire(key, cost, {capacity, refillPerSec, waitMs})`:事务里 `select … for update`,
+  按 DB 时钟补令牌后扣减;拿不到按需要等待的时间加抖动轮询,超过 waitMs 返回 `ok:false`(站点限流器会重新排队)。
+- 站点适配器用 `createSharedSiteRateLimiter`:进程内先串行排队,再到 PG 扣令牌;429 的 Retry-After 写 `blocked_until`。
+  站点限流间隔为 0(不限流)时只走本地;PG 出错时本次退回进程内令牌桶并记 warn。
+- 容量 = 站点并发(burst),速率 = 1000 / 最小间隔毫秒。改站点限流设置即时生效(每次扣令牌带上最新参数)。
+
+排查:`select * from rate_limit_bucket where key = 'site:<id>'`;`blocked_until` 不为空说明站点要求暂停。
+
+## PG 缓存(kv_cache)
+
+- 表 `kv_cache`(迁移 `0042_cache`,`UNLOGGED`:不写 WAL,崩溃后清空):(region, key) 主键,value jsonb,
+  expires_at 每条独立,accessed_at 为最近读写时间。
+- `@umt/db` 的 `PgCache`(对照 MP `TTLCache`):set 带 ttl(秒,≤ 0 删除)与 maxsize(按 region 计条数,超出先删过期再删最久未用);
+  get 命中刷新最近使用;`cachedCall` 对照 MP `@cached`(skip_none / skip_if / empty_ttl / fresh)。
+- 定时任务 `cache.sweep`(维护组,每 10 分钟)物理删除过期行。
+
+| region | 内容 | 键 | TTL | 条数上限 |
+|---|---|---|---|---|
+| `tmdb.request` | TMDB 请求响应(MP `TMDb.request`) | `path?query`(不含凭证) | `cache.tmdbTtlHours`;`results` 为空按 `cache.emptyResultTtlSec` | `cache.tmdbMaxSize` |
+| `tmdb.recognize` | TMDB 识别结果(MP `TmdbCache`) | `[类型][语言]{tmdbid 或名称}-{年份}-{季}` | 同上;未识别 `{id:0}` 按空结果 TTL | `cache.tmdbMaxSize` |
+
+设置(设置 → 元数据 → TMDB 缓存):`cache.tmdbTtlHours`(缺省 24,MP `META_CACHE_EXPIRE`)、`cache.tmdbMaxSize`(缺省 256,MP `CONF.tmdb`)、
+`cache.emptyResultTtlSec`(缺省 1800,MP `EMPTY_RESULT_CACHE_TTL`)。
+
+API:`GET /api/v1/cache/tmdb?kind=recognize|request&limit=` 列出条目(键 / 过期 / 大小,识别条目带 tmdbId / 标题 / 海报);
+`POST /api/v1/cache/tmdb/clear` 清空两类(仅 admin)。
+
+识别缓存何时读写(`sources-identity/service/tmdb-recognize-cache.ts`):
+- 识别资源时先读:命中且有标题 → 按 id 取 TMDB 详情作为唯一远端候选;命中 `{id:0}` → 不再搜索;强制复查(force)不读。
+- 写:自动识别到 TMDB 条目写正常条目;确认无匹配写 `{id:0}`;TMDB 出错或有歧义不写。
+- 人工认定资源身份后回填(MP `update_recognize_cache`),覆盖名称负缓存。
+- "元数据是剧集、缓存是电影"视为类型冲突:读时丢弃,写时拒绝。
+
+## 图片代理与海报
+
+- `GET /api/v1/img/tmdb/{size}/{file}`(会话或 API Key read):只代理 `image.tmdb.org`,size 走白名单(w92…original),
+  file 只允许 `[A-Za-z0-9_-]+.(jpg|jpeg|png|webp)`。
+- 缓存路径对照 MP `sanitize_url_path`:`DATA_DIR/cache/images/t/p/<size>/<file>`。
+- `cache.globalImageCache`(缺省关闭,MP `GLOBAL_IMAGE_CACHE`)开启才读磁盘缓存;拉到的合法图片总会写盘。
+- 按文件头识别图片类型,非图片 / SVG 拒绝;ETag = md5(内容),`Cache-Control: public, max-age=604800`,If-None-Match 相同回 304。
+- 上游超时(20s)/ 非 200 / 非图片 → 502,前端回退无彩占位。
+- 清理:定时任务 `cache.images_clean`(每天)删除 mtime 早于 `cache.globalImageCacheDays`(缺省 7)天的文件。
+- 用量 / 清空:`GET /api/v1/cache/images`、`POST /api/v1/cache/images/clear`(仅 admin);设置 → 元数据 → 图片代理与缓存。
+
+前端:作品库列表、作品详情、搜索面板的 TMDB 候选在有 `posterPath`(metadata.posterPath / TMDB 候选)时显示海报,
+加载失败回退原来的无彩占位。TMDB 详情刷新会把 posterPath / backdropPath 写进 metadata_field。
+
+## 常见问题
+
+- TMDB 缓存不生效:确认 `select region, count(*) from kv_cache group by 1` 有 `tmdb.request`;PG 读写失败时按未命中处理并记
+  `TMDB 缓存读写失败，按未命中处理`。
+- 改了 TMDB 缓存设置:新写入的条目按新 TTL / 上限;已有条目保持原过期时间,必要时清空。
+- 数据库重启后缓存为空:UNLOGGED 表的正常行为。