[JS/TS] 冬瓜TV MAX：基于Node.js与Vue3的私有流媒体聚合播放器Docker部署教程

冬瓜TV MAX (DongguaTV Enhanced Edition) 是一款在原始冬瓜TV项目基础上进行全面重构与升级的现代流媒体聚合播放应用。与MoonTV、OmniBox等项目类似，其核心功能均基于Maccms V10实现视频内容的聚合、搜索与播放。

项目基于现代化的 Node.js 后端与 Vue 3 前端构建，旨在为用户打造高质量的私有影视观看体验。

主要特点

• 双引擎数据驱动：集成TMDb提供高质量的影视元数据（如海报、简介），同时支持接入多个Maccms数据源，自动测速并过滤失效源。
• 智能搜索与聚合：采用实时流式搜索技术，结果边搜边显。自动合并同一影片的不同线路，并利用高性能SQLite数据库实现热搜词秒级响应与无限缓存。
• 沉浸式播放体验：提供影院模式与刷新设计的详情页，支持剧集选择。具备智能线路测速与故障转移功能，保障连续观看。
• 多端与访问控制：支持Android TV及移动端，提供近原生体验。可设置全局访问密码，并支持远程加载配置文件，便于管理。
• 网络优化：针对大陆用户进行智能IP检测，并可配置TMDB反代地址，确保元数据稳定获取。

安装与部署

本文以在群晖NAS上使用Docker部署为例。当前latest镜像版本对应为1.0.17。

准备工作

1. 配置采集源文件

首先创建必要的目录和文件：

# 新建文件夹及子目录
mkdir -p /volume1/docker/dongguatv/cache
# 进入目录
cd /volume1/docker/dongguatv
# 创建所需文件，防止挂载为目录
touch db.json cache.db

编辑db.json文件，用于存放Maccms数据源，格式如下（注意：实际文件中请勿包含注释）：

{
  "sites": [
    {
      "key": "site1_key",
      "name": "站点名称1",
      "api": "https://your-maccms-site.com/api.php/provide/vod/",
      "active": true
    },
    {
      "key": "site2_key",
      "name": "站点名称2",
      "api": "https://another-maccms-site.com/api.php/provide/vod/",
      "active": true
    }
  ]
}

2. 获取TMDb API Key

应用依赖TMDb获取影视元数据，需提前申请API Key：

1. 访问 TMDb官网 注册并登录。
2. 进入 API设置页面，点击创建新API。
3. 应用类型选择 “Developer”，简单填写申请理由。
4. 申请通过后，复制生成的 “API Key (v3 auth)” 备用。

3. (可选) 配置TMDb反代

若网络无法直连TMDb，需配置反代才能正常显示海报等信息。可参考项目官方文档使用Cloudflare Workers等方式搭建。

通过Docker CLI部署

熟悉命令行的用户可使用以下指令快速启动容器：

docker run -d \
   --restart unless-stopped \
   --name donggua-tv \
   -p 3778:3000 \
   -v $(pwd)/db.json:/app/db.json \
   -v $(pwd)/cache.db:/app/cache.db \
   -v $(pwd)/cache:/app/public/cache \
   -e TMDB_API_KEY=你的TMDb_API_密钥 \
   -e TMDB_PROXY_URL=https://你的反代地址.workers.dev \
   -e ACCESS_PASSWORD=你的访问密码 \
   -e CACHE_TYPE=sqlite \
   ghcr.io/ednovas/dongguatv:latest

通过 Docker Compose 部署

更推荐使用docker-compose.yml进行管理，内容如下：

version: '3'
services:
  donggua-tv:
    image: ghcr.io/ednovas/dongguatv:latest
    container_name: donggua-tv
    restart: unless-stopped
    ports:
      - "3778:3000"
    volumes:
      - ./db.json:/app/db.json
      - ./cache.db:/app/cache.db
      - ./cache:/app/public/cache
    environment:
      - TMDB_API_KEY=你的TMDb_API_密钥
      - TMDB_PROXY_URL=https://你的反代地址.workers.dev
      - ACCESS_PASSWORD=你的访问密码
      - CACHE_TYPE=sqlite

将文件保存后，在所在目录执行以下命令启动服务：

docker-compose up -d

运行与访问

部署完成后，在浏览器中访问 http://你的群晖IP:3778 即可看到登录界面，输入预设的ACCESS_PASSWORD密码进入系统。

首次加载时，应用会通过TMDb API获取影视元数据。若网络连接不畅或反代设置不当，可能导致部分海报加载缓慢或失败，这通常会在日志中显示为超时错误，可尝试刷新页面。此问题一般不影响核心的搜索与视频播放功能。

对于希望使用安卓客户端的用户，需要参照项目仓库的说明自行通过GitHub Actions进行应用编译。