🗒️【神级开源】KatelyaTV：打造你的专属全网影视聚合中心（从零开始保姆级教程）
2025-11-22
| 2025-11-21
字数 3558阅读时长≈ 9 分钟
type
status
date
tags
category
icon
password
slug
summary
在这个流媒体平台割据、会员费由于通胀不断上涨的年代，想安安静静看个剧变得越来越难。我们手机里装满了爱优腾芒，电视盒子里塞满了各种广告满天飞的第三方APP，却依然很难找到一个清爽、聚合、且完全由自己掌控的观影环境。
今天，我要向大家重磅推荐一个在 GitHub 上非常低调但功能强大的开源项目——KatelyaTV。
如果你是一个影视爱好者，或者你正在寻找替代传统 TVBox 的更现代化方案，那么 KatelyaTV 绝对会让你眼前一亮。作为一名已经深度使用该项目两个月的用户，我将通过这篇超过 3000 字的长文，带你彻底玩转 KatelyaTV。

🌟 第一部分：什么是 KatelyaTV？它的前世今生

1.1 项目背景

KatelyaTV 并非横空出世，它是基于曾经广受好评的 MoonTV (LunaTV) 项目进行的二次开发和深度优化版本。原项目因为种种原因停止维护后，开源社区的力量让它以 KatelyaTV 的名字重生。
简单来说，KatelyaTV 是一个基于 Next.js 开发的、现代化的、可自托管的影视聚合播放器。

1.2 它不是什么？

  • 它不是资源提供商：KatelyaTV 本身不存储任何视频文件，它只是一个播放器和聚合搜索工具。
  • 它不是传统安卓 APP：虽然它支持 PWA（可以像 APP 一样安装），但它本质上是一个 Web 应用，这意味着你可以在 iPhone、安卓手机、iPad、PC 浏览器甚至电视浏览器上直接通过网址访问，无需下载安装包。

1.3 为什么你需要它？

在体验 KatelyaTV 之前，我使用过 Emby（搭建门槛高、需下载资源）、TVBox（界面相对复古、配置接口易失效）、以及各种盗版影视站（广告多、体验差）。
KatelyaTV 完美解决了以下痛点：
  1. 跨平台同步难：在地铁上用手机看了一半的剧，回家打开电视能接着看吗？KatelyaTV 支持多端同步（需配置数据库），无缝衔接。
  1. 界面审美疲劳：大多数第三方壳子的 UI 设计还停留在十年前。KatelyaTV 采用了 Material Design 风格，支持黑夜模式，UI 极具现代感，媲美奈飞。
  1. 隐私与安全：代码完全开源，部署在你自己的服务器或 Vercel 账号上，没有第三方后台监控你的观看习惯。

🚀 第二部分：核心优势分析（作为使用者的真实感受）

2.1 极致的聚合搜索体验

这是 KatelyaTV 最杀手级的功能。你不需要知道你想看的电影在哪个网站，只需要在搜索框输入关键词，它会自动通过你配置的 JSON 接口去全网检索。
  • 实测：输入“庆余年”，它会同时展示来自 A 站、B 站、C 站等多个源的搜索结果。哪个源速度快、画质高，你点哪个就行。

2.2 强大的播放器内核 (ArtPlayer)

很多网页版播放器功能简陋，但 KatelyaTV 内置了 ArtPlayer，支持功能非常丰富：
  • 倍速播放：0.5x - 2.0x 随意调节。
  • 画中画模式：手机端支持悬浮窗播放，边聊天边看剧。
  • 自动跳过片头片尾：这是追剧党的最爱！你可以设置自动跳过前 90 秒和后 30 秒，或者让系统智能识别。
  • 格式兼容性：完美支持 HLS (m3u8) 等主流流媒体格式。

2.3 真正的全平台兼容 (PWA 技术)

这是我最喜欢的一点。
  • iOS 用户：众所周知，iOS 上安装第三方影视 APP 极其麻烦（伪装上架、掉证书）。KatelyaTV 直接在 Safari 打开，点击“添加到主屏幕”，它就变成了一个独立的 APP，体验和原生应用几乎没有区别。
  • 电视端：只要你的电视浏览器支持现代内核，或者你使用 TVBox 的接口模式，它都能完美适配大屏操作。

2.4 多用户与同步系统

如果你是为全家人搭建，KatelyaTV 的多用户系统非常实用。
  • 每个家庭成员可以有自己的账号。
  • 收藏夹、播放历史是独立的。
  • 支持数据持久化存储（Redis/Upstash/Kvrocks），即使重启服务，数据也不会丢失。

