自建影视聚合播放器：LunaTV Docker 部署与播放源配置完整实战指南

【免费下载链接】LunaTV本项目采用 CC BY-NC-SA 协议，禁止任何商业化行为，任何衍生项目必须保留本项目地址并以相同协议开源项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTV

LunaTV 是一个基于 Next.js 14 构建的开源影视聚合播放器，支持多资源站聚合搜索、在线播放、收藏与播放记录跨端同步。本文带你在一台装有 Docker 的服务器上完成部署，并讲清楚启动之后最关键的播放源配置，10 分钟内你就能拥有一个可以正常看片、能记住进度的个人影视站。

部署后你得到什么：LunaTV 的七项主要能力

先花一分钟了解装好之后的使用体验，这样后面配置时就知道每个环节的意义。

LunaTV 首页会展示"继续观看"和热门内容推荐，配合分类导航快速定位片源；搜索结果来自你配置的全部资源站，一次输入即可跨站聚合。详情页提供剧集列表、演员、年份、简介等完整信息，播放端由 ArtPlayer 与 HLS.js 驱动，支持流媒体在浏览器里直接播放。收藏、播放记录存在服务端存储里，换设备登录也能接着上次的位置看。

其余能力包括：PWA 离线缓存与安装到桌面/主屏；桌面侧边栏加移动底部导航的响应式布局；实验性的切片广告自动跳过；以及一个常被忽略的直播模块，可以配置直播源和 EPG 节目单。v100.0.0 以上的版本还能配合移动端客户端 Selene 使用，数据完全同步；在 Android TV 上也可以把它当作 OrionTV 的后端，播放记录同样与网页端互通。

部署前准备：只需要 Docker 和一个空闲端口

LunaTV 官方仅支持 Docker 及基于 Docker 的平台部署，没有裸机 Node.js 的玩法，这省去了装依赖、编译源码的环节。

机器上需要安装 Docker 和 Docker Compose，并且能访问镜像仓库拉取镜像。资源方面，1GB 左右的内存和 10GB 磁盘就足够个人使用了。唯一必须让出来的是本机3000 端口——服务默认监听容器内的 3000 端口，compose 文件会把它映射到宿主机。如果你的 3000 已被占用，改一下映射的左边部分（比如8080:3000），之后用 8080 访问即可，容器内端口不用动。

三步完成部署：写一份 compose 文件就够

整个部署就是"写文件 → 启动 → 打开浏览器"三步。下面这份docker-compose.yml采用官方推荐的 Kvrocks 存储方案，两个服务、一个网络、一个数据卷，照抄后按需改两处密码即可：

services: moontv-core: 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: driver: bridge volumes: kvrocks-data:

几个字段的填写逻辑：moontv-core是应用本体，USERNAME/PASSWORD是登录管理后台用的站长账号，必填，密码务必换成强密码且不要公开分享实例地址；NEXT_PUBLIC_STORAGE_TYPE指定收藏与播放记录存放的存储后端，本例选了kvrocks；KVROCKS_URL指向同网络里的 Kvrocks 容器，主机名直接用服务名moontv-kvrocks，端口 6666 是 Kvrocks 的默认端口。Kvrocks 是 Redis 协议的兼容存储，apache/kvrocks是官方镜像，把数据目录/var/lib/kvrocks挂到命名卷kvrocks-data后，容器删了数据也不会丢。

在文件所在目录执行docker-compose up -d，等待镜像拉取和容器启动，浏览器打开http://localhost:3000（远程机器则换成对应 IP）就能看到登录页。

管理后台配置播放源：为什么装完的站点没有片源

这一点必须提前说明：部署完成后 LunaTV 是一个空壳，没有内置播放源和直播源，需要站长自己收集并填进后台，这也是全文最容易卡住的一步。

