Buy Me A Coffee

视频聚合平台 (KVideo)

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

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

项目简介

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

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

核心设计理念：Liquid Glass（液态玻璃）

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

玻璃拟态效果：通过 backdrop-filter 实现的磨砂半透明效果，让 UI 元素如同真实的玻璃材质
通用柔和度：统一使用 rounded-2xl 和 rounded-full 两种圆角半径，创造和谐的视觉体验
光影交互：悬停和聚焦状态下的内发光效果，模拟光线被"捕获"的物理现象
流畅动画：基于物理的 cubic-bezier 曲线，实现自然的加速和减速过渡
深度层级：清晰的 z-axis 层次结构，增强空间感和交互反馈

核心功能

智能视频播放

HLS 流媒体支持：基于 hls.js 原生支持 HLS (.m3u8) 格式，提供流畅的视频播放体验
播放控制：完整的播放控制功能，包括进度条、音量控制、播放速度调节、全屏模式等
自动跳过片头/片尾：可设置自动跳过片头和片尾的秒数
自动连播：支持自动播放下一集
移动端优化：专门为移动设备优化的播放器界面和双击手势控制
Chromecast 投屏：支持通过 Google Cast 投屏到电视等设备
画中画 (PiP)：支持浮动窗口模式播放
全屏模式选择：支持系统全屏和网页全屏两种模式
代理播放：三种代理模式（智能重试、仅直连、总是代理），灵活应对不同网络环境
卡顿检测：自动检测播放卡顿并提示
一起看 (VideoTogether)：播放器页面内置官方网页集成脚本，可直接创建或加入房间与朋友同步观看
键盘快捷键：空格/K 播放暂停、F 全屏、M 静音、P 画中画、J/L/方向键快进快退、上下键音量调节

多源并行搜索

聚合搜索引擎：同时在多个视频源中并行搜索，通过 Server-Sent Events (SSE) 实时返回结果
自定义视频源：支持添加、编辑和管理自定义视频源
个人视频源：非管理员用户可添加个人视频源，不影响其他用户（数据按用户隔离）
订阅源管理：支持通过 JSON 链接批量导入和自动更新视频源
JSON 批量导入：在导入设置中直接粘贴 JSON 数组格式的视频源进行批量添加
智能解析：统一的解析器系统，自动处理不同源的数据格式
搜索历史：自动保存搜索历史，支持快速重新搜索
搜索结果显示：支持默认显示和合并同名源两种模式
实时延迟监测：可选实时显示各源的网络延迟
清晰度标签：自动解析并显示视频清晰度（4K/蓝光/1080P/720P/HD 等），方便快速分辨源质量
实际分辨率检测：播放视频时自动检测并显示实际视频分辨率（如 1920x1080），不依赖源标签，显示真实清晰度。分辨率标签 5 秒后自动隐藏，鼠标移动时重新显示
全源分辨率探测：播放器源列表中所有源均自动通过 m3u8 清单探测实际分辨率，显示精确的分辨率标签（1080P/720P/4K 等），不仅限于当前播放的源
繁体中文搜索：自动将繁体中文转换为简体中文进行搜索，确保繁体输入也能搜到结果
源过滤：支持按源和类型筛选搜索结果，源标签支持按类型分组显示，智能合并同名分类标签，展开/折叠状态持久化记忆
多级标签：搜索结果和播放器中显示源名称和内容类型双重标签
搜索取消：搜索进行中可随时点击"取消"按钮终止搜索，释放资源
内容类目过滤：在设置中添加屏蔽关键词（如"伦理"），匹配类目的视频将自动从搜索结果中过滤
搜索性能优化：服务端支持客户端断开检测（AbortSignal），每源超时保护，总结果数上限，防止内存溢出

多线路折叠

智能折叠：播放页面的线路列表默认只显示前 5 个源，避免长列表影响体验
展开/收起：超过 5 个源时显示"展开更多 (N)"按钮，可随时展开查看全部线路
按类型分组：当线路包含类型信息时，自动按内容类型分组显示（如"电影"、"电视剧"等）
延迟排序：线路按网络延迟自动排序，最快的源排在前面
源切换：在线路列表中快速切换到其他源，支持断点续播
自动切源：当当前源不可用时，自动切换到延迟最低的可用源
短链接优化：使用 sessionStorage 缓存源数据，避免 URL 过长导致 CDN 414 错误

IPTV 直播