2.5 安全的内容过滤

家里有小朋友？KatelyaTV 支持配置成人内容过滤系统（需配合数据库），可以有效屏蔽不适合儿童观看的资源源或搜索结果，这在同类开源项目中是非常贴心的设计。
<ins/>

🛠 第三部分：保姆级安装教程

KatelyaTV 的部署方式非常灵活，无论你是小白用户（只有 GitHub 账号）还是极客玩家（有 NAS 或 VPS），都能找到适合你的方案。
注意：本教程基于 katelya77/KatelyaTV 主仓库编写，这也是 bobvane 等分支的上游来源。

方案 A：完全免费党（Vercel + Upstash）—— 强烈推荐 ⭐⭐⭐⭐⭐

适用人群：没有服务器、不想花钱、想要公网访问、小白用户。

准备工作

  1. 注册一个 GitHub 账号。
  1. 注册一个 Vercel 账号（使用 GitHub 登录）。
  1. 注册一个 Upstash 账号（用于免费的 Redis 数据库，保存播放记录）。

第一步：Fork 项目

  1. 访问 https://github.com/katelya77/KatelyaTV。
  1. 点击右上角的 Fork 按钮，将仓库复制到你自己的账号下。

第二步：配置 Upstash 数据库

  1. 登录 Upstash 控制台，点击 "Create Database"。
  1. Name 随便填（如 katelya-db），Region 选择离你近的（如 AP-Southeast 或 US-East）。
  1. 创建成功后，在数据库详情页找到 REST API 部分。
  1. 复制 UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN 这两个值，记在记事本上。

第三步：部署到 Vercel

  1. 登录 Vercel，点击 Add New -> Project。
  1. 在 Import Git Repository 处，选择你刚才 Fork 的 KatelyaTV 项目。
  1. 点击 Import。
  1. 关键步骤：配置环境变量 (Environment Variables)。 在部署页面展开 "Environment Variables" 选项，添加以下变量：
      • PASSWORD: 设置一个你的管理员密码（如 admin888），用于登录后台。
      • NEXT_PUBLIC_STORAGE_TYPE: 填 upstash。
      • UPSTASH_REDIS_REST_URL: 填入刚才 Upstash 获取的 URL。
      • UPSTASH_REDIS_REST_TOKEN: 填入刚才 Upstash 获取的 TOKEN。
      • NEXT_PUBLIC_ENABLE_REGISTER: 填 true（允许注册用户，或者填 false 仅限管理员）。
  1. 点击 Deploy。
  1. 等待约 1-2 分钟，屏幕上撒花庆祝，点击预览链接，你的专属 KatelyaTV 就上线了！

方案 B：NAS/服务器党（Docker 部署）—— 极客首选 ⭐⭐⭐⭐

适用人群：有群晖/威联通 NAS、或是拥有一台 VPS 的用户。数据掌握在自己手里，速度最快。

方法 1：Docker Run (最简单，无数据库，数据存本地)

如果你只需要单人使用，不需要复杂的同步，直接一条命令：
访问 http://你的IP:3000 即可。

方法 2：Docker Compose (推荐，含 Redis 数据库)

为了保存播放记录和收藏，建议配合 Redis 使用。
  1. 创建一个文件夹 katelyatv。
  1. 在该文件夹内创建 docker-compose.yml 文件，内容如下：
  1. 在终端运行 docker-compose up -d。
  1. 搞定！现在你拥有了一个带数据库支持的完整版 KatelyaTV。

⚙️ 第四部分：配置指南（如何让它能看片）

这是最重要的一步！ 出于合规性考虑，KatelyaTV 默认是不包含任何视频源的。刚安装好打开，你会发现搜索不到任何东西，这是正常的。你需要手动配置 config.json。

4.1 获取配置源

这里的“源”通常指的是 TVBox 格式的接口或者是 KatelyaTV 专用的 JSON 配置。
  • 哪里找？ 可以在 Google 搜索 "TVBox 接口 json" 或者 "KatelyaTV 视频源"。GitHub 上有很多热心网友维护的 config.json 集合。
  • 格式说明：它兼容 TVBox 的多源接口格式。

4.2 导入配置

  1. 打开你的 KatelyaTV 网页。
  1. 点击右上角的设置图标（齿轮）或直接访问 /admin。
  1. 输入你在部署时设置的 PASSWORD 登录。
  1. 找到 “配置管理” (Config Management) 或 “视频源配置”。
  1. 你有两个选择：
      • 远程订阅：输入一个以 .json 结尾的 URL（推荐，这样源更新了你也能同步）。
      • 文本编辑：直接将 JSON 内容粘贴进去。
  1. 点击保存。

