DecoTV

DecoTV

DecoTV 是一个开箱即用的、跨平台的影视聚合播放器。它基于 Next.js 16 + Tailwind CSS 4 + TypeScript 5 构建，支持多资源搜索、在线播放、收藏同步、播放记录、云端存储，让你可以随时随地畅享海量免费影视内容。支持本地无数据库模式、CMS 全量代理、隐私纵深防御等企业级特性。

项目展示

⚠️ 重要提醒

注意：部署后项目为空壳项目，无内置播放源和直播源，需要自行收集配置。
免责声明：请不要在 B 站、小红书、微信公众号、抖音、今日头条或其他中国大陆社交平台发布视频或文章宣传本项目，不授权任何"科技周刊/月刊"类项目或站点收录本项目。

✨ 功能特性

• 多源聚合搜索：一次搜索立刻返回全源结果。
• 丰富详情页：支持剧集列表、演员、年份、简介等完整信息展示。
• ▶️ 流畅在线播放：集成 HLS.js & ArtPlayer。
• 多音轨切换：当视频存在 2 条及以上音轨时，播放器控制栏会显示“音轨”按钮，可在中文配音 / English 等音轨间切换；单音轨会自动隐藏按钮，界面保持简洁。
• ️ 网页投屏（Google Cast）：支持在网页端直接发起投屏，并提供 iOS 设备兼容提示。
• ❤️ 收藏 + 继续观看：支持 Kvrocks/Redis/Upstash 存储，多端同步进度。
• 用户注册系统：支持用户自助注册（可选），带图形验证码防机器人。
• PWA：离线缓存、安装到桌面/主屏，移动端原生体验。
• 响应式布局：桌面侧边栏 + 移动底部导航，自适应各种屏幕尺寸。
• 弹幕功能：集成弹弹play开放平台，Vercel 部署默认可通过公共中继加载官方弹幕，并支持 TMDB 精确匹配、手动匹配与第三方自定义节点。
• ☁️ PanSou 网盘搜索：支持对接远程 PanSou 节点，提供聚合网盘搜索能力，并可在后台灵活配置节点与鉴权。
• ⬇️ 视频资源下载能力：支持浏览器分片下载与服务端 FFmpeg 转存下载，增强任务管理、重试与超时处理。
• 灵活直播体验：支持多直播源配置、分页切换优化与 m3u8/flv/mp4 自动识别处理。
• 豆瓣信息增强：支持标题反查豆瓣 ID、并行抓取与图片代理，详情页信息更完整。
• ️ TMDB 元数据增强：支持与豆瓣互补的 TMDB 元数据查询，中文优先、英文回退，可为详情页和私人影库补充更稳定的海报、背景图与简介。
• ️ 私人影库：支持接入 OpenList / 小雅 Alist / Emby / Jellyfin，在“我的影库”中浏览和播放自有媒体资源，并通过服务端代理保护流地址与鉴权信息。
• 智能去广告：自动跳过视频中的切片广告（实验性）。
• 本地无数据库模式：无需 Redis，自动降级为浏览器 localStorage 存储。
• CMS 全量代理：根绝 Mixed Content 和 CORS 问题，支持任意第三方源。
• ️ 隐私纵深防御：双重熔断机制，从配置到代理层隔离成人内容。

注意：部署后项目为空壳项目，无内置播放源和直播源，需要自行收集

请不要在 B 站、小红书、微信公众号、抖音、今日头条或其他中国大陆社交平台发布视频或文章宣传本项目，不授权任何“科技周刊/月刊”类项目或站点收录本项目。

目录

• 项目展示
• ✨ 功能特性
• 技术栈
• 部署
• ⚙️ 配置文件
• 自动更新
• 环境变量
• ⬇️ 下载功能使用指南
• Roadmap
• AndroidTV 使用
• 安全与隐私提醒
• License
• 致谢
• Star History
• 赞赏支持

技术栈

部署

本项目仅支持 Docker 或其他基于 Docker 的平台 部署。

OpenWrt 部署

如果你计划运行在 OpenWrt（软路由 / ARM 盒子 / 树莓派等）设备上，参阅完整指南：

OpenWrt 部署指南

快速拉取预构建镜像：