登录后台后进入"配置文件设置"（对应源码见 src/app/admin/page.tsx），LunaTV 接受标准苹果 CMS V10 格式的接口，把配置以 JSON 形式粘贴保存即可。这份配置由三部分组成：cache_time控制接口缓存秒数，填大一点可以减轻资源站压力；api_site是资源站列表，每站需要一个唯一标识 key、该站api.php/provide/vod的 JSON 接口地址、界面展示用的 name，个别站点 API 拿不到剧集详情时还要补detail指向其网页详情根地址；custom_category用于在导航栏加自定义分类，用type（movie 或 tv）加query（搜索关键词）作为标识，支持"华语""美剧""豆瓣高分"这类词，也可以直接写"哈利波特"实现类似豆瓣搜索的效果。

如果你的配置想复用到其他实例或客户端，还有一个订阅机制：把完整配置文件做 base58 编码后提供一个 HTTP 地址，就成为一个订阅链接，可在后台或 Helios 客户端中直接拉取。

存储后端怎么选：Kvrocks、Redis 还是 Upstash

收藏和播放记录存在哪里，由NEXT_PUBLIC_STORAGE_TYPE决定，三种选项各有取舍。

Kvrocks 是默认推荐项：性能好、配合命名卷可以可靠持久化，上文 compose 文件就是按它写的。Redis 兼容性好，但官方明确提示有丢数据风险——如果用redis方案，必须像 README 示例那样开启持久化并挂载/data卷，否则升级或重启后记录会清空。Upstash 则是托管在云端的 Redis，适合无服务器或不想自己维护数据库的场景，需要额外注册账号，把UPSTASH_URL和UPSTASH_TOKEN两个环境变量填进 core 服务即可，compose 里也就只剩一个容器。

无论选哪种，都建议养成备份习惯：Kvrocks 方案备份kvrocks-data卷里的内容即可；Redis 方案备份持久化目录。这是全系统里唯一会产生用户数据的地方。

可选调优：豆瓣代理与站点展示

基础跑通后，几个环境变量值得按需调整，它们都写在 core 服务的environment里。

豆瓣海报和详情数据默认由服务器直连豆瓣（direct），如果你的网络到豆瓣不稳，推荐改为社区 CDN 方案：NEXT_PUBLIC_DOUBAN_PROXY_TYPE=cmliussss-cdn-tencent与NEXT_PUBLIC_DOUBAN_IMAGE_PROXY_TYPE=cmliussss-cdn-tencent，让浏览器直接向带 CDN 加速的镜像请求数据，国内访问速度明显更稳。站点展示方面，NEXT_PUBLIC_SITE_NAME改站名，ANNOUNCEMENT改首页公告（默认是一段合规免责声明，建议保留），SITE_BASE填你的访问 URL。行为类选项还有NEXT_PUBLIC_SEARCH_MAX_PAGE（搜索可翻页数，默认 5）和NEXT_PUBLIC_FLUID_SEARCH（搜索流式输出，默认开启）。改完环境变量后重新docker-compose up -d让容器重建生效。

五项验证清单与日常更新方式

部署是否真正可用，按顺序检查五件事：能用http://localhost:3000打开登录页；用 compose 里的账号密码成功登录管理后台；保存配置后首页能加载出分类与推荐内容；搜索任意一部电影能返回聚合结果并点开详情页；最终能流畅播放且刷新后"继续观看"位置保留。五步全过，这套影视聚合播放器就算正式上线了。

日常维护只需要一条命令：docker-compose pull && docker-compose up -d，拉取新版镜像并重建容器，存储卷里的数据不受影响。最后再叮嘱两句安全上的事：实例只供个人使用，不要公开传播访问链接，避免他人滥用；账号密码保持强随机，若日后要长期运行，也可以固定一个版本标签代替latest，防止自动拉到不稳定的新版本。照这套流程走下来，从空服务器到能看片只需要一份 compose 文件和一段播放源配置，剩下的交给它自己同步记录就好。

【免费下载链接】LunaTV本项目采用 CC BY-NC-SA 协议，禁止任何商业化行为，任何衍生项目必须保留本项目地址并以相同协议开源项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTV