打造私人Netflix影库：冬瓜TV (DongguaTV) 一键部署全攻略

April 4, 2026

当你想要观看影视内容时，可能需要打开多个应用程序，在不同的平台间反复切换，其过程如同查看复杂的股票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