docker pull ghcr.io/decohererk/decotv:latest

若需在外部主机自行构建后再导入至 OpenWrt，请参考指南中的 “获取或构建镜像” 与 “导出并传输” 步骤。

Docker 镜像标签

DecoTV 提供以下 Docker 镜像标签：

推荐使用方式：

# 方式1：使用 latest 标签（自动获取最新更新）
docker pull ghcr.io/decohererk/decotv:latest

# 方式2：使用特定版本号（生产环境推荐）
docker pull ghcr.io/decohererk/decotv:v1.0.0

# 方式3：回滚到旧版本
docker pull ghcr.io/decohererk/decotv:v0.9.0

版本号标签优势：

• ✅ 清楚知道运行的版本，方便对比 GitHub 最新版
• ✅ 可以固定版本号，避免意外更新影响生产环境
• ✅ 支持版本回滚，遇到问题可快速恢复到旧版本
• ✅ 便于团队协作时统一环境版本

注意：使用 latest 标签时，重启容器不会自动拉取新镜像，需要手动执行 docker pull 才能获取更新。使用版本号标签可以明确控制何时更新。

访问协议与反向代理

DecoTV 支持直接通过 Docker 端口映射在局域网 HTTP 地址访问，例如 http://192.168.1.10:3000。这种场景下登录 Cookie 不会设置 Secure 属性，浏览器可以正常保存认证状态。

公网部署强烈建议使用 HTTPS。若前面有 Nginx/OpenResty 等反向代理，请确保把外部访问协议传给 DecoTV：

proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

DecoTV 会根据请求 URL、X-Forwarded-Proto、X-Forwarded-Host 或标准 Forwarded 头判断实际协议和外部访问域名。使用 https://域名:非443端口 反代时，务必传递带端口的 $http_host，否则浏览器后续请求 m3u8 代理地址时会丢端口。HTTPS 访问会设置 Secure Cookie；HTTP 局域网直连和 HTTP 反代不会设置 Secure Cookie。不要仅依赖容器内的 NODE_ENV=production 判断访问协议。

Kvrocks 存储（推荐）

…

Redis 存储（有一定的丢数据风险）

…

Upstash 存储

1. 在 upstash 注册账号并新建一个 Redis 实例，名称任意。
2. 复制新数据库的 HTTPS ENDPOINT 和 TOKEN
3. 使用如下 docker compose

services:
  decotv-core:
    image: ghcr.io/decohererk/decotv:latest # 或使用 :v1.0.0 固定版本
    container_name: decotv-core
    restart: on-failure
    ports:
      - '3000:3000'
    environment:
      - USERNAME=admin
      - PASSWORD=admin_password
      - NEXT_PUBLIC_STORAGE_TYPE=upstash
      - UPSTASH_URL=上面 https 开头的 HTTPS ENDPOINT
      - UPSTASH_TOKEN=上面的 TOKEN

本地无数据库模式（最简部署）

如果你只是想快速体验或单机使用，不需要多端同步功能，可以使用本地存储模式。此模式下数据保存在浏览器的 localStorage 中，无需任何外部数据库。

Docker Run（最简单）

docker run -d \
  --name decotv \
  -p 3000:3000 \
  -v decotv-downloads:/app/.cache/ffmpeg-downloads \
  -e PASSWORD=你的管理密码 \
  ghcr.io/decohererk/decotv:latest

Docker Compose

services:
  decotv:
    image: ghcr.io/decohererk/decotv:latest
    container_name: decotv
    restart: unless-stopped
    ports:
      - '3000:3000'
    environment:
      - PASSWORD=你的管理密码
    volumes:
      - decotv-downloads:/app/.cache/ffmpeg-downloads
volumes:
  decotv-downloads:

重要说明

免登录家庭模式

默认仍为 NEXT_PUBLIC_AUTH_MODE=password，需要登录后使用。家庭局域网、NAS、电视盒子、OpenWrt、飞牛 OS 等完全可信内网场景，可以显式开启免登录：

docker run -d \
  --name decotv \
  -p 3000:3000 \
  -e NEXT_PUBLIC_AUTH_MODE=public \
  -v decotv-downloads:/app/.cache/ffmpeg-downloads \
  ghcr.io/decohererk/decotv:latest