4.3 验证

回到首页，在搜索框输入一个热门电影名字（如“阿凡达”）。如果下方刷刷刷出现了一排结果，恭喜你，配置成功！

🎮 第五部分：使用技巧与进阶玩法

5.1 将其变为手机 APP (PWA)

  • iOS: 在 Safari 中打开你的网站 -> 点击底部中间的分享按钮 -> 下滑找到“添加到主屏幕” -> 确认。现在桌面上出现了一个 KatelyaTV 的图标，点开它，没有浏览器地址栏，全屏沉浸式体验。
  • Android: 使用 Chrome 打开 -> 点击右上角菜单 -> “安装应用”或“添加到主屏幕”。

5.2 配合电视使用

如果你想在电视上看：
  1. 投屏：手机端播放视频时，ArtPlayer 播放器通常支持 DLNA 投屏（取决于源的格式和手机浏览器支持）。
  1. 电视浏览器：在电视自带浏览器输入你的网址（建议配合蓝牙鼠标或飞鼠，体验更好）。
  1. TVBox 联动：KatelyaTV 甚至可以生成一个供 TVBox 使用的配置接口（在设置里可以找到），你可以把它当作一个源管理器，然后在电视上的 TVBox APP 里调用。

5.3 数据备份

如果你使用的是 Docker + Redis 方案，记得定期备份 redis-data 目录。 如果你使用的是 Vercel + Upstash，数据在云端，相对安全，但建议定期导出 Upstash 的数据。

📝 第六部分：常见问题排查 (FAQ)

Q1: 部署成功了，但是搜索一直转圈圈，不出结果？
  • 原因：通常是配置的视频源接口失效了，或者该接口屏蔽了海外 IP（如果你用 Vercel 部署，服务器在海外）。
  • 解决：尝试更换一个国内可直连的接口，或者使用开启了 Cloudflare 代理的接口。如果在本地 Docker 部署，检查你的网络环境是否能访问那些源网站。
Q2: 播放视频提示“跨域错误”或无法播放？
  • 原因：Web 播放器受限于浏览器的安全策略（CORS）。某些视频源不支持跨域播放。
  • 解决：
      1. 在设置里开启 “代理播放” (Proxy) 选项（会消耗服务器流量）。
      1. 更换一个源（通常 M3U8 格式的兼容性最好）。
      1. 使用支持嗅探的浏览器插件。
Q3: 忘记管理员密码了怎么办？
  • Vercel 用户：去 Vercel 后台的环境变量里重新设置 PASSWORD，然后 Redeploy。
  • Docker 用户：修改 docker-compose.yml 里的密码，然后 docker-compose up -d 重启。

🎬 第七部分：总结与评价

作为一名折腾过无数影音工具的玩家，KatelyaTV 给了我极大的惊喜。它没有 Plex/Emby 那样庞大的刮削和存储压力，却比传统的 TVBox 更加优雅、现代和可控。
它的核心价值在于“连接”：连接了分散在互联网各个角落的资源，连接了你的手机、电脑和电视。
优点总结：
  • ✅ 免费开源，无内购，无强制广告。
  • ✅ 界面精美，交互逻辑符合现代习惯。
  • ✅ 部署灵活，Vercel 方案让小白也能零成本拥有专属影视站。
  • ✅ 隐私安全，数据完全掌握在自己手中。
缺点/注意事项：
  • ⚠️ 依赖源：体验好坏 90% 取决于你找到的视频源质量。
  • ⚠️ 门槛：相比直接下载个 APP，它还是需要一点点动手能力的（不过看完本文你应该没问题了）。
如果你厌倦了在各个视频 APP 之间切换，厌倦了忍受长达 90 秒的广告，那么花 20 分钟搭建一个属于你的 KatelyaTV，绝对是今年最值得的数字投资之一。
附录：资源链接
  • Issue 反馈: 如果遇到 Bug，请到 GitHub Issues 区反馈。
免责声明：本文仅从技术角度分析开源项目 KatelyaTV 的部署与使用。请大家支持正版影视作品，项目仅供学习交流，请勿用于非法用途。
<ins/>
相关文章 :
建站
  • Docker
  • VPS
  • Web
    • 【年度宝藏】DecoTV：KatelyaTV 的完美进化，打造你的终极私人影视聚合中心（保姆级教程）自建项目：VPS-Tailscale-DERP-AutoSetup（中国VPS部署带域名版）
    Loading...
    目录
    0%