DecoTV：构建个性化跨平台影视聚合站的完整指南

DecoTV：构建个性化跨平台影视聚合站的完整指南

【免费下载链接】DecoTV基于最新版LunaTV二次开发的一个开箱即用的、跨平台的影视聚合播放站。【原KatelyaTV】项目地址: https://gitcode.com/gh_mirrors/de/DecoTV

在数字娱乐需求日益增长的今天，如何快速搭建一个功能完善、界面美观的影视聚合平台，同时保持数据私密性和多设备同步能力，成为许多技术爱好者和家庭媒体中心管理者的共同挑战。DecoTV 应运而生，这是一个基于最新版 LunaTV 二次开发的开源项目，为这一难题提供了优雅的解决方案。

项目定位与核心价值

DecoTV 是一款专为技术爱好者和媒体中心管理者设计的现代化影视聚合播放器。它采用 Next.js 16、Tailwind CSS 4 和 TypeScript 5 构建，不仅提供了开箱即用的部署体验，更在数据隐私、多端同步和功能扩展性方面进行了深度优化。与传统的影视聚合方案不同，DecoTV 强调"可定制、可控制、可扩展"的设计理念，让用户完全掌控自己的观影体验。

目标用户群体

DecoTV 适合三类用户群体：

1. 技术爱好者：希望搭建个性化影视平台，享受完全控制权
2. 家庭媒体中心管理者：需要为家庭成员提供统一的多设备观影体验
3. 隐私敏感用户：希望数据完全自托管，避免第三方监控

功能特性深度解析

核心播放体验

DecoTV 的核心播放功能建立在现代 Web 技术之上，支持 HLS.js 和 ArtPlayer 双引擎，确保在不同设备和网络环境下的流畅播放体验。多音轨切换功能智能识别视频中的音轨数量，仅在存在多条音轨时显示切换按钮，保持界面简洁。

明亮模式界面适合白天使用，提供清新简洁的视觉体验

数据同步与存储策略

项目最大的亮点在于其灵活的存储架构设计。DecoTV 支持四种存储模式，满足不同场景需求：

智能内容发现系统

DecoTV 集成了豆瓣和 TMDB 双元数据源，通过智能匹配算法为影视内容补充完整的元数据信息。系统采用"中文优先、英文回退"的策略，确保华语内容的准确性，同时兼顾欧美内容的完整性。

私人影库集成

对于拥有自建媒体服务器的用户，DecoTV 提供了无缝的集成方案。支持 OpenList、小雅 Alist、Emby 和 Jellyfin 等多种媒体服务器，通过服务端代理保护流地址和鉴权信息，确保私有媒体资源的安全性。

实战部署：从零到一的完整流程

环境准备与基础部署

部署 DecoTV 需要满足以下基础要求：

• Docker 环境（推荐 Docker 20.10+）
• 至少 1GB 可用内存
• 稳定的网络连接
• 基本的命令行操作能力

第一步：获取项目代码

# 克隆项目仓库 git clone https://gitcode.com/gh_mirrors/de/DecoTV cd DecoTV

第二步：选择适合的部署模式

场景一：快速体验与单机使用

对于初次接触或仅需单机使用的用户，推荐使用本地存储模式：

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

场景二：家庭多设备同步

对于家庭用户，建议使用 Kvrocks 存储模式，配置 docker-compose.yml：

services: decotv-core: image: ghcr.io/decohererk/decotv:latest 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 depends_on: - decotv-kvrocks decotv-kvrocks: image: apache/kvrocks container_name: decotv-kvrocks restart: unless-stopped volumes: - kvrocks-data:/var/lib/kvrocks volumes: kvrocks-data:

第三步：访问与初始化

部署完成后，通过浏览器访问http://localhost:3000，使用设置的管理密码登录系统。首次登录后，系统将引导您完成基础配置。

配置影视资源库

DecoTV 部署后默认不包含任何影视资源，需要手动配置资源站点。这是项目设计的核心理念之一：让用户完全控制内容来源，避免法律风险。

基础配置文件示例：

{ "cache_time": 7200, "api_site": { "dyttzy": { "api": "http://example.com/api.php/provide/vod", "name": "示例资源站", "detail": "http://example.com" } }, "custom_category": [ { "name": "华语电影", "type": "movie", "query": "华语" }, { "name": "美剧推荐", "type": "tv", "query": "美剧" } ] }

配置解析：

