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

🛠 技术栈

分类	主要依赖
前端框架	Next.js 16 · App Router · Turbopack
UI & 样式	Tailwind CSS 4
语言	TypeScript 5
播放器	ArtPlayer · HLS.js
代码质量	ESLint 9 · Prettier 3 · Jest 29
部署	Docker

🚀 部署

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

🧩 OpenWrt 部署

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

👉 OpenWrt 部署指南

快速拉取预构建镜像：

docker pull ghcr.io/decohererk/decotv:latest

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

📦 Docker 镜像标签

DecoTV 提供以下 Docker 镜像标签：

标签	说明	使用场景
`latest`	最新构建版本	总是使用最新代码，包含所有小更新
`v1.0.0`	特定版本号	固定版本部署，便于版本管理和回滚

推荐使用方式：

# 方式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 存储（推荐）

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=kvrocks
      - KVROCKS_URL=redis://decotv-kvrocks:6666
    networks:
      - decotv-network
    depends_on:
      - decotv-kvrocks
  decotv-kvrocks:
    image: apache/kvrocks
    container_name: decotv-kvrocks
    restart: unless-stopped
    volumes:
      - kvrocks-data:/var/lib/kvrocks
    networks:
      - decotv-network
networks:
  decotv-network:
    driver: bridge
volumes:
  kvrocks-data:

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

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=redis
      - REDIS_URL=redis://decotv-redis:6379
    networks:
      - decotv-network
    depends_on:
      - decotv-redis
  decotv-redis:
    image: redis:alpine
    container_name: decotv-redis
    restart: unless-stopped
    networks:
      - decotv-network
    # 请开启持久化，否则升级/重启后数据丢失
    volumes:
      - ./data:/data
networks:
  decotv-network:
    driver: bridge

Upstash 存储

在 upstash 注册账号并新建一个 Redis 实例，名称任意。
复制新数据库的 HTTPS ENDPOINT 和 TOKEN
使用如下 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:

重要说明

