KVideo README

The project's README from github.com/KuekHaoYang/KVideo. As one markdown file: README.md.

Upstream Sync

Ask DeepWiki

Buy Me A Coffee

Buy Me A Coffee

视频聚合平台 (KVideo)

KVideo Banner

一个基于 Next.js 16 构建的现代化视频聚合播放平台。采用独特的 "Liquid Glass" 设计语言,提供流畅的视觉体验和强大的视频搜索功能。

在线体验:https://kvideo.pages.dev/

Next.js React Tailwind CSS TypeScript License

项目简介

KVideo 是一个高性能、现代化的视频聚合与播放应用,专注于提供极致的用户体验和视觉设计。本项目利用 Next.js 16 的最新特性,结合 React 19 和 Tailwind CSS v4,打造了一个既美观又强大的视频浏览平台。

说明:仓库默认不内置任何视频源、高级源或 IPTV 源。部署者必须自行配置已获授权、可合法使用且允许当前部署方式访问的内容来源。

核心设计理念:Liquid Glass(液态玻璃)

项目的视觉设计基于 "Liquid Glass" 设计系统,这是一套融合了以下特性的现代化 UI 设计语言:

核心功能

智能视频播放

多源并行搜索

多线路折叠

IPTV 直播

豆瓣集成

个性化推荐

收藏管理

观看历史管理

弹幕 (Danmaku)

广告过滤

响应式设计

主题系统

PWA 支持

跨设备配置同步

解决 iOS Safari「添加到主屏幕」后 PWA 与浏览器之间 localStorage 不共享的问题(#119),同时实现多设备配置共享(#115)。

工作原理:

  1. 服务端存储(Upstash Redis):用户配置通过 /api/user/config API 存储在 Upstash Redis 中,使用 user:config:{profileId} 作为 key。Edge Runtime 兼容,Cloudflare Pages / Vercel 均可部署。
  2. 自动拉取(Pull):应用加载时,useConfigSync hook 从服务端拉取配置,与本地 updatedAt 时间戳比较——服务端更新时自动合并到本地。
  3. 自动推送(Push):本地设置变更后,自动延迟 3 秒推送到服务端(防抖),避免频繁写入。
  4. 同步范围:视频源 (sources)、高级源 (premiumSources)、订阅列表 (subscriptions)、屏蔽分类 (blockedCategories)、排序偏好 (sortBy)、语言 (locale)。
  5. 数据隔离:按 profileId(SHA-256 哈希)隔离,不同账户互不影响。

使用前提:

典型场景:

无障碍设计

高级模式

TV/大屏适配

Android TV 应用

Apple TV 应用

数据管理

隐私保护

本应用注重用户隐私:

账户与访问控制

KVideo 现在支持两套认证模式:

方式一:托管账户模式(推荐)

启用条件:

启用后:

强制优先托管模式:设置 MANAGED_AUTH_ENABLED=true 只会改变认证模式选择,不会跳过 AUTH_SECRET 和 Redis 检查。缺少 AUTH_SECRET、UPSTASH_REDIS_REST_URL 或 UPSTASH_REDIS_REST_TOKEN 时,托管账户模式仍不会启用。 首次启用时,如果 Redis 里还没有账户,会自动使用 ADMIN_PASSWORD 和 ACCOUNTS 作为引导种子创建首批托管账户。

方式二:单管理员密码(环境变量模式)

通过 ADMIN_PASSWORD 环境变量设置管理员密码:

# Docker
docker run -d -p 3000:3000 -e ADMIN_PASSWORD=your_password --name kvideo kuekhaoyang/kvideo:latest

登录后自动获得超级管理员权限,可管理所有设置。

向后兼容:ACCESS_PASSWORD 环境变量仍然有效,当 ADMIN_PASSWORD 未设置时,ACCESS_PASSWORD 将作为管理员密码使用。

方式三:多账户系统(环境变量模式)

通过 ACCOUNTS 环境变量配置多个账户,每个账户拥有独立的数据空间(收藏、历史、设置、个人源等)。

兼容格式:

多个账户之间用逗号分隔。

# 基本用法
docker run -d -p 3000:3000 \
  -e ACCOUNTS="pass1:张三:admin,pass2:李四:viewer,pass3:王五" \
  --name kvideo kuekhaoyang/kvideo:latest

# 为观众添加额外权限(如 IPTV 访问和源管理)
docker run -d -p 3000:3000 \
  -e ACCOUNTS="pass1:张三:admin,pass2:李四:viewer:iptv_access|source_management" \
  --name kvideo kuekhaoyang/kvideo:latest

KVideo (KuekHaoYang/KVideo)

Searching Database…

4.2K ·GitHub
Что это?KVideo — self-hosted платформа агрегации и стриминга видео на Next.js 16 с UI в стиле 'Liquid Glass' (глассморфизм), параллельным поиском по нескольким источникам, IPTV-эфиром и слоем комментариев данмаку.
Это хостинг-сервис или то, что я разворачиваю сам?Это self-hosted: вы сами запускаете образ (например, через Docker) и подключаете свои легально доступные видеоисточники; управляемого сервиса KVideo не существует.
Как его развернуть?Скачайте и запустите Docker-образ с открытым портом 3000, настройте вход через переменные окружения ACCOUNTS или ADMINPASSWORD, затем добавьте свои видеоисточники на странице настроек.
Есть ли в нём встроенные видеоисточники?Нет, в репозитории нет ни одного встроенного видео-, premium- или IPTV-источника; после развёртывания нужно настроить свои авторизованные, легально доступные источники.
Что нужно для синхронизации настроек между устройствами?Без экземпляра Upstash Redis (UPSTASHREDISRESTURL/TOKEN) настройки и источники остаются локальными для каждого браузера; с настроенным Redis источники, подписки и предпочтения синхронизируются автоматически между устройствами и PWA-установками, включая случай iOS Safari 'add to home screen'.
Можно использовать это на телевизоре, а не только в браузере?Да — помимо адаптивного веб-UI с навигацией TV-пультом, есть отдельные лёгкие WebView-приложения для Android TV и SwiftUI-приложение для Apple TV (tvOS), которые просто загружают ваш развёрнутый экземпляр.
Что такое дизайн 'Liquid Glass'?Это визуальная дизайн-система KVideo, построенная на эффектах матового стекла через backdrop-filter, единых скруглённых углах, светящихся состояниях hover/focus и анимациях cubic-bezier с физическими кривыми для целостного, современного ощущения.
Он поддерживает живые IPTV-каналы помимо видео по запросу?Да, он импортирует плейлисты M3U/M3U8 или списки каналов JSON, автоматически выявляет проблемы воспроизведения HEVC, проксирует потоки для устранения проблем CORS/User-Agent и автоматически переключается на источник с наименьшей задержкой, если канал отказал.
Как работает функция данмаку (бегущих комментариев)?KVideo подключается к self-hosted API агрегации, совместимому с danmuapi, и рисует сотни бегущих/верхних/нижних комментариев на Canvas-слое, не вредя производительности воспроизведения, с настраиваемой прозрачностью, размером шрифта и заполнением экрана.
Можно ли блокировать рекламу во время воспроизведения?Да, есть встроенный рекламный фильтр с режимами по ключевым словам, эвристическим (beta) и агрессивным, переключаемым на лету из меню настроек плеера.
Size
3.1 MB
Stars
4.2K
Age
11mo
Commits · 90 Days