• cache_time：接口缓存时间（秒），建议设置为 2 小时（7200 秒）
• api_site：资源站点配置，支持多个站点并行
• custom_category：自定义分类，可基于类型和关键词创建个性化导航

高级功能配置指南

弹幕功能集成

DecoTV 支持弹弹play开放平台的弹幕服务，提供三种接入方式：

1. 公共中继模式（Vercel 部署默认）：无需配置，使用项目公共中继
2. 自有凭证模式：在弹弹play DevCenter 申请凭证后配置
3. 自定义中继模式：自建中继服务并配置地址

自有凭证配置示例：

DANDANPLAY_APP_ID=your_app_id DANDANPLAY_APP_SECRET=your_app_secret

网盘搜索配置

集成 PanSou 网盘搜索功能，需要先部署独立的 PanSou 服务：

1. 部署 PanSou 服务并确保健康检查接口可访问
2. 在 DecoTV 后台配置 PanSou 服务地址
3. 如需鉴权，配置对应的 Token 或用户名密码

TMDB 元数据增强

TMDB 作为豆瓣的补充数据源，特别适合欧美和日韩内容：

1. 在 TMDB 官网申请 API Key
2. 配置环境变量或后台设置
3. 执行连通性测试验证配置

性能优化与最佳实践

存储方案选择指南

选择存储方案时，需要综合考虑使用场景、数据量和性能需求：

本地存储模式适用场景：

• 单用户、单设备使用
• 临时测试环境
• 对数据持久性要求不高的场景

Kvrocks 存储模式优势：

• 数据持久化到磁盘，重启不丢失
• 支持多设备同步
• 性能优于 Redis 在某些场景
• 内存占用更友好

生产环境推荐配置：

# docker-compose.prod.yml services: decotv: image: ghcr.io/decohererk/decotv:v1.0.0 # 固定版本，避免意外更新 container_name: decotv restart: unless-stopped ports: - '3000:3000' environment: - USERNAME=${ADMIN_USERNAME} - PASSWORD=${ADMIN_PASSWORD} - NEXT_PUBLIC_STORAGE_TYPE=kvrocks - KVROCKS_URL=redis://kvrocks:6666 - SITE_BASE=${SITE_URL} volumes: - downloads:/app/.cache/ffmpeg-downloads depends_on: kvrocks: condition: service_healthy kvrocks: image: apache/kvrocks container_name: kvrocks restart: unless-stopped volumes: - kvrocks-data:/var/lib/kvrocks healthcheck: test: ["CMD", "redis-cli", "-p", "6666", "ping"] interval: 30s timeout: 10s retries: 3 volumes: kvrocks-data: downloads:

安全配置建议

访问控制策略

1. 公网部署必须设置强密码：避免使用弱密码或默认密码
2. 谨慎开启用户注册功能：仅在可信环境中使用
3. 使用 HTTPS 反向代理：确保数据传输安全
4. 配置防火墙规则：限制不必要的端口访问

内容过滤配置

DecoTV 内置成人内容过滤机制，可通过 URL 参数灵活控制：

• 家庭安全模式：自动过滤成人内容和敏感关键词
• 完整内容模式：显示所有内容，需在 URL 中添加/adult/前缀

OrionTV 集成配置示例：

# 家庭安全模式 API 地址: https://your-domain.com/ # 完整内容模式 API 地址: https://your-domain.com/adult/

下载功能优化

DecoTV 提供两种下载模式，满足不同场景需求：

浏览器分片下载：

• 适合大部分 Web 部署场景
• 无需服务端 FFmpeg 支持
• 自动解析 m3u8 分片并合并

FFmpeg 转存下载：

• 官方 Docker 镜像内置 FFmpeg
• 支持格式转换和优化
• 需要挂载持久化存储卷

推荐挂载配置：

volumes: - decotv-downloads:/app/.cache/ffmpeg-downloads

故障排除与性能调优

常见问题解决方案

问题一：登录后仍提示 401 Unauthorized

可能原因及解决方案：

1. 浏览器 Cookie 问题：清除浏览器 Cookie 后重新登录
2. 残留数据库配置：检查是否设置了冲突的存储环境变量
3. 反向代理配置错误：确保正确传递X-Forwarded-Proto头部

问题二：播放卡顿或加载缓慢

优化建议：

1. 检查网络连接：确保资源站点可正常访问
2. 调整缓存策略：适当增加cache_time值
3. 启用 CDN 加速：对静态资源使用 CDN 服务
4. 优化资源站点选择：选择响应速度快的资源站点