项目	说明
✅ 必需配置	`PASSWORD` - 管理员登录密码
❌ 不需要	`USERNAME`、`NEXT_PUBLIC_STORAGE_TYPE`、任何数据库连接变量
❌ 不需要	`AUTH_SECRET`、`AUTH_URL`（这些是其他认证框架的配置，DecoTV 不使用）
⚠️ 数据存储	所有配置保存在浏览器 localStorage，清除浏览器数据会丢失配置
⚠️ 多端同步	不支持，每个浏览器独立存储
⬇️ 下载缓存	建议挂载 `/app/.cache/ffmpeg-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？

这可能是以下原因：

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

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

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

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

⚙️ 配置文件

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

配置文件示例如下：

{
  "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 也有自动更新功能

🌍 环境变量

基础配置

变量	说明	可选值	默认值
USERNAME	管理员账号	任意字符串	无默认，数据库模式必填，本地模式可省略
PASSWORD	管理员密码	任意字符串	无默认，必填
NEXT_PUBLIC_AUTH_MODE	访问模式	password、public	password
PUBLIC_ALLOW_ADMIN	public 模式下是否开放后台	true/false	false
SITE_BASE	站点 URL	形如 https://example.com	空
NEXT_PUBLIC_SITE_NAME	站点名称	任意字符串	DecoTV
ANNOUNCEMENT	站点公告	任意字符串	本网站仅提供影视信息搜索服务，所有内容均来自第三方网站。本站不存储任何视频资源，不对任何内容的准确性、合法性、完整性负责。

存储配置

变量	说明	可选值	默认值	备注
NEXT_PUBLIC_STORAGE_TYPE	存储类型	localstorage、redis、kvrocks、upstash	localstorage	不填则默认本地模式，数据存浏览器中
KVROCKS_URL	Kvrocks 数据库连接地址	redis://host:port	空	当 STORAGE_TYPE=kvrocks 时必填
REDIS_URL	Redis 数据库连接地址	redis://host:port	空	当 STORAGE_TYPE=redis 时必填
UPSTASH_URL	Upstash Redis REST URL	https://xxx.upstash.io	空	当 STORAGE_TYPE=upstash 时必填
UPSTASH_TOKEN	Upstash Redis REST 令牌	AUxxxx...	空	当 STORAGE_TYPE=upstash 时必填

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

用户注册配置

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

变量	说明	可选值	默认值	备注
NEXT_PUBLIC_ENABLE_REGISTRATION	旧配置迁移时的初始注册状态	true/false	false	后续以管理面板保存的设置为准
DEFAULT_REGISTRATION_GROUP	旧配置迁移时的初始默认用户组	用户组名称	空	后续在管理面板选择已创建的用户组

安全提示：公开注册默认关闭；不设置默认用户组时，新账号默认可使用全部可用视频源。详见用户注册功能说明

高级配置

变量	说明	可选值	默认值	备注
NEXT_PUBLIC_SEARCH_MAX_PAGE	搜索接口可拉取的最大页数	1-50	5	数值越大越慢
NEXT_PUBLIC_DOUBAN_PROXY_TYPE	豆瓣数据源请求方式	见下方说明	auto	-
NEXT_PUBLIC_DOUBAN_PROXY	自定义豆瓣数据代理 URL	URL prefix	空	custom 模式使用
NEXT_PUBLIC_DOUBAN_IMAGE_PROXY_TYPE	豆瓣图片代理类型	见下方说明	auto	-
NEXT_PUBLIC_DOUBAN_IMAGE_PROXY	自定义豆瓣图片代理 URL	URL prefix	空	custom 模式使用
NEXT_PUBLIC_DISABLE_YELLOW_FILTER	关闭色情内容过滤	true/false	false	不建议开启
NEXT_PUBLIC_FLUID_SEARCH	是否开启搜索接口流式输出	true/false	true	-

NEXT_PUBLIC_DOUBAN_PROXY_TYPE 可选值

值	说明
auto	智能自动（默认），服务端按成功率和延迟在多个 provider 间自动降级
direct	服务器直接请求豆瓣源站
server	兼容值，等同于服务端智能代理
cors-proxy-zwei	服务端通过 Zwei 提供的 CORS Proxy 请求豆瓣数据
cmliussss-cdn-tencent	服务端通过 CMLiussss 提供的腾讯云 CDN 加速请求豆瓣数据
cmliussss-cdn-ali	服务端通过 CMLiussss 提供的阿里云 CDN 加速请求豆瓣数据
custom	使用自定义代理（需配置 NEXT_PUBLIC_DOUBAN_PROXY）

NEXT_PUBLIC_DOUBAN_IMAGE_PROXY_TYPE 可选值

值	说明
auto	智能自动（默认），按候选链路逐级重试
direct	浏览器直接请求豆瓣图片域名
server	服务器代理请求豆瓣图片
img3	使用豆瓣官方精品 CDN（阿里云）
cmliussss-cdn-tencent	使用 CMLiussss 提供的腾讯云 CDN
cmliussss-cdn-ali	使用 CMLiussss 提供的阿里云 CDN
custom	使用自定义代理（需配置 NEXT_PUBLIC_DOUBAN_IMAGE_PROXY）

auto 模式下，豆瓣数据请求统一走服务端 /api/douban/*：优先使用最近成功且延迟较低的 provider，单个 provider 超时、403/429/5xx、返回 HTML 或非 JSON 时，会记录失败原因并短期负缓存，然后自动尝试下一个 provider。API 成功响应会带 X-DecoTV-Douban-Provider 与 X-DecoTV-Douban-Duration，失败响应会带 providerAttempts 便于排查。

豆瓣封面图片在浏览器端按候选链路重试：用户选择的代理 → 上次 auto 成功节点 → img3.doubanio.com → CMLiussss 阿里云 CDN → CMLiussss 腾讯云 CDN → /api/image-proxy 服务器代理 → 豆瓣原图直连 → poster-fallback.svg。本地设置或后台配置变更后会触发 doubanProxyChanged，只清理豆瓣相关缓存。

弹幕功能配置

DecoTV 接入弹弹play开放平台提供的弹幕库。按照开放平台文档，应用取得的 AppId 与 AppSecret 需要妥善保管且不得泄露给他人。为避免将共享凭证写入公开代码或镜像，项目提供服务端中继用于部分公开部署场景。

默认接入规则

部署方式	默认行为
Vercel 等非 Docker Web 部署	未配置自有凭证时，通过项目公共中继 `https://tv.katelya.eu.org` 加载弹弹play官方弹幕
官方 Docker 镜像	不自动接入项目公共中继；可使用后台第三方弹幕节点，或配置自行申请的弹弹play凭证
已配置 `DANDANPLAY_APP_*` 的部署	优先在本部署服务端直连弹弹play开放平台
后台启用了第三方自定义弹幕节点	优先使用该第三方节点