Docker Compose 示例：

services:
  decotv:
    image: ghcr.io/decohererk/decotv:latest
    container_name: decotv
    restart: unless-stopped
    ports:
      - '3000:3000'
    environment:
      - NEXT_PUBLIC_AUTH_MODE=public
    volumes:
      - decotv-downloads:/app/.cache/ffmpeg-downloads
volumes:
  decotv-downloads:

⚠️ NEXT_PUBLIC_AUTH_MODE=public 仅建议局域网、NAS、家庭内网、VPN、自用环境开启，不建议公网暴露。/admin 和 /api/admin/* 默认仍需要登录保护；只有同时设置 PUBLIC_ALLOW_ADMIN=true 才会免登录开放后台和后台 API，该开关风险极高，仅适合完全可信内网。

常见问题

Q: 登录成功后操作仍提示 401 Unauthorized？

这可能是以下原因：

1. 浏览器 Cookie 问题：尝试清除浏览器 Cookie 后重新登录
2. 残留数据库配置：确保没有设置 REDIS_URL、KV_REST_API_URL 等数据库变量
3. 反向代理协议头缺失：如果你通过 Nginx/OpenResty 等反向代理使用 HTTPS，确保正确配置 X-Forwarded-Proto $scheme，否则应用可能无法按外部访问协议设置 Cookie
4. 镜像未更新：latest 镜像重启不会自动拉取新版本，升级前需要先执行 docker pull ghcr.io/decohererk/decotv:latest

Q: 如何从本地模式迁移到数据库模式？

由于本地模式数据存储在浏览器中，无法直接迁移。建议：

1. 手动导出配置（复制配置文件内容）
2. 部署新的数据库模式实例
3. 在新实例中导入配置

⚙️ 配置文件

完成部署后为空壳应用，无播放源，需要站长在管理后台的配置文件设置中填写配置文件（后续会支持订阅）

配置文件示例如下：

{
  "cache_time": 7200,
  "api_site": {
    "dyttzy": {
      "api": "http://xxx.com/api.php/provide/vod",
      "name": "示例资源",
      "detail": "http://xxx.com"
    }
    // ...更多站点
  },
  "custom_category": [
    {
      "name": "华语",
      "type": "movie",
      "query": "华语"
    }
  ]
}

• cache_time：接口缓存时间（秒）。
• api_site：你可以增删或替换任何资源站，字段说明：
  • key：唯一标识，保持小写字母/数字。
  • api：资源站提供的 vod JSON API 根地址。
  • name：在人机界面中展示的名称。
  • detail：（可选）部分无法通过 API 获取剧集详情的站点，需要提供网页详情根 URL，用于爬取。
• custom_category：自定义分类配置，用于在导航中添加个性化的影视分类。以 type + query 作为唯一标识。支持以下字段：
  • name：分类显示名称（可选，如不提供则使用 query 作为显示名）
  • type：分类类型，支持 movie（电影）或 tv（电视剧）
  • query：搜索关键词，用于在豆瓣 API 中搜索相关内容

custom_category 支持的自定义分类已知如下：

• movie：热门、最新、经典、豆瓣高分、冷门佳片、华语、欧美、韩国、日本、动作、喜剧、爱情、科幻、悬疑、恐怖、治愈
• tv：热门、美剧、英剧、韩剧、日剧、国产剧、港剧、日本动画、综艺、纪录片

也可输入如 "哈利波特" 效果等同于豆瓣搜索

DecoTV 支持标准的苹果 CMS V10 API 格式。

自动更新

可借助 watchtower 自动更新镜像容器

dockge/komodo 等 docker compose UI 也有自动更新功能

环境变量

基础配置

存储配置

注意：Upstash 使用 REST API 连接，需要填写 UPSTASH_URL（HTTPS ENDPOINT）和 UPSTASH_TOKEN，不是传统的 Redis 连接字符串。

用户注册配置

注册需要先配置 redis、upstash 或 kvrocks 存储。部署后由站长在 /admin -> 用户配置 -> 公开注册 中直接控制开关和新用户默认用户组，无需为日常启停重新部署。