问题三：TVBox 配置失效

解决方案：

# 启用远程 spider.jar ALLOW_REMOTE_SPIDER_JAR=true SPIDER_JAR_URL=https://trusted-source/spider.jar SPIDER_JAR_SHA256=your_jar_sha256_hash

性能监控指标

建议定期监控以下关键指标：

• 内存使用量：确保不超过容器限制
• CPU 使用率：关注高峰时段负载
• 网络流量：监控入站和出站流量
• 存储空间：确保下载缓存目录有足够空间

扩展功能与集成方案

Android TV 集成

DecoTV 可与 OrionTV 配合使用，实现在 Android TV 上的完美体验：

1. 在 Android TV 上安装 OrionTV
2. 配置 DecoTV 作为后端服务地址
3. 享受大屏观影体验，播放记录自动同步

暗夜模式界面适合夜间使用，有效保护视力并提升观影沉浸感

移动端 PWA 支持

DecoTV 支持渐进式 Web 应用（PWA）特性，可将应用安装到手机主屏：

1. 在移动浏览器中访问 DecoTV
2. 点击浏览器菜单中的"添加到主屏幕"
3. 享受接近原生应用的体验

多语言与国际化

虽然当前版本主要支持中文界面，但项目架构已为国际化做好准备。技术栈采用 TypeScript 和现代 React 架构，便于未来添加多语言支持。

版本管理与升级策略

Docker 镜像标签策略

DecoTV 提供灵活的版本管理方案：

生产环境推荐使用版本号标签：

docker pull ghcr.io/decohererk/decotv:v1.0.0

自动更新方案

使用 Watchtower 实现容器自动更新：

# 安装 Watchtower docker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower \ --interval 3600 \ decotv

架构设计与技术实现

前端技术栈

DecoTV 采用现代化的前端技术栈：

• Next.js 16：提供服务器端渲染和静态生成能力
• Tailwind CSS 4：原子化 CSS 框架，确保样式一致性
• TypeScript 5：类型安全的开发体验
• ArtPlayer + HLS.js：专业的视频播放解决方案

后端架构

项目采用无状态架构设计，所有状态通过存储层管理：

• API 路由：基于 Next.js 的 App Router
• 存储抽象层：支持多种存储后端
• 代理中间件：处理跨域和安全限制

安全架构

DecoTV 采用多层安全防护：

1. 输入验证：对所有用户输入进行严格验证
2. 输出编码：防止 XSS 攻击
3. CORS 控制：限制跨域请求
4. 内容过滤：内置成人内容过滤机制
5. SSRF 防护：代理接口多重防护

社区生态与未来发展

项目路线图

DecoTV 持续演进，未来规划包括：

• 多语言国际化支持
• 更多数据库存储选择
• 移动端原生应用开发
• 智能推荐算法优化
• 用户评分系统完善

贡献指南

项目采用标准的开源协作流程：

1. Fork 项目仓库
2. 创建功能分支
3. 提交代码变更
4. 创建 Pull Request
5. 通过代码审查和测试

获取支持与反馈

• 问题报告：通过项目 Issue 页面提交
• 功能建议：参与项目讨论区
• 技术交流：参考项目文档和示例

总结与建议

DecoTV 作为一个现代化的影视聚合解决方案，在易用性、功能性和可扩展性之间取得了良好平衡。无论是个人使用还是家庭共享，都能提供优质的观影体验。

部署建议总结：

1. 个人使用：推荐本地存储模式，简单快捷
2. 家庭共享：使用 Kvrocks 存储，实现多设备同步
3. 生产环境：采用固定版本标签，配合健康检查和监控
4. 内容安全：合理配置访问控制和内容过滤

通过本文的完整指南，您应该已经掌握了 DecoTV 的核心概念、部署方法和最佳实践。现在可以开始构建属于您自己的个性化影视聚合平台，享受完全掌控的数字娱乐体验。

DecoTV 采用科幻星空设计语言，象征着探索无限可能的内容世界

记住，成功的部署不仅需要技术实现，更需要合理的规划和持续的维护。建议从简单配置开始，逐步添加高级功能，确保系统的稳定性和安全性。随着对系统理解的深入，您可以根据实际需求调整配置，打造最适合自己的影视聚合解决方案。

【免费下载链接】DecoTV基于最新版LunaTV二次开发的一个开箱即用的、跨平台的影视聚合播放站。【原KatelyaTV】项目地址: https://gitcode.com/gh_mirrors/de/DecoTV