当视频数据包含 TMDB ID 时，自动匹配会优先使用开放平台的 tmdbId + episode 查询，失败时再按标题回退；获取弹幕使用 withRelated=true 汇集关联来源。弹幕与搜索结果会在服务端/CDN 缓存，减少对开放平台的重复请求。

项目公共中继

https://tv.katelya.eu.org 提供弹弹play官方弹幕的公共中继能力。中继服务在服务端完成开放平台认证，下游部署和浏览器不会获得项目使用的 AppSecret。

公共中继主要用于简化 Vercel 等 Web 平台的部署体验。由于公共服务存在可用容量、异常调用检测及平台额度约束，服务可能按实际运行情况进行限流或临时暂停，不保证作为专用弹幕后端长期无限制使用。

自行接入官方弹幕

需要独立可用性、希望脱离公共中继运行的部署，可在弹弹play DevCenter 申请凭证，并仅在自己的服务端环境变量中配置：

DANDANPLAY_APP_ID=在DevCenter申请的AppId
DANDANPLAY_APP_SECRET=有效AppSecret

Vercel 部署应将 DANDANPLAY_APP_SECRET 保存为 Sensitive Environment Variable，并在保存后重新部署。Docker 部署应从未提交到 Git 的运行时环境文件注入凭证，例如：

docker run --env-file .env.docker.local -p 3000:3000 decotv

Docker 与自定义中继

公开 Docker 镜像不会内置共享 AppSecret，也不会默认请求项目公共中继。镜像持有者能够检查镜像内容和运行环境，因此将共享密钥打包进公开镜像无法保证凭证安全。

希望为 Docker 实例统一提供官方弹幕的用户，可以在自己控制的服务器上部署 DecoTV 中继，并为容器指定中继地址：

DANDANPLAY_RELAY_URL=https://your-relay.example.com

Vercel 或其他源码部署也可以使用 DANDANPLAY_RELAY_URL 覆盖默认中继；设为 disabled 时完全禁用中继回退。

不要将真实密钥提交到仓库、写入 NEXT_PUBLIC_* 环境变量、打包进公开镜像或提供给前端生成签名。弹弹play文档说明开放平台将在 2026 年 6 月 25 日 起启用应用分层与额度管理机制；自行部署的中继服务应开启缓存，并根据流量情况配置限流策略。

感谢弹弹play 为 DecoTV 提供弹幕服务支持！

网盘搜索（PanSou）配置

DecoTV 的网盘搜索采用远程 PanSou 节点转发模式。推荐先部署 fish2018/pansou，确认服务可访问后，在后台 PanSou 配置 中填入服务地址（可选填写 Token）。

快速示例：

部署 PanSou 服务并确保 https://your-pansou-domain/api/health 可访问。
进入 DecoTV 后台 PanSou 配置 页面。
填写服务地址（例如 https://your-pansou-domain）。如果 PanSou 开启 AUTH_ENABLED=true，可以直接填写 PanSou 用户名/密码，DecoTV 会自动登录换取 JWT；也可以在 API Token / 鉴权密钥 中直接填 JWT，支持填 Bearer xxx 或裸 token。
先执行连通性测试，再保存配置即可生效。

TMDB 元数据增强配置

DecoTV 支持把 TMDB 作为与豆瓣互补的第二元数据来源，尤其适合欧美 / 日韩内容和私人影库场景。

快速使用：

到 TMDB 后台申请 API Key。
在环境变量或后台 TMDB 配置 中填写 TMDB_API_KEY。
如果部署环境无法直连 TMDB，可额外配置 TMDB_PROXY 或 TMDB_REVERSE_PROXY。
进入后台执行 TMDB 连通性测试，保存后即可生效。

使用建议：

华语内容可以继续以豆瓣为主，TMDB 负责补充海报、背景图和缺失简介。
私人影库建议同时开启 TMDB，这样 OpenList 文件名中的 {tmdb-xxxx} 或 Emby / Jellyfin 的 ProviderIds.Tmdb 可以直接命中精准元数据。
如果未配置 TMDB_API_KEY，项目会自动降级，不影响原有豆瓣链路和公共资源站播放。

私人影库配置（OpenList / 小雅 Alist / Emby / Jellyfin）

DecoTV 支持在后台接入 OpenList、小雅 Alist、Emby、Jellyfin 等私有媒体服务，配置成功后前台会自动显示“我的影库”入口。

OpenList 快速使用：

准备 OpenList 服务地址、Token 和挂载根路径。
推荐按以下格式整理目录，方便精准匹配 TMDB 元数据：

