feat(cache): TMDB image proxy, posters, cache admin API and settings cards
GET /img/tmdb/{size}/{file} ported from MP ImageHelper / fetch_image
(sanitized cache path under DATA_DIR/cache/images, GLOBAL_IMAGE_CACHE
read switch, md5 ETag / 304, day-based cleanup job). Cache module adds
cache.sweep / cache.images_clean jobs and /cache/tmdb, /cache/images
list and clear endpoints. Library list/detail and the search palette
show posters with the neutral placeholder as fallback; metadata settings
get TMDB cache and image cache cards. Runbook docs/runbook/cache.md and
porting notes docs/porting/moviepilot-tmdb-cache.md.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
rootandClaude Opus 5.5 committed
1 parent
946fca5e55
commit
7862573944
16 files changed
+1028
-9
No files matched your search
+210
@@ -0,0 +1,210 @@
|
||||
import { join } from "node:path";
|
||||
import { createRoute, type RouteConfig } from "@hono/zod-openapi";
|
||||
import {
|
||||
Api,
|
||||
apiResponse,
|
||||
DEFAULT_SETTINGS,
|
||||
type EndpointDef,
|
||||
type TmdbCacheItem,
|
||||
type TmdbCacheList,
|
||||
} from "@umt/contracts";
|
||||
import type { z } from "zod";
|
||||
import { dataPaths } from "../../config.ts";
|
||||
import { requireScope } from "../../http/auth.ts";
|
||||
import { errorBody } from "../../http/errors.ts";
|
||||
import { CACHE_REGIONS, sharedCache, tmdbCachePolicy } from "../../shared-cache.ts";
|
||||
import { registerScheduledJob } from "../schedules/registry.ts";
|
||||
import type { ModuleApp, ServerContext, ServerModule } from "../types.ts";
|
||||
import { ImageCache, ImageProxyError } from "./images.ts";
|
||||
|
||||
/**
|
||||
* C2-A 缓存(docs/runbook/cache.md):
|
||||
* - PG 缓存 kv_cache(UNLOGGED,移植 MP TTLCache)的过期行物理清理任务 cache.sweep(每 10 分钟);
|
||||
* - TMDB 缓存管理(对照 MP tmdb_cache_items / tmdb_cache_clear):GET /cache/tmdb、POST /cache/tmdb/clear;
|
||||
* - 图片代理 GET /img/tmdb/{size}/{file}(会话或 API Key read,移植 MP ImageHelper / fetch_image)+ DATA_DIR/cache/images 落盘,
|
||||
* 用量 / 清空 GET /cache/images、POST /cache/images/clear,按保留天数清理的任务 cache.images_clean(每天)。
|
||||
*/
|
||||
export interface CacheModuleOptions {
|
||||
/** 图片上游 fetch(测试注入) */
|
||||
imageFetch?: typeof globalThis.fetch;
|
||||
/** 图片上游基址(测试指向 mock) */
|
||||
imageUpstreamBase?: string;
|
||||
/** 图片缓存目录;缺省 DATA_DIR/cache/images */
|
||||
imageDir?: string;
|
||||
}
|
||||
|
||||
type Infer<T> = T extends z.ZodType ? z.infer<T> : Record<string, never>;
|
||||
|
||||
function route<D extends EndpointDef>(
|
||||
app: ModuleApp,
|
||||
def: D,
|
||||
handler: (i: { query: Infer<D["query"]> }) => Promise<unknown>,
|
||||
) {
|
||||
const request: RouteConfig["request"] = {};
|
||||
if (def.query) request.query = def.query as never;
|
||||
const r = createRoute({
|
||||
method: def.method,
|
||||
path: def.path,
|
||||
summary: def.summary,
|
||||
tags: ["cache"],
|
||||
middleware: [requireScope(def.scope)] as never,
|
||||
request,
|
||||
responses: {
|
||||
200: { description: def.summary, content: { "application/json": { schema: apiResponse(def.response) } } },
|
||||
},
|
||||
});
|
||||
// biome-ignore lint/suspicious/noExplicitAny: 路由泛型在封装里擦除,入参已由 zod-openapi 校验
|
||||
app.openapi(r, (async (c: any) => {
|
||||
const data = def.response.parse(await handler({ query: def.query ? c.req.valid("query") : {} } as never));
|
||||
return c.json({ ok: true, data }, 200);
|
||||
// biome-ignore lint/suspicious/noExplicitAny: 同上
|
||||
}) as any);
|
||||
}
|
||||
|
||||
const str = (v: unknown) => (typeof v === "string" && v ? v : null);
|
||||
|
||||
export function createCacheModule(opts: CacheModuleOptions = {}): ServerModule & {
|
||||
images(ctx: ServerContext): ImageCache;
|
||||
} {
|
||||
const imageCaches = new WeakMap<object, ImageCache>();
|
||||
const images = (ctx: ServerContext) => {
|
||||
let c = imageCaches.get(ctx);
|
||||
if (!c) {
|
||||
c = new ImageCache({
|
||||
dir: opts.imageDir ?? join(dataPaths(ctx.config).dataDir, "cache", "images"),
|
||||
...(opts.imageFetch ? { fetch: opts.imageFetch } : {}),
|
||||
...(opts.imageUpstreamBase ? { upstreamBase: opts.imageUpstreamBase } : {}),
|
||||
});
|
||||
imageCaches.set(ctx, c);
|
||||
}
|
||||
return c;
|
||||
};
|
||||
const cacheSettings = (ctx: ServerContext) => ctx.settings.get("cache").catch(() => DEFAULT_SETTINGS.cache);
|
||||
|
||||
return {
|
||||
name: "cache",
|
||||
images,
|
||||
registerRoutes(app, ctx) {
|
||||
// 图片代理:不进 OpenAPI(二进制响应);<img> 带 cookie 会话即可,API Key 需 read
|
||||
app.get("/img/tmdb/:size/:file", requireScope("read"), async (c) => {
|
||||
const s = await cacheSettings(ctx);
|
||||
try {
|
||||
// MP cache_img:GLOBAL_IMAGE_CACHE 开启才读磁盘缓存
|
||||
return await images(ctx).serve(
|
||||
c.req.param("size"),
|
||||
c.req.param("file"),
|
||||
s.globalImageCache ?? false,
|
||||
c.req.header("if-none-match") ?? null,
|
||||
);
|
||||
} catch (e) {
|
||||
if (e instanceof ImageProxyError) {
|
||||
return c.json(errorBody(e.status === 400 ? "bad_request" : "upstream_unavailable", e.message), e.status);
|
||||
}
|
||||
throw e;
|
||||
}
|
||||
});
|
||||
|
||||
route(app, Api.cache.tmdb, async ({ query }) => {
|
||||
const cache = sharedCache(ctx);
|
||||
const policy = await tmdbCachePolicy(ctx);
|
||||
const want = (k: "request" | "recognize") => !query.kind || query.kind === k;
|
||||
const items: TmdbCacheItem[] = [];
|
||||
if (want("recognize")) {
|
||||
for (const r of await cache.items<Record<string, unknown>>(CACHE_REGIONS.tmdbRecognize, query.limit)) {
|
||||
const v = r.value ?? {};
|
||||
const t = v.type === "movie" || v.type === "tv" ? v.type : "unknown";
|
||||
items.push({
|
||||
kind: "recognize",
|
||||
key: r.key,
|
||||
expiresAt: r.expiresAt.toISOString(),
|
||||
updatedAt: r.updatedAt.toISOString(),
|
||||
bytes: r.bytes,
|
||||
tmdbId: typeof v.id === "number" ? v.id : Number(v.id) || 0,
|
||||
title: str(v.title),
|
||||
year: str(v.year),
|
||||
mediaType: t,
|
||||
posterPath: str(v.poster_path),
|
||||
});
|
||||
}
|
||||
}
|
||||
if (want("request")) {
|
||||
for (const r of await cache.items(CACHE_REGIONS.tmdbRequest, query.limit)) {
|
||||
items.push({
|
||||
kind: "request",
|
||||
key: r.key,
|
||||
expiresAt: r.expiresAt.toISOString(),
|
||||
updatedAt: r.updatedAt.toISOString(),
|
||||
bytes: r.bytes,
|
||||
tmdbId: null,
|
||||
title: null,
|
||||
year: null,
|
||||
mediaType: null,
|
||||
posterPath: null,
|
||||
});
|
||||
}
|
||||
}
|
||||
const out: TmdbCacheList = {
|
||||
items,
|
||||
counts: {
|
||||
request: await cache.count(CACHE_REGIONS.tmdbRequest),
|
||||
recognize: await cache.count(CACHE_REGIONS.tmdbRecognize),
|
||||
},
|
||||
maxSize: policy.maxsize,
|
||||
ttlHours: Math.round(policy.ttl / 3600),
|
||||
emptyResultTtlSec: policy.emptyTtl,
|
||||
};
|
||||
return out;
|
||||
});
|
||||
route(app, Api.cache.tmdbClear, async () => {
|
||||
const cache = sharedCache(ctx);
|
||||
const deleted =
|
||||
(await cache.clear(CACHE_REGIONS.tmdbRecognize)) + (await cache.clear(CACHE_REGIONS.tmdbRequest));
|
||||
ctx.logger.info({ deleted }, "TMDB 缓存已清空");
|
||||
return { deleted };
|
||||
});
|
||||
route(app, Api.cache.images, async () => {
|
||||
const s = await cacheSettings(ctx);
|
||||
const img = images(ctx);
|
||||
const u = await img.usage();
|
||||
return {
|
||||
enabled: s.globalImageCache ?? false,
|
||||
days: s.globalImageCacheDays ?? DEFAULT_SETTINGS.cache.globalImageCacheDays,
|
||||
usedBytes: u.bytes,
|
||||
files: u.files,
|
||||
dir: img.dir,
|
||||
};
|
||||
});
|
||||
route(app, Api.cache.imagesClear, async () => ({ deleted: await images(ctx).clear() }));
|
||||
},
|
||||
registerTasks() {},
|
||||
start(ctx: ServerContext) {
|
||||
registerScheduledJob(ctx, {
|
||||
key: "cache.sweep",
|
||||
defaults: {
|
||||
name: "缓存清理",
|
||||
description: "删除 PG 缓存里已过期的条目（TMDB 请求与识别缓存）",
|
||||
group: "maintain",
|
||||
schedule: { type: "interval", everyMs: 10 * 60_000 },
|
||||
firstRun: "after_interval",
|
||||
},
|
||||
run: async () => ({ summary: `删除 ${await sharedCache(ctx).sweep()} 条过期缓存` }),
|
||||
});
|
||||
registerScheduledJob(ctx, {
|
||||
key: "cache.images_clean",
|
||||
defaults: {
|
||||
name: "图片缓存清理",
|
||||
description: "删除超过保留天数的图片代理缓存文件（对照 MP 启动时的 clear_temp）",
|
||||
group: "maintain",
|
||||
schedule: { type: "interval", everyMs: 24 * 3_600_000 },
|
||||
},
|
||||
run: async () => {
|
||||
const s = await cacheSettings(ctx);
|
||||
const n = await images(ctx).clean(s.globalImageCacheDays ?? DEFAULT_SETTINGS.cache.globalImageCacheDays);
|
||||
return { summary: `删除 ${n} 张过期图片` };
|
||||
},
|
||||
});
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export const cacheModule = createCacheModule();
|
||||
Reference in new issue
Block a user