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
这是什么？KVideo 是一个自托管的视频聚合与流媒体播放平台，基于 Next.js 16 构建，采用“Liquid Glass”玻璃拟态界面，支持并行多源搜索、IPTV 直播电视以及弹幕评论覆盖层。
这是托管服务，还是要我自己部署？它是自托管的：你需要自行运行镜像（例如通过 Docker），并将其指向你自己合法可用的视频源；KVideo 没有提供托管服务。
如何部署它？拉取并运行 Docker 镜像并暴露 3000 端口，通过 ACCOUNTS 或 ADMINPASSWORD 环境变量设置登录，然后在设置页面中添加你自己的视频源。
它内置视频源吗？没有，该仓库不内置任何视频源、付费源或 IPTV 源；部署后你必须自行配置已获授权、可合法访问的源。
跨设备配置同步需要什么条件？如果没有 Upstash Redis 实例（UPSTASHREDISRESTURL/TOKEN），设置和视频源只会保留在各个浏览器本地；配置好 Redis 后，视频源、订阅和偏好设置会自动跨设备和 PWA 安装同步，包括 iOS Safari“添加到主屏幕”的情况。
除了在浏览器里，还能在电视上使用吗？可以——除了支持电视方向键/遥控器导航的响应式网页界面外，还有专门面向 Android TV 的轻量级 WebView 应用，以及面向 Apple TV（tvOS）的 SwiftUI 应用，它们只是加载你部署好的实例。
“Liquid Glass”设计是什么？它是 KVideo 的视觉设计体系，围绕磨砂玻璃 backdrop-filter 效果、统一的圆角、悬停/聚焦时的发光状态，以及基于物理感的 cubic-bezier 动画构建，营造出连贯统一的现代感。
除了点播视频，它还支持 IPTV 直播频道吗？支持，它可以导入 M3U/M3U8 播放列表或 JSON 频道列表，自动检测 HEVC 播放问题，通过代理流修复 CORS/User-Agent 问题，并在某个频道失效时自动切换到延迟最低的源。
弹幕（滚动评论）功能是如何工作的？KVideo 连接到自托管的兼容 danmuapi 的聚合 API，在 Canvas 覆盖层上渲染数百条滚动、顶部或底部弹幕，且不影响播放性能，透明度、字号和屏幕占比均可调节。
播放时可以屏蔽广告吗？可以，它内置了广告过滤器，提供关键词、启发式（测试版）和强力三种模式，可以在播放器的设置菜单中实时切换。
What are similar projects?StarLive, LibreTV, ui-ux-pro-max-skill, whirl, neko-master, crm, agent-device, full-stack-fastapi-template
Which topics is it in?liquid-glass, danmaku, android-tv, hls, iptv, tvos, adblock, video-streaming, dark-mode, pwa, accessibility, tailwindcss
Creator
KuekHaoYang
Size
3.1 MB
Stars
4.2K
Updated
CommitAug 16Releaseandroid-tv-apk-2026-04-02Apr 02
Age
11mo
Commits · 90 Days