电影：流浪地球2 (2023) {tmdb-835547}/流浪地球2.mkv
剧集：三体 (2023) {tmdb-1428232}/Season 01/S01E01.mkv

进入后台 私人影库 配置区块，添加连接并选择 OpenList。
填写服务地址、Token、根路径，先测试连接，再执行扫描。

小雅 Alist 快速使用：

准备小雅服务地址、访问密码（若实例开启了访问控制）和扫描根目录，默认根目录为 /。
进入后台 私人影库 配置区块，添加连接并选择 小雅 Alist。
填写服务地址、访问密码和根目录；如实例未开启访问密码可留空，根目录可按需填写如 /电影。
先测试连接，再执行扫描；播放 .strm 文件时，服务端会实时刷新阿里云盘直链。

Emby / Jellyfin 快速使用：

在 Emby / Jellyfin 管理后台创建 API Key，按需准备用户 ID。
在 DecoTV 后台添加 Emby 或 Jellyfin 连接，填写服务地址、API Key，可选填写用户 ID 和媒体库过滤。
先测试连接，再保存配置，最后执行扫描或刷新。
播放时 DecoTV 会通过服务端代理获取流地址，并尝试同步播放进度。

补充说明：

私人影库的视频流和鉴权信息不会直接暴露给浏览器端。
小雅 Alist 兼容 Alist API；如果测试连接提示鉴权失败，请检查是否需要填写访问密码。
OpenList 默认根目录为 /Media，小雅 Alist 默认根目录为 /。
部分小雅资源暂不支持站内在线播放，遇到此类资源时请在小雅网页端打开。
Emby / Jellyfin 私人影库支持音轨切换：播放器会基于 AudioStreamIndex 重新加载流并恢复切换前进度；HLS 资源支持无中断音轨切换。
OpenList 即使没有 TMDB ID 也能扫描，但推荐使用规范命名以获得更好的元数据匹配效果。
如果某一个连接失效，只会影响该连接，不会影响其他连接和公共资源站功能。
更完整的部署变量说明可参考 TMDB 与私人影库部署说明。

⬇️ 下载功能使用指南

1) 下载当前集（浏览器分片下载）

在播放页点击 下载当前集。
m3u8 资源会自动解析分片并下载，完成后在浏览器本地合并导出。
该模式不依赖 FFmpeg，适合大部分 Web 部署场景。

2) FFmpeg 转存下载（服务端）

在播放页点击 FFmpeg 转存下载。
官方 Docker 镜像已内置 ffmpeg/ffprobe，VPS Docker 部署可直接使用。
自行构建镜像时请使用本仓库 Dockerfile；非 Docker 手动部署需自行安装 ffmpeg 和 ffprobe。
Vercel 等 Serverless 环境无法稳定运行长时间 FFmpeg 进程，会自动降级为浏览器分片下载。

3) 推荐环境与可选变量

推荐：Docker / VPS（稳定支持浏览器下载 + FFmpeg 转存）。
推荐挂载：/app/.cache/ffmpeg-downloads，用于保存服务端转存的临时成品文件。
可选变量：
FFMPEG_PATH：自定义 ffmpeg 可执行路径。
FFPROBE_PATH：自定义 ffprobe 可执行路径。
FFMPEG_DOWNLOAD_DIR：服务端转存文件目录。
FFMPEG_ALLOW_SERVERLESS=true：仅在你明确具备可执行二进制能力时使用。

VPS Docker 持久化示例：

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

如果使用宿主机目录绑定，例如 ./downloads:/app/.cache/ffmpeg-downloads，请确保目录允许容器内 UID 1001 写入：

mkdir -p ./downloads
sudo chown -R 1001:1001 ./downloads

4) 常见错误排查

拉取播放列表失败 (502)：通常是上游 m3u8 源需要特定 Referer/Origin，请确认源可访问，或切换其他源重试。
FFmpeg API request failed (500/501)：检查部署环境是否安装 FFmpeg；官方 Docker 镜像应开箱可用，自建镜像请确认 Dockerfile 包含 FFmpeg。
EACCES / permission denied：转存目录不可写；使用上方 named volume，或修正宿主机目录权限。
转存大文件失败：检查 VPS 磁盘空间、反向代理超时和 FFMPEG_JOB_RETENTION_MS，必要时降低 FFMPEG_MAX_CONCURRENT_JOBS。

Roadmap