M3U 播放列表：支持导入和管理 M3U/M3U8 格式的 IPTV 源
JSON 频道列表：支持导入 JSON 格式的频道列表（数组或对象格式，自动识别）
HEVC 智能兼容：自动检测 HEVC/H.265 编码流，优先选择 H.264 级别以避免音画不同步或仅有声音问题
频道网格：按分组展示频道，支持分页浏览，大列表搜索优化
多级频道列表：播放器内按源分组 → 按分类分组 → 频道的三级列表导航
多线路折叠：频道多线路默认显示前 3 条，可点击展开查看全部
自动切源：当视频源不可用时，自动选择延迟最低的可用源
自定义请求头：自动解析 M3U 中的 http-user-agent 和 http-referrer 属性，通过代理传递
User-Agent 智能代理：当频道指定自定义 User-Agent 时，自动走代理路径避免浏览器限制，解决 CCTV 等频道仅有声音无画面的问题
流媒体代理：内置 HLS 流代理，自动处理 CORS 问题和 M3U8 URL 重写
智能内容检测：当 content-type 不明确时，检查响应体内容自动识别 M3U8 格式，同时保持二进制流数据完整性
重定向跟随：自动跟随 HTTP 3xx 重定向，提升兼容性
超时保护：15 秒请求超时、30 秒加载超时、20 秒分片加载超时、3 次清单重试
逐源频道缓存：每个 IPTV 源的频道独立缓存，避免重复加载
并发控制：最多同时拉取 3 个源，防止网络拥堵
权限控制：通过 iptv_access 权限控制谁可以访问 IPTV 功能
键盘快捷键：播放器内支持空格暂停/继续、F 全屏、M 静音、方向键调节音量等
搜索优化：播放器内搜索使用 useTransition 非阻塞渲染，避免大列表卡顿

豆瓣集成

电影 & 电视剧分类：支持在电影和电视剧之间无缝切换，方便查找不同类型的影视资源
详细影视信息：自动获取豆瓣评分、演员阵容、剧情简介等详细信息
推荐系统：基于豆瓣数据的相关推荐
自定义标签管理：支持拖拽排序的标签管理器，自定义首页推荐分类
可点击演员/导演：播放页面的演员、导演名字可直接点击搜索其他作品

个性化推荐

基于观看历史：根据观看历史自动分析偏好，推荐相关影视内容
智能分析：分析最常观看的类型、演员和地区，生成精准推荐
标签集成：推荐作为首个标签「为你推荐」出现在标签栏中（需观看 2 部以上作品）
自动加载：无限滚动自动加载更多推荐内容
独立模式：普通模式和高级模式的推荐互相独立
缓存优化：推荐结果缓存 30 分钟，避免重复请求

收藏管理

一键收藏：在搜索结果和播放页面快速收藏视频
收藏列表：独立的收藏侧边栏，快速访问已收藏的视频
容量限制：每个模式最多 100 条收藏
普通/高级隔离：普通模式和高级模式的收藏互相独立
数据隔离：多账户场景下，每个用户拥有独立的收藏数据

观看历史管理

自动记录：自动记录观看进度和历史
断点续播：从上次观看位置继续播放
智能去重：按标题去重（V2），相同标题不同源的历史合并为一条
容量限制：最多保存 50 条历史记录
历史管理：支持删除单条历史或清空全部历史
隐私保护：所有数据存储在本地，不上传到服务器

弹幕 (Danmaku)

弹幕聚合：接入自建弹幕聚合 API（兼容 danmu_api 格式），自动匹配当前播放内容
Canvas 渲染：基于 Canvas 的高性能弹幕渲染，支持数百条弹幕同时滚动，不影响播放交互
滚动/顶部/底部弹幕：支持三种弹幕类型，自动分配轨道防止重叠
自定义显示：可调节弹幕透明度（10%-100%）和字号（14/18/20/24/28px）
显示区域：可选 25%/50%/75%/100% 的屏幕区域显示弹幕
播放器联动：暂停时弹幕冻结，跳转时自动清除，全屏模式下正常显示
多 API 管理：每个用户可添加多个弹幕 API，选择当前使用的 API
优先级规则：用户选择的弹幕 API 优先于系统默认配置
环境变量预设：可通过 DANMAKU_API_URL 或 NEXT_PUBLIC_DANMAKU_API_URL 为所有用户预设弹幕 API 地址

广告过滤

多模式选择：支持关闭、关键词过滤、智能启发式过滤(Beta)和激进模式
UI 集成：在播放器设置菜单中直接切换模式，实时生效
自定义关键词：支持通过环境变量或文件扩展过滤关键词
高性能：基于流式处理，对播放加载速度几乎无影响

响应式设计

全端适配：完美支持桌面、平板、移动设备和 TV/机顶盒
移动优先：专门的移动端组件和交互设计
触摸优化：针对触摸屏优化的手势和交互（双击快进/快退、滑动音量控制）
TV 适配：遥控器方向键导航和大屏 UI 优化

主题系统

深色/浅色模式：支持系统级主题切换
动态主题：基于 CSS Variables 的动态主题系统
无缝过渡：主题切换时的平滑过渡动画

PWA 支持

可安装应用：支持将 KVideo 安装为独立应用
Service Worker：离线缓存和资源预加载
全屏体验：独立应用模式下的沉浸式体验
配置同步：iOS Safari 添加到主屏幕后，视频源和设置自动从服务端同步，无需重新配置

跨设备配置同步

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

工作原理：

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

使用前提：

需配置 Upstash Redis 环境变量（UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN），与观看历史/收藏同步共用同一 Redis 实例。
未配置 Redis 时，配置同步功能静默降级——应用正常运行，仅本地存储生效。

典型场景：

电脑浏览器配置了视频源 → 手机打开同一实例 → 自动拉取到相同配置
iOS Safari「添加到主屏幕」后打开 PWA → 自动从 Redis 同步配置，无需重新设置

无障碍设计

键盘导航：完整的键盘快捷键支持（播放控制、音量、进度等）
ARIA 标签：符合 WCAG 标准的无障碍实现
语义化 HTML：使用语义化标签提升可访问性

高级模式

独立入口：在浏览器地址栏直接输入 /premium 即可进入独立的高级视频专区
内容隔离：高级内容与普通内容完全物理隔离，互不干扰
专属设置：拥有独立的内容源管理和功能设置（播放器、显示、弹幕等设置完全独立）
独立推荐：基于高级模式观看历史的个性化推荐，与普通模式互不影响
分类浏览：支持模糊匹配合并多源的相同分类标签，提供统一浏览体验
交错排列：多源结果智能交错排列，平衡各源展示

TV/大屏适配

自动检测：自动检测 TV 浏览器（Smart TV、Tizen、WebOS、Fire TV 等）
空间导航：支持遥控器/方向键在页面元素间导航
10 英尺 UI：TV 模式下自动放大字体、交互元素和间距
焦点高亮：TV 模式下聚焦元素显示醒目的高亮边框和缩放效果
播放器兼容：播放器区域不受空间导航干扰，方向键正常控制播放

Android TV 应用

WebView 封装：基于 Android WebView 的轻量 APK，直接加载 KVideo 网页
遥控器支持：D-pad 中心键映射为 Enter，Back 键映射为网页后退
全屏沉浸：自动横屏、全屏、硬件加速
Leanback 启动器：支持从 Android TV 主屏直接启动
可配置 URL：在 MainActivity.kt 中修改 KVIDEO_URL 常量指向你的部署实例

Apple TV 应用

WKWebView 封装：基于 tvOS WKWebView 的轻量 SwiftUI 应用，直接加载 KVideo 网页
遥控器支持：滑动手势映射为滚动，点击映射为聚焦/选择，Menu 按钮支持网页后退
TV 模式注入：页面加载后自动注入 tv-mode CSS 类，激活大屏优化样式
可配置 URL：在 ContentView.swift 中修改 kvideoURL 常量指向你的部署实例

数据管理

设置导出/导入：支持将所有设置导出为 JSON 文件，方便备份和迁移
JSON 批量导入：支持粘贴 JSON 数组格式的视频源进行批量导入
滚动位置记忆：退出或刷新页面后，自动恢复到之前的滚动位置
返回顶部：一键返回页面顶部
数据隔离：多账户场景下，所有用户数据（历史、收藏、设置、个人源）按 profileId 完全隔离

隐私保护

本应用注重用户隐私：

本地存储：所有数据存储在本地浏览器中
无服务器数据：不收集或上传任何用户数据
自定义源：用户可自行配置视频源
数据隔离：多账户场景下，每个用户的数据（历史、收藏、设置、个人源）完全隔离
Profile ID：基于密码的 SHA-256 哈希生成唯一用户标识，密码不可逆推

账户与访问控制

KVideo 支持基于环境变量的账户认证系统，支持角色区分和细粒度权限控制。

方式一：单管理员密码

通过 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 环境变量配置多个账户，每个账户拥有独立的数据空间（收藏、历史、设置、个人源等）。

格式： 密码:名称[:角色[:权限1|权限2|...]]，多个账户用逗号分隔。

角色：super_admin（超级管理员）、admin（管理员）或 viewer（观众，默认）
权限（可选）：使用 | 分隔，为该账户添加其角色之外的额外权限

# 基本用法
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

特点：

每个账户拥有独立的收藏、历史、设置和个人视频源数据
可同时配置 ADMIN_PASSWORD（作为超级管理员入口）
支持为任何角色添加额外的自定义权限

角色与权限

| 权限 | 说明 | super_admin | admin | viewer | |------|------|:-----------:|:-----:|:------:| | source_management | 管理系统视频源 | ✓ | - | - | | account_management | 查看账户列表 | ✓ | - | - | | danmaku_api | 配置系统弹幕 API | ✓ | - | - | | data_management | 导出/导入/重置数据 | ✓ | - | - | | player_settings | 播放器设置 | ✓ | ✓ | - | | danmaku_appearance | 弹幕外观设

KVideo

Install / Use

README