打造私人Netflix影库:冬瓜TV (DongguaTV) 一键部署全攻略
当你想要观看影视内容时,可能需要打开多个应用程序,在不同的平台间反复切换,其过程如同查看复杂的股票K线图一般繁琐。当你终于找到想看的资源,却常常遭遇播放卡顿,画面宛如PPT般不连贯。此时你或许会陷入沉思:自己缺少的或许并非某个平台的会员,而是一个能够整合所有资源的「聚合入口」。
正是在这样的需求背景下,冬瓜TV(DongguaTV)应运而生。它主打全网聚合搜索、多源聚合、实时线路测速、热门内容推荐、便捷的后台管理以及JSON持久化配置。与Plex、Jellyfin、Emby这类以管理和刮削本地媒体库为核心的系统不同,冬瓜TV的定位更侧重于成为一个「聚合检索中心」与「快速播放入口」。
用一句话概括其核心价值:旨在减少用户的折腾成本,实现搜索即得、点击即看的高效观影体验。
⚠️ 项目免责声明:冬瓜TV项目仅供学习与研究之用,请勿将其用于任何商业用途。因使用本项目而产生的任何法律问题与责任,需由使用者自行承担。我们始终倡导并鼓励大家支持正版影视内容。
此前,市面上也曾出现过功能类似的项目,例如「MoonTV」、「MoonTV PLUS」、「LibreTV」和「OmniBox」。相比之下,冬瓜TV虽然在功能模块数量上未必是最多的,但其在用户体验与界面设计层面,可以说是当前最为精致的一款。

冬瓜TV项目核心功能解析
完整项目地址为:Minerchu/dongguaTV3。
冬瓜TV是一个基于Node.js与Vue 3技术栈构建的视频聚合平台。它深度集成了众多视频站点的API接口,提供了智能搜索、资源聚合、实时测速等一站式功能,致力于为用户打造专属的私人Netflix体验。项目核心支持「TMDb智能元数据刮削」、「全网资源聚合」与「极速流畅播放」。
🎬 双引擎驱动数据获取
TMDb (The Movie Database):作为高质量的影视元数据提供方,为影片和剧集提供详尽的海报、背景图、评分、剧情简介以及演职员表等信息。
CMS聚合源 (Maccms):项目集成了超过48个第三方站点的API接口。系统能够自动对全网资源进行实时测速,并智能过滤掉已失效的源,从源头上保障播放的流畅性。
🔍 智能化搜索与聚合机制
实时流式搜索 (SSE):采用Server-Sent Events技术实现搜索结果的流式返回。搜索结果边获取边显示,给予用户即时反馈,无需等待所有源全部响应完毕。
自动分组与实时合并:系统会将同一部影视作品的不同播放线路自动聚合展示。新搜索到的资源会实时合并到已有的结果卡片中,卡片右上角的资源数量会动态更新。
SQLite永久缓存:内置高性能的SQLite数据库作为缓存层,支持无限存储,读写速度极快,能够实现热搜词条的秒级响应。
📺 沉浸式播放与观看体验
影院模式界面:全新设计的播放详情页采用暗色系沉浸式布局,优化了视觉焦点,并支持以网格形式选择剧集。
智能线路测速:支持用户端直连测速与服务器端代理测速两种模式,能够更真实地反映视频源的实际可用性与速度。
自动故障转移:当当前播放线路失败时,系统会自动切换到列表中的下一个可用线路,全程无需用户手动干预。
投屏功能支持:集成了DLNA与AirPlay本地投屏协议(具体支持程度取决于用户浏览器)。
🌏 针对大陆用户的深度优化
智能IP双重检测:采用Cloudflare Trace与ipapi.co双重检测机制,IP地理位置判断准确率高且不受API速率限制。当检测到大陆IP时,会自动切换至TMDB反代访问模式。
核心资源本地化:Vue、Bootstrap、DPlayer等核心前端依赖库均采用本地化部署,彻底解决了因公共CDN被劫持或加载缓慢导致页面打开慢的问题,实现秒开体验。
一键交互式安装脚本:支持通过命令行交互方式,便捷地配置API Key、反代地址及运行端口。
📱 全面的多终端兼容支持
Android TV / 电视盒子:提供了专属的APK安装包,完美适配电视遥控器的操作逻辑,并支持在Android TV桌面(Leanback Launcher)直接启动。
移动端App体验:基于现代Web技术进行封装,在移动设备上可获得接近原生应用的交互体验。
PWA渐进式网页应用:支持将网页应用添加到设备主屏幕,实现即点即用,无需通过浏览器多次访问。
🔒 安全与访问权限控制
全局访问密码:支持为整个应用设置全局访问密码,并允许用户选择记住登录状态(最长可达1年),在安全与便捷之间取得平衡。
远程配置加载:支持从指定的远程URL地址加载
db.json配置文件,便于在多设备、多站点环境下进行统一的资源管理。
部署前准备:API密钥与配置文件
本文将以威联通(QNAP)NAS为例,详细演示通过Docker Compose部署冬瓜TV的完整流程。
首先,你需要获取一个TMDb API密钥。访问TMDb官网注册账号后,在账户设置中申请API。如下图所示,找到页面底部的「API 密钥」,复制并妥善保存备用。

接下来,在NAS上创建用于部署的专用目录。威联通的Docker相关路径通常为/share/Container/,我们可以在其下创建donggua文件夹。请在该目录中预先创建两个空文件:db.json 和 cache.db,创建后的目录结构参考下图。

其中,db.json文件需要你自行配置视频采集源(API)。其内容需遵循以下JSON格式:
{
"sites": [
{
"key": "unique_key1", // 唯一标识符(建议使用英文字母,且不可重复)
"name": "站点名称1", // 将在前端界面显示的名称
"api": "https://...", // Maccms V10/JSON 格式的接口地址
"active": true // 是否启用该站点 (true/false)
},
{
"key": "unique_key2", // 唯一标识符
"name": "站点名称2", // 显示名称
"api": "https://...", // API地址
"active": true // 启用状态
}
]
}
为方便初学者快速上手,我们已整理一份现成的源地址列表。如果你有自己的稳定视频源,也可以据此格式自行修改与添加。请注意,公共源的可用性与稳定性无法得到长期保证,且通常不会进行持续的维护更新。
详细部署步骤:Docker Compose实战
完成上述准备工作后,即可开始部署。以下为docker-compose.yml部署代码示例,请根据你的实际环境进行调整。
services:
donggua-tv:
image: ghcr.io/ednovas/dongguatv:latest
container_name: donggua-tv
ports:
- "3000:3000" # 冒号左侧的端口可根据需要更改
environment:
- TMDB_API_KEY=your_api_key_here # 请替换为你在TMDb获取的API密钥
- ACCESS_PASSWORD=qnap1234 # 设置你的访问密码,请自行更改
- CACHE_TYPE=sqlite
# - TMDB_PROXY_URL=https://tmdb-proxy.your-name.workers.dev # 仅在无法直连TMDb时需要取消注释并配置
volumes:
- /share/Container/donggua/db.json:/app/db.json # 挂载采集源配置文件
- /share/Container/donggua/cache.db:/app/cache.db # 挂载SQLite数据库文件
- /share/Container/donggua/cache/images:/app/public/cache/images # 挂载图片缓存目录
restart: always
关于环境变量TMDB_PROXY_URL,你需要参考项目官方文档中提供的两种反代搭建方法。请注意,只有在你所处的网络环境确实无法直接访问TMDb官方网站时,才需要进行此项配置。

在威联通NAS上,打开Container Station应用。点击“创建”按钮,选择“创建应用程序”,将上述docker-compose.yml文件的内容粘贴到编辑框中。

界面与功能初体验
按照前述步骤成功部署后,你可以在浏览器中输入 你的NAS_IP地址:3000 来访问冬瓜TV服务界面。
首先,输入之前在部署代码中设定的ACCESS_PASSWORD(例如qnap1234)进行登录。

登录成功后的初始主界面如下图所示。位于搜索框下方的分类导航栏,点击后可快速跳转到对应的影视分类区域。

首次加载时,系统需要从TMDb获取并缓存大量的海报与背景图片。通过容器日志可以看到大量图片加载请求,此时请耐心等待一段时间。

短暂等待后,所有元数据与图片便会加载完成,界面将完整呈现。

现在,你可以尝试搜索任意一部感兴趣的影视作品,体验其聚合搜索与播放功能。

结语
总体而言,冬瓜TV提供了一套非常完善且体验上乘的聚合观影解决方案。除了需要预先处理好TMDb的访问问题(部分地区可能需要配置反代),其整体部署与使用过程都相当顺畅。对于希望构建个人影音中心、追求一站式观影体验的用户而言,这是一个非常值得尝试的项目。