多语言国际化支持
更多数据库存储选择
手机端 APP 开发
智能推荐算法
用户评分系统
弹幕功能（集成弹弹play弹幕库）
下载管理（浏览器分片下载 + FFmpeg 转存）

📺 AndroidTV 使用

目前该项目可以配合 OrionTV 在 Android TV 上使用，可以直接作为 OrionTV 后端

已实现播放记录和网页端同步

详细配置指南：

📖 OrionTV 使用指南
🔒 成人内容过滤使用指南 - 支持通过 URL 参数灵活控制成人内容过滤

OrionTV 成人内容过滤快速配置：

点击查看 OrionTV 过滤配置示例

🎯 推荐方式：使用路径前缀

家庭安全模式（推荐家庭使用）

API 地址: https://your-domain.com/

✅ 自动过滤成人资源源和敏感关键词

完整内容模式（成人用户）

API 地址: https://your-domain.com/adult/

✅ 显示所有内容（包括成人资源）

💡 工作原理:

路径前缀 /adult/ 会被自动识别并重写

例如: /adult/api/search → /api/search?adult=1

OrionTV 无需额外配置，开箱即用

备用方式：使用 URL 参数

注意: 此方式仅适用于 Web 端，OrionTV 可能不支持

家庭安全模式

API 地址: https://your-domain.com

完整内容模式

API 地址: https://your-domain.com?adult=1

详细说明请参阅成人内容过滤使用指南

🎥 TVbox 配置

具体可见 TVBox 配置优化说明 ,详细功能见/admin 管理页面 TVbox 配置

🧑‍💻 用户注册功能

DecoTV 支持用户自助注册功能（可选），适合需要允许用户自行创建账号的场景。

功能特性：

✅ 图形验证码防机器人注册
✅ 严格的用户名和密码验证
✅ 管理后台即时启停和默认用户组配置（默认关闭）
✅ 仅支持 Redis/Upstash/Kvrocks 存储模式

详细使用指南：用户注册功能说明

快速启用：

# 先设置支持多用户的存储
NEXT_PUBLIC_STORAGE_TYPE=redis  # 或 upstash、kvrocks

部署完成后，以站长账号进入 /admin 的“用户配置”，选择新用户默认用户组后打开“允许访客自行注册账号”。

⚠️ 安全提示：建议默认关闭注册，仅在需要时临时开启，注册完成后在后台立即关闭。

🔒 安全与隐私提醒

请设置密码保护并关闭公网注册

为了您的安全和避免潜在的法律风险，我们要求在部署时强烈建议关闭公网注册：

部署要求

设置环境变量 PASSWORD：为您的实例设置一个强密码
仅供个人使用：请勿将您的实例链接公开分享或传播
遵守当地法律：请确保您的使用行为符合当地法律法规

重要声明

本项目仅供学习和个人使用
请勿将部署的实例用于商业用途或公开服务
如因公开分享导致的任何法律问题，用户需自行承担责任
项目开发者不对用户的使用行为承担任何法律责任
本项目不在中国大陆地区提供服务。如有该项目在向中国大陆地区提供服务，属个人行为。在该地区使用所产生的法律风险及责任，属于用户个人行为，与本项目无关，须自行承担全部责任。特此声明

📄 License

🙏 致谢

ts-nextjs-tailwind-starter — 项目最初基于该脚手架。
LibreTV — 由此启发，站在巨人的肩膀上。
ArtPlayer — 提供强大的网页视频播放器。
HLS.js — 实现 HLS 流媒体在浏览器中的播放支持。
Zwei — 提供获取豆瓣数据的 cors proxy
CMLiussss — 提供豆瓣 CDN 服务
感谢所有提供免费影视接口的站点。

📈 Star History

💝 赞赏支持

如果这个项目对你有所帮助，欢迎 Star ⭐ 本项目或请作者喝杯咖啡 ☕

_{🎨 微信赞赏}

🌟 如果觉得项目有用，请点个 Star 支持一下！🌟

_{Made with ❤️ by Decohererk and Contributors}

Name		Name	Last commit message	Last commit date
.github		.github
.husky		.husky
.vscode		.vscode
__tests__		__tests__
docs		docs
public		public
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc.js		.prettierrc.js
CHANGELOG		CHANGELOG
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
TVBox配置优化说明.md		TVBox配置优化说明.md
VERSION.txt		VERSION.txt
commitlint.config.js		commitlint.config.js
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
jest.setup.js		jest.setup.js
next.config.js		next.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.js		postcss.config.js
proxy.worker.js		proxy.worker.js
start.js		start.js
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation