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）。

工作原理：

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 哈希）隔离，不同账户互不影响。

使用前提：

• 需配置 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 现在支持两套认证模式：

• 托管账户模式（推荐）：配置 AUTH_SECRET + Upstash Redis 后，登录改为 用户名 + 密码，超级管理员可直接在设置页创建、修改、重置和删除账户。
• 环境变量模式（兼容旧部署）：未启用托管账户时，继续使用 ADMIN_PASSWORD / ACCESS_PASSWORD / ACCOUNTS 进行密码登录。

方式一：托管账户模式（推荐）

启用条件：

• 配置 AUTH_SECRET
• 配置 UPSTASH_REDIS_REST_URL
• 配置 UPSTASH_REDIS_REST_TOKEN

启用后：

• 主登录页使用 用户名 + 密码
• 服务端使用 HTTP-only 签名会话 Cookie 作为认证真源
• 超级管理员可在设置页直接管理账户和权限
• 配置同步、历史、收藏等跨设备数据会按登录账户自动隔离

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

兼容格式：

• 旧格式：密码:名称[:角色[:权限1|权限2|...]]
• 新格式：用户名:密码:名称[:角色[:权限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	弹幕外观设置	✓	✓	-
view_settings	显示设置	✓	✓	✓
iptv_access	访问 IPTV 功能	✓	✓	-

通过 ACCOUNTS 的第 4 个字段，可以为任何角色添加上表中的额外权限。例如让观众也能访问 IPTV：password:name:viewer:iptv_access

个人视频源与弹幕 API

所有已登录的用户（包括观众）都可以：

• 添加个人视频源：在设置页面添加自己的视频源，仅对自己可见，不影响其他用户
• 管理弹幕 API：添加多个弹幕 API 端点，选择当前使用的 API（优先于系统默认）

这些数据按用户 profileId 隔离存储，切换账户后自动加载对应的个人配置。

说明：旧环境变量模式下仍然支持“仅输入密码”登录；托管账户模式下则统一改为“用户名 + 密码”登录。

方式四：高级内容独立密码

通过 PREMIUM_PASSWORD 环境变量为高级内容（/premium）设置独立的访问密码，实现与主密码的分离控制。

适合场景：给家人分享普通密码，但高级内容需要额外密码才能访问。

# Docker
docker run -d -p 3000:3000 \
  -e ADMIN_PASSWORD="admin123" \
  -e PREMIUM_PASSWORD="premium456" \
  --name kvideo kuekhaoyang/kvideo:latest

特点： - 访问 /premium 页面时需输入此专用密码 - 管理员密码和 admin/super_admin 账号也可以解锁高级内容 - 密码仅在当前浏览器会话有效，关闭浏览器后需重新输入 - 不设置此变量时，高级内容无额外密码保护

方式五：会话持久化设置

通过 PERSIST_SESSION 环境变量控制用户登录后是否在设备上记住会话：

变量名	选项	说明	默认值
PERSIST_SESSION	true / false	是否在本地浏览器持久化保存登录状态。设置为 true 时，用户只需登录一次，后续访问无需再次登录。	true

[!NOTE] 此功能仅在设置了 ADMIN_PASSWORD、ACCESS_PASSWORD 或 ACCOUNTS 时才会生效。

站点名称自定义配置

通过环境变量可以自定义站点名称、标题和描述，无需修改源代码。

可用环境变量：

变量名	说明	默认值
NEXT_PUBLIC_SITE_TITLE	浏览器标签页标题	KVideo - 视频聚合平台
NEXT_PUBLIC_SITE_DESCRIPTION	站点描述	视频聚合平台
NEXT_PUBLIC_SITE_NAME	站点头部名称	KVideo

配置示例：

Vercel 部署： 在 Vercel 项目设置中添加环境变量：

• 变量名：NEXT_PUBLIC_SITE_NAME
• 变量值：我的视频平台

Cloudflare Pages 部署： 在 Cloudflare Pages 项目设置中添加环境变量： - 变量名：NEXT_PUBLIC_SITE_NAME - 变量值：我的视频平台

本地开发： 在项目根目录创建 .env.local 文件：

NEXT_PUBLIC_SITE_NAME=我的视频平台
NEXT_PUBLIC_SITE_TITLE=我的视频 - 聚合播放平台
NEXT_PUBLIC_SITE_DESCRIPTION=专属视频聚合播放平台

[!NOTE] NEXT_PUBLIC_SITE_* 属于构建时变量。直接运行 Docker Hub 的预构建镜像时，docker run -e NEXT_PUBLIC_SITE_* ... 不会覆盖已经打包进前端的文案。

Docker 图标自定义

Docker 预构建镜像支持在运行时替换图标，无需重新构建镜像。该配置会作用于顶部 Logo 和浏览器 favicon；如果你还要同步替换安装后的 PWA 图标，请直接覆盖仓库中的 public/icon.png 后重新构建镜像。

可用环境变量：

变量名	说明
SITE_ICON_FILE	从容器内文件路径读取图标，适合 Docker 挂载，优先级高于 SITE_ICON_URL
SITE_ICON_URL	直接使用外部 URL 或站内路径作为图标

配置示例：

Docker 挂载文件（推荐）：

docker run -d -p 3000:3000 \
  -v /path/to/icon.png:/app/custom/icon.png:ro \
  -e SITE_ICON_FILE=/app/custom/icon.png \
  --name kvideo kuekhaoyang/kvideo:latest

Docker 使用 URL：

docker run -d -p 3000:3000 \
  -e SITE_ICON_URL="https://example.com/icon.png" \
  --name kvideo kuekhaoyang/kvideo:latest

Docker 使用站内路径：

docker run -d -p 3000:3000 \
  -e SITE_ICON_URL="/placeholder-poster.svg" \
  --name kvideo kuekhaoyang/kvideo:latest

自动订阅源配置

可以通过环境变量自动配置订阅源，应用启动时会自动加载并设置为自动更新。

支持两种环境变量名：SUBSCRIPTION_SOURCES（服务端） 和 NEXT_PUBLIC_SUBSCRIPTION_SOURCES（客户端构建时嵌入）。

格式： JSON 数组字符串，包含 name 和 url 字段；或直接提供订阅 URL（逗号分隔多个）。

示例：

# JSON 格式
SUBSCRIPTION_SOURCES='[{"name":"每日更新源","url":"https://example.com/api.json"},{"name":"备用源","url":"https://backup.com/api.json"}]'

# 简单 URL 格式
SUBSCRIPTION_SOURCES='https://example.com/api.json,https://backup.com/api.json'

Docker 部署：

docker run -d -p 3000:3000 -e SUBSCRIPTION_SOURCES='[{"name":"MySource","url":"..."}]' --name kvideo kuekhaoyang/kvideo:latest

Vercel 部署：

在 Vercel 项目设置中添加环境变量： - 变量名：SUBSCRIPTION_SOURCES - 变量值：[{"name":"...","url":"..."}]

Cloudflare Pages 部署：

在 Cloudflare Pages 项目设置中添加环境变量： - 变量名：`NEXT_PUBL