LunaTV 保姆级部署教程：用 Docker 从零搭建影视聚合播放器
【免费下载链接】LunaTV本项目采用 CC BY-NC-SA 协议，禁止任何商业化行为，任何衍生项目必须保留本项目地址并以相同协议开源项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTV
追一部剧要跳好几个网站、找到的资源第二天就失效、手机上看到一半换到电视又从头开始——如果你被这些情况折腾过，正缺的就是一个能自己部署的影视聚合播放器。LunaTV 是一个基于 Next.js 的开源项目，把多个资源站的结果聚合到同一个搜索框里，支持在线播放、收藏同步和观看进度跨设备恢复，整体只靠 Docker 就能跑起来。下面这份实操流程会带着你把服务启动、后台配源、完整看片走一遍，全程不需要碰代码。
开工前的体检：环境、内存和存储选型
先花一分钟确认两件事：
- 机器上装好了 Docker 和 Docker Compose，执行
docker -v和docker compose version能正常输出版本号即可； - 内存建议 1GB 起步，Linux 环境下表现最稳。
存储后端怎么选：先给结论
LunaTV 的收藏和播放进度都存在一个键值数据库里，有三种可选。推荐直接上 Kvrocks：它和 Redis 协议兼容（可以理解为 Redis 的"换芯版"），自带完善的数据持久化，重启、升级后进度不会丢。
| 选项 | 优点 | 短板 |
|---|---|---|
| Kvrocks（推荐） | 持久化开箱即用，镜像直接拉，数据最稳 | 多起一个容器 |
| Redis | 熟悉的人多，生态成熟 | 持久化要自己开，忘了配升级重启就可能丢数据 |
| Upstash | 不用自己维护存储 | 依赖云服务账号，数据不在自己手里 |
三者差异只体现在 compose 里两个环境变量上。本文按 Kvrocks 方案走。
一份 compose 把服务跑起来
新建一个目录，放入docker-compose.yml，关键行都做了注释：
services: moontv-core: # LunaTV 主服务 image: ghcr.io/moontechlab/lunatv:latest container_name: moontv-core restart: on-failure ports: - "3000:3000" # 浏览器访问用的端口 environment: - USERNAME=admin # 站长账号，按需修改 - PASSWORD=换成你的强密码 # 站长密码，必填 - NEXT_PUBLIC_STORAGE_TYPE=kvrocks # 指定存储后端 - KVROCKS_URL=redis://moontv-kvrocks:6666 networks: [moontv-network] depends_on: [moontv-kvrocks] moontv-kvrocks: # 存储容器 image: apache/kvrocks container_name: moontv-kvrocks restart: unless-stopped volumes: - kvrocks-data:/var/lib/kvrocks # 数据落到卷里，容器重建不丢 networks: [moontv-network] networks: moontv-network: volumes: kvrocks-data:在配置目录执行docker compose up -d，Compose 会先拉取两个镜像，再按依赖顺序逐个把容器拉起来；首次拉取镜像可能要一两分钟，耐心等它跑完。
执行docker compose ps，看到两个服务都处于 Up 状态，浏览器打开http://localhost:3000应该能看到登录页，到这里底座就算搭好了。
豆瓣数据加载不出来？加两行代理变量
影片海报、评分这类豆瓣数据默认由服务器直连获取，如果加载慢或失败，给主服务的environment里补上这两行，再docker compose up -d重建一次即可：
- NEXT_PUBLIC_DOUBAN_PROXY_TYPE=cmliussss-cdn-tencent - NEXT_PUBLIC_DOUBAN_IMAGE_PROXY_TYPE=cmliussss-cdn-tencent登录管理后台：给空壳装上内容
很多教程会在这里省略掉最要紧的一步：LunaTV 部署完是个空壳，不内置任何播放源，得自己进后台把源接进来。
用刚才设置好的账号密码登录管理后台，进入配置文件设置，粘贴一段符合苹果 CMS V10 API 格式的配置就能生效。核心是api_site字段，每个源站给一个api（该站的 vod JSON 接口地址）和一个name（前端展示名）：
{ "cache_time": 7200, "api_site": { "example": { "api": "http://你的源站/api.php/provide/vod", "name": "示例源" } } }cache_time是接口缓存时长（秒），源站接口慢时调大一点能明显减轻压力；- 配置支持多站点并存，随时增删替换；
- 多设备想保持同一套源：把整份配置做 base58 编码后挂成 http 服务，链接填进后台的订阅栏即可，改一处全部生效。
保存后刷新前端，站点就不再是空的了。
走一遍完整看片动线：首页、筛选、换源播放
打开首页，第一个模块就是"继续观看"，卡片上直接标着播放进度和集数，点开就能从断点接着看；下方的"热门电影"则是豆瓣维度的热门推荐，不用主动找就有内容可看。
点进电影分类页，顶部是两组筛选器："分类"对应热门、最新、豆瓣高分、冷门佳片这类榜单，"地区"覆盖华语、欧美、韩日。两个维度叠着用，找片基本两三下就能锁到目标。
选一部点进播放页，左侧是播放器，右侧栏在"选集"和"换源"两个标签间切换。同一部剧挂着多个来源，每个来源都标注了带宽、分辨率和集数——哪个卡切哪个，不用退出页面。
站点整体是响应式布局，手机上浏览器长按"添加到主屏"就能当 PWA 用；移动端想更顺手，还可以配合 Selene 客户端，播放记录和网页端完全同步。
上线前验收：6 项检查清单
逐条过一遍，全勾上再算部署完成：
- 浏览器打开
http://localhost:3000，登录页正常加载 - 用自设的 USERNAME / PASSWORD 能登入管理后台
- 后台保存的播放源在搜索中有结果返回
- 播放起播、选集切换、换源都正常
- 看几分钟后回到首页，"继续观看"出现该条目（证明存储写入了）
- 执行
docker compose restart后，收藏和进度原样保留
常见问题排查：问题、原因与处理
| 问题 | 可能原因 | 处理方式 |
|---|---|---|
| 3000 端口起不来 | 别的程序占着端口 | 把端口映射改成3001:3000之类，重新 up |
| 页面能开，海报和评分缺失 | 豆瓣直连被限流 | 补上两行豆瓣代理变量并重建容器 |
| 源配好了，搜索却是空的 | 接口地址写错或源站本身挂了 | 先验证接口可达性；确认是苹果 CMS V10 的 JSON 接口 |
| 重启后进度没了 | 用了 Redis 但没开持久化 | 换 Kvrocks 方案，或给 Redis 挂数据卷 |
| 主服务反复重启、连不上存储 | 连接串里主机名写错 | 容器网络内要用服务名：redis://moontv-kvrocks:6666 |
到这里，属于你自己的影视中心已经能看、能搜、能续播了。下一步想折腾的话，方向不少：用 watchtower 做镜像自动更新、在配置里写custom_category定制自己的分类入口，或者接上 Android TV 端让客厅也用上同一套片库。
【免费下载链接】LunaTV本项目采用 CC BY-NC-SA 协议，禁止任何商业化行为，任何衍生项目必须保留本项目地址并以相同协议开源项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTV
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
