Lampa如何集成TMDB API:影视目录数据获取与缓存策略完整指南

原创2026-11-14 17:33:152,141 阅读

Lampa如何集成TMDB API:影视目录数据获取与缓存策略完整指南

Lampa 是一款运行在电视和桌面端的免费流媒体应用,它的电影、剧集目录与海报数据全部来自 TMDB API。本文将带你拆解 Lampa 是如何封装 TMDB 接口请求、组装查询参数,并通过"内存 + IndexedDB"的多级缓存策略,让目录翻页秒开、海报稳定加载的,适合想深入了解其数据层设计的新手与开发者。

Lampa 主界面欢迎页,展示基于 TMDB 数据的影视目录浏览界面

认识 Lampa:为什么目录数据交给 TMDB

Lampa 本身不存储任何电影资料,也不提供视频托管,它只做两件事:从 TMDB 拉取目录数据,再从公共网络源解析播放地址。因此整个"电影目录"体验(海报墙、评分、简介、演职员、推荐)都取决于 TMDB 接口调用得有多高效。

Lampa 支持 LG WebOS、Samsung Tizen、Android、Windows、macOS 等多平台部署,可以通过 Dockerfile 一键构建镜像,或按 README.md 中的 MSX 说明上传到自有主机,msx/start.json 中配置好域名即可安装。

接口封装:TMDB 模块的 4 个核心方法

Lampa 将 TMDB 集成收敛在一个轻量模块里(见 app.min.js),对外只暴露 4 个方法:

方法 作用
api(url) 拼接 api.themoviedb.org/3/ 前缀,生成数据接口地址
image(url) 拼接 image.tmdb.org/ 前缀,生成海报/背景图地址
key() 返回内置的 TMDB API Key,免去用户配置
broken() 统计海报加载失败次数,触发自动代理

关键设计有 3 点:

  1. 零配置:API Key 直接内置在客户端(app.min.js),用户装完即用,不需要自己去 TMDB 官网申请密钥;
  2. 代理可插拔:当检测到 proxy_tmdb 开关打开时,api() 和 image() 会自动把请求前缀替换成用户填写的 tmdb_proxy_api / tmdb_proxy_image 代理地址(app.min.js);
  3. 失败自愈:海报连续失败超过 50 张时,若开启了"自动启用代理",客户端会自动打开 TMDB 代理开关(app.min.js)。

请求组装:一个查询参数生成器的复用

所有 TMDB 请求(目录、搜索、详情、剧集)都经过同一个参数组装函数(app.min.js),它会自动追加:

  • api_key:内置密钥;
  • language:由设置项 tmdb_lang 决定,还支持多语言兜底(先查本地语言,再查英文);
  • page、query、with_genres、sort_by、with_keywords、with_watch_providers 等分页与筛选参数。

以搜索为例,Lampa 会并行发起 电影、剧集、人物 三路搜索请求(app.min.js),用一个状态计数器 Status(3) 等三路都返回后再合并结果。目录翻页列表则带有"过滤后整页为空就自动取下一页"的补偿逻辑,保证用户看到的每一页都是满的(app.min.js)。

Lampa 搜索界面,输入片名后展示来自 TMDB 的电影与剧集搜索结果

缓存策略揭秘:三级缓存让目录秒开

Lampa 的 TMDB 数据不是"每次刷新都重新请求",而是分三层缓存:

1. 请求级缓存(带 TTL)

每次 TMDB 请求都通过统一入口 get() 发出,可携带 { life: 分钟数 } 的缓存参数(app.min.js)。不同数据的保鲜期被精心分级:

数据类型 缓存时长 原因
影视详情页(含演职员、推荐、相似片) 7 天 详情变化慢,app.min.js
目录/翻页列表 2 天 榜单缓慢变动,app.min.js
影视剧集某季信息 3 天 新季更新不频繁
影片"家庭发行日" 1 天 发行日期几乎不变

2. 内存级缓存(去重并发)

"仅显示已发行"过滤需要逐个查询影片的发行日期。Lampa 用一张内存表 released_dates(影片 ID → 日期)记录结果,并把等待中的回调挂到 released_waiting 队列:同一部影片的并发请求只发一次网络请求,"查无结果"的影片 24 小时内不再重查(app.min.js)。这是典型的"请求去重 + 短期记忆"模式。

3. IndexedDB 持久化缓存

页面级数据(卡片、海报、背景图等)落到浏览器的 IndexedDB,统一由 Cache 实例管理,内含 cards、images、timetable、storage 等 9 个数据仓库(app.min.js)。配合 Storage.cache(name, limit, default) 接口(app.min.js),书签、观看进度等数据都能带条数上限地持久化,重启电视后依然秒开。

Lampa 剧集浏览界面,展示 TMDB 提供的剧集列表、海报与评分数据

可用性保障:海报镜像轮询与自动封禁

海报域名 image.tmdb.org 在某些网络环境下不稳定,Lampa 内置了一套镜像轮询器(app.min.js):

  • 维护 imagetmdb.com 等多个镜像的实时状态;
  • 某个镜像 10 秒内出错 20 次即被临时封禁,自动切到下一个可用镜像;
  • 当前选中的镜像写入 tmdb_img_mirror 设置项,下次启动优先沿用;
  • 配合"自动启用代理"开关,海报大面积失败时整体切到用户或内置的 TMDB 代理(app.min.js)。

这套"镜像池 + 失败计数 + 自动封禁"机制,让海报加载的成功率远超直连单一域名。

Lampa 书签界面,收藏条目中的海报与简介均来自 TMDB 数据

动手实践:在设置中调整 TMDB 行为

Lampa 的 TMDB 相关设置集中在设置页的"目录数据"面板(界面模板见 app.min.js,中文文案见 lang/zh.js),常用项包括:

设置项 说明
TMDB 语言 控制目录、简介的展示语言
TMDB 海报分辨率 对应请求图片时的尺寸参数
仅显示已发行 隐藏还在影院上映、未首播的影片
代理 TMDB / 自动启用代理 数据与图片走代理,失败自动开启
Api / Image 代理地址 分别填写数据接口和海报图的代理前缀

新手建议的 3 个调优步骤:

  1. 先把 TMDB 语言设为自己熟悉的语言(如中文地区可选对应语言代码);
  2. 电视网络访问 api.themoviedb.org 不畅时,打开"代理 TMDB"并让"自动启用代理"保持开启;
  3. 缓存数据过多占用存储时,在设置里使用"清除缓存"(文案见 lang/zh.js),基础设置会被保留。

小结:Lampa 数据层设计可借鉴的 3 点

  1. 单一出口封装:所有 TMDB 调用收口在一个模块里,代理、语言、密钥全部集中处理,业务代码不感知 URL 细节;
  2. 分级 TTL 缓存:按数据"易变程度"分配 1 天~7 天不等的缓存时长,详情页最长效、列表次之、日期类最短;
  3. 失败自愈:海报镜像池自动封禁坏节点、请求去重合并并发、网络错误时宁可展示也不空白。

这套"轻客户端 + 远端目录 + 多层缓存"的架构,正是 Lampa 在电视这种弱交互设备上依然流畅的关键。如果你想深入源码,核心入口都在 app.min.js,配合 index.html 的页面骨架阅读效率最高。

登录后查看全文
lampa