Yamby 元数据图片缓存机制与加速原理

为什么需要图片缓存

Emby 媒体库的海报墙由大量图片组成——每部影片至少有海报、背景图、Logo 三种。一个 1000 部影片的库需要加载 3000+ 张图。如果每次进入媒体库都从 Emby 服务器重新加载，会导致：

• 加载慢（网络延迟 + 服务器 CPU 开销）
• 流量消耗大（每张图几百 KB）
• 服务器压力（每台客户端都来拉一遍图片）

Yamby 的图片缓存机制解决这个问题。

缓存原理

Yamby 的图片缓存工作机制：

1. 首次访问：从 Emby 服务器 API 请求图片 → 下载 → 解码 → 渲染到海报墙 → 同时存入本地缓存
2. 二次访问：检查本地缓存是否存在 + 是否过期 → 存在且有效则直接读本地磁盘，跳过网络请求
3. 过期策略：缓存设置了过期时间（默认 7 天），超过过期时间的缓存文件会被重新从服务器获取

缓存命中率在媒体库稳定后通常能达到 90%+——第二次打开媒体库几乎瞬间完成，就是因为图片全从本地读。

缓存存储位置

缓存文件存储在 Yamby 应用的内部私有目录下（Android 沙箱），路径大致为：

/data/data/com.hush.yamby/cache/images/

每个图片文件的文件名是 Emby 服务器图片 API 链接的 MD5 哈希值。所以不同服务器的图片不会互相覆盖——同一部电影在两台 Emby 服务器上的海报 URL 不同，缓存文件名也不同。

缓存大小管理

默认缓存大小上限为 256MB。超过上限时，Yamby 自动淘汰最久没访问的缓存文件。

手动调整缓存上限：设置 → 通用 → 图片缓存 → 最大缓存大小。可选范围 128MB - 2GB。

建议：

• 有 Wi-Fi 的场景：缓存设大一些（512MB+），多存几张海报省流量
• 流量敏感场景：缓存设小一些（128MB），避免后台偷偷占用空间

清理缓存

两种清理方式：

自动清理：超过过期时间的缓存 + 超过大小上限的缓存，Yamby 自动淘汰。

手动清理：设置 → 通用 → 图片缓存 → 清除所有缓存。清理后首次打开媒体库会重新加载所有图片（网络请求高峰，可能较慢）。

缓存与元数据刷新

Emby 服务器上管理员修改了某部影片的封面图后，Yamby 客户端不会立即看到——因为本地缓存里存的还是旧图。

让缓存失效的方法：

• 等待缓存自然过期（7 天）
• 手动强制刷新该影片 → 长按封面 → 「刷新图片」
• 手动清除所有缓存后重新加载

日常运维不需要手动管理缓存，保持默认设置即可。