mirror of
https://github.com/KuekHaoYang/KVideo.git
synced 2026-08-17 09:43:43 +08:00
688 lines
27 KiB
Markdown
688 lines
27 KiB
Markdown
[](https://github.com/sky06walker/KVideo/actions/workflows/Github_Upstream_Sync.yml)
|
||
|
||
# 视频聚合平台 (KVideo)
|
||
|
||
|
||
|
||
> 一个基于 Next.js 16 构建的现代化视频聚合播放平台。采用独特的 "Liquid Glass" 设计语言，提供流畅的视觉体验和强大的视频搜索功能。
|
||
|
||
**在线体验：[https://kvideo.pages.dev/](https://kvideo.pages.dev/)**
|
||
|
||
[](https://nextjs.org/)
|
||
[](https://react.dev/)
|
||
[](https://tailwindcss.com/)
|
||
[](https://www.typescriptlang.org/)
|
||
[](LICENSE)
|
||
|
||
## 项目简介
|
||
|
||
**KVideo** 是一个高性能、现代化的视频聚合与播放应用，专注于提供极致的用户体验和视觉设计。本项目利用 Next.js 16 的最新特性，结合 React 19 和 Tailwind CSS v4，打造了一个既美观又强大的视频浏览平台。
|
||
|
||
### 核心设计理念：Liquid Glass（液态玻璃）
|
||
|
||
项目的视觉设计基于 **"Liquid Glass"** 设计系统，这是一套融合了以下特性的现代化 UI 设计语言：
|
||
|
||
- **玻璃拟态效果**：通过 `backdrop-filter` 实现的磨砂半透明效果，让 UI 元素如同真实的玻璃材质
|
||
- **通用柔和度**：统一使用 `rounded-2xl` 和 `rounded-full` 两种圆角半径，创造和谐的视觉体验
|
||
- **光影交互**：悬停和聚焦状态下的内发光效果，模拟光线被"捕获"的物理现象
|
||
- **流畅动画**：基于物理的 `cubic-bezier` 曲线，实现自然的加速和减速过渡
|
||
- **深度层级**：清晰的 z-axis 层次结构，增强空间感和交互反馈
|
||
|
||
## 核心功能
|
||
|
||
### 智能视频播放
|
||
|
||
- **HLS 流媒体支持**：基于 [hls.js](https://github.com/video-dev/hls.js/) 原生支持 HLS (.m3u8) 格式，提供流畅的视频播放体验
|
||
- **播放控制**：完整的播放控制功能，包括进度条、音量控制、播放速度调节、全屏模式等
|
||
- **自动跳过片头/片尾**：可设置自动跳过片头和片尾的秒数
|
||
- **自动连播**：支持自动播放下一集
|
||
- **移动端优化**：专门为移动设备优化的播放器界面和双击手势控制
|
||
- **Chromecast 投屏**：支持通过 Google Cast 投屏到电视等设备
|
||
- **全屏模式选择**：支持系统全屏和网页全屏两种模式
|
||
- **代理播放**：三种代理模式（智能重试、仅直连、总是代理），灵活应对不同网络环境
|
||
- **卡顿检测**：自动检测播放卡顿并提示
|
||
|
||
### 多源并行搜索
|
||
|
||
- **聚合搜索引擎**：同时在多个视频源中并行搜索，大幅提升搜索速度
|
||
- **自定义视频源**：支持添加、编辑和管理自定义视频源
|
||
- **订阅源管理**：支持通过 JSON 链接批量导入和自动更新视频源
|
||
- **智能解析**：统一的解析器系统，自动处理不同源的数据格式
|
||
- **搜索历史**：自动保存搜索历史，支持快速重新搜索
|
||
- **搜索结果显示**：支持默认显示和合并同名源两种模式
|
||
- **实时延迟监测**：可选实时显示各源的网络延迟
|
||
- **源过滤**：支持按源和类型筛选搜索结果
|
||
|
||
### 豆瓣集成
|
||
|
||
- **电影 & 电视剧分类**：支持在电影和电视剧之间无缝切换，方便查找不同类型的影视资源
|
||
- **详细影视信息**：自动获取豆瓣评分、演员阵容、剧情简介等详细信息
|
||
- **推荐系统**：基于豆瓣数据的相关推荐
|
||
- **自定义标签管理**：支持拖拽排序的标签管理器，自定义首页推荐分类
|
||
- **可点击演员/导演**：播放页面的演员、导演名字可直接点击搜索其他作品
|
||
|
||
### 个性化推荐
|
||
|
||
- **基于观看历史**：根据观看历史自动分析偏好，推荐相关影视内容
|
||
- **智能分析**：分析最常观看的类型、演员和地区，生成精准推荐
|
||
- **标签集成**：推荐作为首个标签「为你推荐」出现在标签栏中（需观看 2 部以上作品）
|
||
- **自动加载**：无限滚动自动加载更多推荐内容
|
||
- **独立模式**：普通模式和高级模式的推荐互相独立
|
||
- **缓存优化**：推荐结果缓存 30 分钟，避免重复请求
|
||
|
||
### 收藏管理
|
||
|
||
- **一键收藏**：在搜索结果和播放页面快速收藏视频
|
||
- **收藏列表**：独立的收藏侧边栏，快速访问已收藏的视频
|
||
- **普通/高级隔离**：普通模式和高级模式的收藏互相独立
|
||
- **数据隔离**：多账户场景下，每个用户拥有独立的收藏数据
|
||
|
||
### 观看历史管理
|
||
|
||
- **自动记录**：自动记录观看进度和历史
|
||
- **断点续播**：从上次观看位置继续播放
|
||
- **历史管理**：支持删除单条历史或清空全部历史
|
||
- **隐私保护**：所有数据存储在本地，不上传到服务器
|
||
|
||
### 响应式设计
|
||
|
||
- **全端适配**：完美支持桌面、平板、移动设备和 TV/机顶盒
|
||
- **移动优先**：专门的移动端组件和交互设计
|
||
- **触摸优化**：针对触摸屏优化的手势和交互
|
||
- **TV 适配**：遥控器方向键导航和大屏 UI 优化
|
||
|
||
### 主题系统
|
||
|
||
- **深色/浅色模式**：支持系统级主题切换
|
||
- **动态主题**：基于 CSS Variables 的动态主题系统
|
||
- **无缝过渡**：主题切换时的平滑过渡动画
|
||
|
||
### PWA 支持
|
||
|
||
- **可安装应用**：支持将 KVideo 安装为独立应用
|
||
- **Service Worker**：离线缓存和资源预加载
|
||
- **全屏体验**：独立应用模式下的沉浸式体验
|
||
|
||
### 无障碍设计
|
||
|
||
- **键盘导航**：完整的键盘快捷键支持（播放控制、音量、进度等）
|
||
- **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` 常量指向你的部署实例
|
||
|
||
### 广告过滤
|
||
|
||
- **多模式选择**：支持关闭、关键词过滤、智能启发式过滤(Beta)和激进模式
|
||
- **UI 集成**：在播放器设置菜单中直接切换模式，实时生效
|
||
- **自定义关键词**：支持通过环境变量或文件扩展过滤关键词
|
||
- **高性能**：基于流式处理，对播放加载速度几乎无影响
|
||
|
||
### 弹幕 (Danmaku)
|
||
|
||
- **弹幕聚合**：接入自建弹幕聚合 API（兼容 [danmu_api](https://github.com/huangxd-/danmu_api) 格式），自动匹配当前播放内容
|
||
- **Canvas 渲染**：基于 Canvas 的高性能弹幕渲染，支持数百条弹幕同时滚动，不影响播放交互
|
||
- **滚动/顶部/底部弹幕**：支持三种弹幕类型，自动分配轨道防止重叠
|
||
- **自定义显示**：可调节弹幕透明度（10%-100%）和字号（14/18/20/24/28px）
|
||
- **播放器联动**：暂停时弹幕冻结，跳转时自动清除，全屏模式下正常显示
|
||
- **环境变量预设**：可通过 `NEXT_PUBLIC_DANMAKU_API_URL` 为所有用户预设弹幕 API 地址
|
||
|
||
### 数据管理
|
||
|
||
- **设置导出/导入**：支持将所有设置导出为 JSON 文件，方便备份和迁移
|
||
- **滚动位置记忆**：退出或刷新页面后，自动恢复到之前的滚动位置
|
||
- **返回顶部**：一键返回页面顶部
|
||
|
||
## 隐私保护
|
||
|
||
本应用注重用户隐私：
|
||
|
||
- **本地存储**：所有数据存储在本地浏览器中
|
||
- **无服务器数据**：不收集或上传任何用户数据
|
||
- **自定义源**：用户可自行配置视频源
|
||
- **数据隔离**：多账户场景下，每个用户的数据（历史、收藏、设置）完全隔离
|
||
|
||
## 账户与访问控制
|
||
|
||
KVideo 支持基于环境变量的账户认证系统，支持角色区分（管理员/观众）和数据隔离。
|
||
|
||
### 方式一：单管理员密码
|
||
|
||
通过 `ADMIN_PASSWORD` 环境变量设置管理员密码：
|
||
|
||
```bash
|
||
# Docker
|
||
docker run -d -p 3000:3000 -e ADMIN_PASSWORD=your_password --name kvideo kuekhaoyang/kvideo:latest
|
||
```
|
||
|
||
登录后自动获得管理员权限，可管理所有设置。
|
||
|
||
> **向后兼容**：`ACCESS_PASSWORD` 环境变量仍然有效，当 `ADMIN_PASSWORD` 未设置时，`ACCESS_PASSWORD` 将作为管理员密码使用。
|
||
|
||
### 方式二：多账户系统
|
||
|
||
通过 `ACCOUNTS` 环境变量配置多个账户，每个账户拥有独立的数据空间（收藏、历史、设置等）。
|
||
|
||
**格式：** `密码:名称[:角色]`，多个账户用逗号分隔。角色可选 `admin`（管理员）或 `viewer`（观众，默认）。
|
||
|
||
```bash
|
||
# Docker
|
||
docker run -d -p 3000:3000 \
|
||
-e ACCOUNTS="pass1:张三:admin,pass2:李四:viewer,pass3:王五" \
|
||
--name kvideo kuekhaoyang/kvideo:latest
|
||
```
|
||
|
||
**特点：**
|
||
- 每个账户拥有独立的收藏、历史和设置数据
|
||
- 管理员可管理源和设置，观众仅可查看和播放
|
||
- 可同时配置 `ADMIN_PASSWORD`（作为超级管理员入口）
|
||
|
||
### 方式三：会话持久化设置
|
||
|
||
通过 `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`
|
||
- 变量值：`我的视频平台`
|
||
|
||
**Docker 部署：**
|
||
```bash
|
||
docker run -d -p 3000:3000 \
|
||
-e NEXT_PUBLIC_SITE_NAME="我的视频平台" \
|
||
-e NEXT_PUBLIC_SITE_TITLE="我的视频 - 聚合播放平台" \
|
||
-e NEXT_PUBLIC_SITE_DESCRIPTION="专属视频聚合播放平台" \
|
||
--name kvideo kuekhaoyang/kvideo:latest
|
||
```
|
||
|
||
**本地开发：**
|
||
在项目根目录创建 `.env.local` 文件：
|
||
```env
|
||
NEXT_PUBLIC_SITE_NAME=我的视频平台
|
||
NEXT_PUBLIC_SITE_TITLE=我的视频 - 聚合播放平台
|
||
NEXT_PUBLIC_SITE_DESCRIPTION=专属视频聚合播放平台
|
||
```
|
||
|
||
## 自动订阅源配置
|
||
|
||
可以通过环境变量自动配置订阅源，应用启动时会自动加载并设置为自动更新。
|
||
|
||
支持两种环境变量名：`SUBSCRIPTION_SOURCES`（服务端） 和 `NEXT_PUBLIC_SUBSCRIPTION_SOURCES`（客户端构建时嵌入）。
|
||
|
||
**格式：** JSON 数组字符串，包含 `name` 和 `url` 字段；或直接提供订阅 URL（逗号分隔多个）。
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 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 部署：**
|
||
|
||
```bash
|
||
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_PUBLIC_SUBSCRIPTION_SOURCES`
|
||
- 变量值：`[{"name":"...","url":"..."}]`
|
||
|
||
## 广告过滤关键词配置
|
||
|
||
通过环境变量自定义广告过滤关键词，用于在 HLS 播放时识别和过滤广告片段。
|
||
|
||
| 变量名 | 说明 |
|
||
|--------|------|
|
||
| `AD_KEYWORDS` 或 `NEXT_PUBLIC_AD_KEYWORDS` | 广告关键词，逗号或换行分隔 |
|
||
| `AD_KEYWORDS_FILE` | 广告关键词文件路径（适用于 Docker 挂载） |
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 环境变量方式
|
||
AD_KEYWORDS="ad,sponsor,preroll,midroll"
|
||
|
||
# Docker 挂载文件方式
|
||
docker run -d -p 3000:3000 \
|
||
-v /path/to/keywords.txt:/app/keywords.txt \
|
||
-e AD_KEYWORDS_FILE=/app/keywords.txt \
|
||
--name kvideo kuekhaoyang/kvideo:latest
|
||
```
|
||
|
||
## 弹幕 API 配置
|
||
|
||
通过环境变量预设弹幕聚合 API 地址，用户无需手动配置即可使用弹幕功能。
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `NEXT_PUBLIC_DANMAKU_API_URL` | 弹幕聚合 API 地址 | - |
|
||
|
||
需要自建或使用兼容 [danmu_api](https://github.com/huangxd-/danmu_api) 格式的弹幕聚合服务。
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# Docker
|
||
docker run -d -p 3000:3000 \
|
||
-e NEXT_PUBLIC_DANMAKU_API_URL="https://your-danmu-api.example.com" \
|
||
--name kvideo kuekhaoyang/kvideo:latest
|
||
```
|
||
|
||
设置后用户在播放器菜单中即可直接开启弹幕，也可在设置页面中覆盖此地址。
|
||
|
||
## 自定义源 JSON 格式
|
||
|
||
如果你想创建自己的订阅源或批量导入源，可以使用以下 JSON 格式。
|
||
|
||
**基本结构：**
|
||
|
||
可以是单个对象数组，也可以是包含 `sources` 或 `list` 字段的对象。
|
||
|
||
**源对象字段说明：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | string | 是 | 唯一标识符，建议使用英文 |
|
||
| `name` | string | 是 | 显示名称 |
|
||
| `baseUrl` | string | 是 | API 地址 (例如: `https://example.com/api.php/provide/vod`) |
|
||
| `group` | string | 否 | 分组，可选值: `"normal"` (默认) 或 `"premium"` |
|
||
| `enabled` | boolean | 否 | 是否启用，默认为 `true` |
|
||
| `priority` | number | 否 | 优先级，数字越小优先级越高，默认为 1 |
|
||
|
||
**示例 JSON：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "my_source_1",
|
||
"name": "我的精选源",
|
||
"baseUrl": "https://api.example.com/vod",
|
||
"group": "normal",
|
||
"priority": 1
|
||
},
|
||
{
|
||
"id": "premium_source_1",
|
||
"name": "特殊资源",
|
||
"baseUrl": "https://api.premium-source.com/vod",
|
||
"group": "premium",
|
||
"enabled": true
|
||
}
|
||
]
|
||
```
|
||
|
||
### 重要的区别说明：订阅源 vs 视频源
|
||
|
||
**这是一个常见的误区，请仔细阅读：**
|
||
|
||
- **视频源 (Source)**：
|
||
- 指向单个 CMS/App API 接口
|
||
- 例如：`https://api.example.com/vod`
|
||
- 这种链接**不能**直接作为"订阅"添加
|
||
- 只能在"自定义源管理"中作为单个源添加
|
||
|
||
- **订阅源 (Subscription)**：
|
||
- 指向一个 **JSON 文件**（如上面的示例）的 URL
|
||
- 这个 JSON 文件里包含了一个或多个视频源的列表
|
||
- 例如：`https://mysite.com/kvideo-sources.json`
|
||
- 这是一个**配置文件**的链接，不是视频 API 的链接
|
||
- 只有这种返回 JSON 列表的链接才能在"订阅管理"中添加
|
||
|
||
> **简单来说**：如果你只有一个 m3u8 或 API 接口地址，请去"自定义源"添加。如果你有一个包含多个源的 JSON 文件链接，请去"订阅管理"添加。
|
||
|
||
## 全部环境变量参考
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `ADMIN_PASSWORD` | 管理员密码 | - |
|
||
| `ACCESS_PASSWORD` | 访问密码（向后兼容，等同于 `ADMIN_PASSWORD`） | - |
|
||
| `ACCOUNTS` | 多账户配置，格式：`密码:名称[:角色]`，逗号分隔 | - |
|
||
| `PERSIST_SESSION` | 是否持久化登录会话 | `true` |
|
||
| `NEXT_PUBLIC_SITE_TITLE` | 浏览器标签页标题 | `KVideo - 视频聚合平台` |
|
||
| `NEXT_PUBLIC_SITE_DESCRIPTION` | 站点描述 | `视频聚合平台` |
|
||
| `NEXT_PUBLIC_SITE_NAME` | 站点头部名称 | `KVideo` |
|
||
| `SUBSCRIPTION_SOURCES` | 自动订阅源配置（服务端） | - |
|
||
| `NEXT_PUBLIC_SUBSCRIPTION_SOURCES` | 自动订阅源配置（客户端） | - |
|
||
| `AD_KEYWORDS` / `NEXT_PUBLIC_AD_KEYWORDS` | 广告过滤关键词 | - |
|
||
| `AD_KEYWORDS_FILE` | 广告关键词文件路径 | - |
|
||
| `NEXT_PUBLIC_DANMAKU_API_URL` | 弹幕聚合 API 地址 | - |
|
||
|
||
## 技术栈
|
||
|
||
### 前端核心
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| **[Next.js](https://nextjs.org/)** | 16.1.6 | React 框架，使用 App Router |
|
||
| **[React](https://react.dev/)** | 19.2.4 | UI 组件库 |
|
||
| **[TypeScript](https://www.typescriptlang.org/)** | 5.x | 类型安全的 JavaScript |
|
||
| **[Tailwind CSS](https://tailwindcss.com/)** | 4.x | 实用优先的 CSS 框架 |
|
||
| **[Zustand](https://github.com/pmndrs/zustand)** | 5.x | 轻量级状态管理 |
|
||
| **[hls.js](https://github.com/video-dev/hls.js/)** | 1.x | HLS 流媒体播放引擎 |
|
||
| **[Lucide React](https://lucide.dev/)** | 0.x | 图标库 |
|
||
| **[@dnd-kit](https://dndkit.com/)** | 6.x | 拖拽交互（标签排序等） |
|
||
|
||
### 开发工具
|
||
|
||
- **ESLint 10**：代码质量检查
|
||
- **PostCSS 8**：CSS 处理器
|
||
- **Vercel Analytics**：性能监控和分析
|
||
- **Cloudflare Pages**：边缘部署支持
|
||
|
||
### 架构特点
|
||
|
||
- **App Router**：Next.js 的新路由系统，支持服务端组件和流式渲染
|
||
- **API Routes**：内置 API 端点，处理认证、豆瓣数据和视频源代理
|
||
- **Service Worker**：PWA 支持和资源缓存
|
||
- **Server Components**：优化首屏加载性能
|
||
- **Client Components**：复杂交互和状态管理
|
||
- **Edge Runtime**：API 路由运行在 Edge Runtime 上，提供更低延迟
|
||
|
||
## 快速部署
|
||
|
||
### 部署到自己的服务器
|
||
|
||
#### 选项 1：Vercel 一键部署（推荐）
|
||
|
||
[](https://vercel.com/new/clone?repository-url=https://github.com/KuekHaoYang/KVideo)
|
||
|
||
1. 点击上方按钮
|
||
2. 连接你的 GitHub 账号
|
||
3. Vercel 会自动检测 Next.js 项目并部署
|
||
4. 几分钟后即可访问你自己的 KVideo 实例
|
||
|
||
#### 选项 2：Cloudflare Pages 部署 (推荐)
|
||
|
||
此方法完全免费且速度极快，是部署本项目的最佳选择。
|
||
|
||
1. **Fork 本仓库**：首先将项目 Fork 到你的 GitHub 账户。
|
||
|
||
2. **创建项目**：
|
||
- 点击访问 [**Cloudflare Pages - Connect Git**](https://dash.cloudflare.com/?to=/:account/pages/new/provider/github)。
|
||
- 如果未连接 GitHub，请点击 **Connect GitHub**；若已连接，直接选择你刚刚 Fork 的 `KVideo` 项目并点击 **Begin setup**。
|
||
|
||
3. **配置构建参数**：
|
||
- **Project name**: 默认为 `kvideo` (建议保持不变，后续链接基于此名称)
|
||
- **Framework Preset**: 选择 `Next.js`
|
||
- **Build command**: 输入 `npm run pages:build`
|
||
- **Build output directory**: 输入 `.vercel/output/static`
|
||
- 点击 **Save and Deploy**。
|
||
|
||
4. **关键步骤：修复运行时环境**
|
||
> *注意：此时部署虽然显示"Success"，但你会发现访问网页会报错。这是因为缺少必要的兼容性配置。请按以下步骤修复：*
|
||
|
||
- 进入 **[项目设置页面](https://dash.cloudflare.com/?to=/:account/pages/view/kvideo/settings/production)** (如果你的项目名不是 kvideo，请在控制台手动查找 Settings -> Functions)。
|
||
- 拉到页面底部找到 **Compatibility flags** 部分。
|
||
- 添加标志：`nodejs_compat`
|
||
|
||
5. **重试部署 (生效配置)**：
|
||
- 回到 **[项目概览页面](https://dash.cloudflare.com/?to=/:account/pages/view/kvideo)**。
|
||
- 在 **Deployments** 列表中，找到最新的那次部署。
|
||
- 点击右侧的三个点 `...` 菜单，选择 **Retry deployment**。
|
||
- 等待新的部署完成后，你的 KVideo 就部署成功了！
|
||
|
||
#### 选项 3：Docker 部署
|
||
|
||
**从 Docker Hub 拉取（最简单）：**
|
||
|
||
```bash
|
||
# 拉取最新版本
|
||
docker pull kuekhaoyang/kvideo:latest
|
||
docker run -d -p 3000:3000 --name kvideo kuekhaoyang/kvideo:latest
|
||
```
|
||
|
||
应用将在 `http://localhost:3000` 启动。
|
||
|
||
> **多架构支持**：镜像支持 2 种主流平台架构：
|
||
> - `linux/amd64` - Intel/AMD 64位（大多数服务器、PC、Intel Mac）
|
||
> - `linux/arm64` - ARM 64位（Apple Silicon Mac、AWS Graviton、树莓派 4/5）
|
||
|
||
**自己构建镜像：**
|
||
|
||
```bash
|
||
git clone https://github.com/KuekHaoYang/KVideo.git
|
||
cd KVideo
|
||
docker build -t kvideo .
|
||
docker run -d -p 3000:3000 --name kvideo kvideo
|
||
```
|
||
|
||
**使用 Docker Compose：**
|
||
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
#### 选项 4：传统 Node.js 部署
|
||
|
||
```bash
|
||
# 1. 克隆仓库
|
||
git clone https://github.com/KuekHaoYang/KVideo.git
|
||
cd KVideo
|
||
|
||
# 2. 安装依赖
|
||
npm install
|
||
|
||
# 3. 构建项目
|
||
npm run build
|
||
|
||
# 4. 启动生产服务器
|
||
npm start
|
||
```
|
||
|
||
应用将在 `http://localhost:3000` 启动。
|
||
|
||
#### 选项 5：Android TV APK 构建
|
||
|
||
项目内置了一个轻量的 Android TV WebView 壳应用，可以将 KVideo 打包成 APK 安装到 Android TV 或机顶盒上。
|
||
|
||
**前置要求：**
|
||
|
||
- [Android Studio](https://developer.android.com/studio)（推荐）或 Android SDK Command-line Tools
|
||
- JDK 17+
|
||
|
||
**步骤：**
|
||
|
||
1. **修改目标 URL**：编辑 `android-tv/app/src/main/java/com/kvideo/tv/MainActivity.kt`，将 `KVIDEO_URL` 改为你的部署地址：
|
||
```kotlin
|
||
private const val KVIDEO_URL = "https://your-kvideo-instance.com"
|
||
```
|
||
|
||
2. **使用 Android Studio 构建（推荐）**：
|
||
- 用 Android Studio 打开 `android-tv/` 目录
|
||
- 等待 Gradle 同步完成
|
||
- 点击 **Build → Build Bundle(s) / APK(s) → Build APK(s)**
|
||
- APK 输出在 `android-tv/app/build/outputs/apk/debug/app-debug.apk`
|
||
|
||
3. **使用命令行构建**：
|
||
```bash
|
||
cd android-tv
|
||
./gradlew assembleDebug
|
||
```
|
||
APK 输出在 `app/build/outputs/apk/debug/app-debug.apk`
|
||
|
||
4. **安装到 Android TV**：
|
||
```bash
|
||
adb install app/build/outputs/apk/debug/app-debug.apk
|
||
```
|
||
或通过 U 盘、文件管理器等方式侧载安装。
|
||
|
||
> **注意**：此 APK 是一个 WebView 壳应用，需要你的 KVideo 实例已经部署并可访问。APK 本身不包含 KVideo 代码，仅作为 TV 端的浏览器入口。
|
||
|
||
#### 选项 6：Apple TV 应用构建
|
||
|
||
项目内置了一个轻量的 tvOS WKWebView 壳应用，可以将 KVideo 安装到 Apple TV 上。
|
||
|
||
**前置要求：**
|
||
|
||
- macOS + Xcode 15+
|
||
- Apple Developer 账号（免费账号即可侧载到个人设备）
|
||
|
||
**步骤：**
|
||
|
||
1. **创建 Xcode 项目**：打开 Xcode → **File → New → Project** → 选择 **tvOS → App** → 设置 Product Name 为 `KVideoTV`，Interface 选 **SwiftUI**，Language 选 **Swift**
|
||
|
||
2. **替换源文件**：将项目中 `apple-tv/KVideoTV/KVideoTV/` 目录下的 `KVideoTVApp.swift` 和 `ContentView.swift` 复制替换 Xcode 生成的同名文件
|
||
|
||
3. **修改目标 URL**：编辑 `ContentView.swift`，将 `kvideoURL` 改为你的部署地址：
|
||
```swift
|
||
let kvideoURL = "https://your-kvideo-instance.com"
|
||
```
|
||
|
||
4. **设置部署目标**：将 Deployment Target 设置为 **tvOS 16.0** 或更高
|
||
|
||
5. **构建运行**：连接 Apple TV（或使用 tvOS 模拟器），按 **Cmd+R** 构建运行
|
||
|
||
**工作原理：**
|
||
- 全屏 `WKWebView` 加载 KVideo URL
|
||
- 页面加载后自动注入 `tv-mode` CSS 类，激活 TV 优化样式
|
||
- Apple TV 遥控器滑动手势映射为滚动，点击映射为聚焦/选择
|
||
- Menu 按钮支持网页后退导航
|
||
|
||
> **注意**：Apple TV 应用如果仅是 Web 壳应用，不可上架 App Store。此功能仅供个人侧载使用。也可以直接从 iPhone/iPad/Mac 使用 AirPlay 投屏，无需此应用。
|
||
|
||
## 如何更新
|
||
|
||
### Vercel 部署
|
||
|
||
Vercel 会自动检测 GitHub 仓库的更新并重新部署，无需手动操作。
|
||
|
||
### Docker 部署
|
||
|
||
当有新版本发布时：
|
||
|
||
```bash
|
||
# 停止并删除旧容器
|
||
docker stop kvideo
|
||
docker rm kvideo
|
||
|
||
# 拉取最新镜像
|
||
docker pull kuekhaoyang/kvideo:latest
|
||
|
||
# 运行新容器
|
||
docker run -d -p 3000:3000 --name kvideo kuekhaoyang/kvideo:latest
|
||
```
|
||
|
||
### Node.js 部署
|
||
|
||
```bash
|
||
cd KVideo
|
||
git pull origin main
|
||
npm install
|
||
npm run build
|
||
npm start
|
||
```
|
||
|
||
> **自动化部署**：本项目使用 GitHub Actions 自动构建和发布 Docker 镜像。每次代码推送到 main 分支时，会自动构建多架构镜像并推送到 Docker Hub。
|
||
|
||
## 贡献代码
|
||
|
||
我们非常欢迎各种形式的贡献！无论是报告 Bug、提出新功能建议、改进文档，还是提交代码，你的每一份贡献都让这个项目变得更好。
|
||
|
||
**想要参与开发？请查看 [贡献指南](CONTRIBUTING.md) 了解详细的开发规范和流程。**
|
||
|
||
快速开始：
|
||
1. **报告 Bug**：[提交 Issue](https://github.com/KuekHaoYang/KVideo/issues)
|
||
2. **功能建议**：在 Issues 中提出你的想法
|
||
3. **代码贡献**：Fork → Branch → PR
|
||
4. **文档改进**：直接提交 PR
|
||
|
||
## 许可证
|
||
|
||
本项目基于 [MIT 许可证](LICENSE) 开源。
|
||
|
||
## 致谢
|
||
|
||
感谢以下开源项目：
|
||
|
||
- [Next.js](https://nextjs.org/) - React 框架
|
||
- [Tailwind CSS](https://tailwindcss.com/) - CSS 框架
|
||
- [Zustand](https://github.com/pmndrs/zustand) - 状态管理
|
||
- [React](https://react.dev/) - UI 库
|
||
- [hls.js](https://github.com/video-dev/hls.js/) - HLS 播放引擎
|
||
- [Lucide](https://lucide.dev/) - 图标库
|
||
- [dnd-kit](https://dndkit.com/) - 拖拽交互
|
||
|
||
## 联系方式
|
||
|
||
- **作者**：[KuekHaoYang](https://github.com/KuekHaoYang)
|
||
- **项目主页**：[https://github.com/KuekHaoYang/KVideo](https://github.com/KuekHaoYang/KVideo)
|
||
- **问题反馈**：[GitHub Issues](https://github.com/KuekHaoYang/KVideo/issues)
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
Made with ❤️ by <a href="https://github.com/KuekHaoYang">KuekHaoYang</a>
|
||
<br>
|
||
如果这个项目对你有帮助，请考虑给一个 ⭐️
|
||
</div>
|
||
|
||
## Star History
|
||
|
||
[](https://www.star-history.com/#KuekHaoYang/KVideo&type=date&legend=top-left)
|