diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b1c8176..d5d9d5c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,7 +62,7 @@ | 工具 | 最低版本 | 推荐版本 | 检查命令 | |------|----------|----------|----------| -| **Node.js** | 20.0.0 | 20.x LTS | `node --version` | +| **Node.js** | 20.0.0 | 22.x LTS | `node --version` | | **npm** | 9.0.0 | 10.x | `npm --version` | | **Git** | 2.30.0 | 最新版本 | `git --version` | @@ -846,10 +846,6 @@ find . -type f -not -path "*/node_modules/*" -not -path "*/.next/*" -not -path " - 模块化 注:系统文件(如 README.md、CONTRIBUTING.md 等文档)不受此限制。 -- 提取组件 -- 提取 Hook -- 提取工具函数 -- 模块化 ### Q3: 我的 PR 多久会被审查? diff --git a/README.md b/README.md index e68cbc5..be9a3b9 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,15 @@ > 一个基于 Next.js 16 构建的现代化视频聚合播放平台。采用独特的 "Liquid Glass" 设计语言,提供流畅的视觉体验和强大的视频搜索功能。 -**🌐 在线体验:[https://kvideo.pages.dev/](https://kvideo.pages.dev/)** +**在线体验:[https://kvideo.pages.dev/](https://kvideo.pages.dev/)** -[](https://nextjs.org/) +[](https://nextjs.org/) [](https://react.dev/) [](https://tailwindcss.com/) [](https://www.typescriptlang.org/) [](LICENSE) -## 📖 项目简介 +## 项目简介 **KVideo** 是一个高性能、现代化的视频聚合与播放应用,专注于提供极致的用户体验和视觉设计。本项目利用 Next.js 16 的最新特性,结合 React 19 和 Tailwind CSS v4,打造了一个既美观又强大的视频浏览平台。 @@ -28,123 +28,151 @@ - **流畅动画**:基于物理的 `cubic-bezier` 曲线,实现自然的加速和减速过渡 - **深度层级**:清晰的 z-axis 层次结构,增强空间感和交互反馈 -## ✨ 核心功能 +## 核心功能 -### 🎥 智能视频播放 +### 智能视频播放 -- **HLS 流媒体支持**:原生支持 HLS (.m3u8) 格式,提供流畅的视频播放体验 -- **智能缓存机制**:Service Worker 驱动的智能缓存系统,自动预加载和缓存视频片段 -- **后台下载**:利用观看历史,在后台自动下载历史视频,确保离线也能观看 +- **HLS 流媒体支持**:基于 [hls.js](https://github.com/video-dev/hls.js/) 原生支持 HLS (.m3u8) 格式,提供流畅的视频播放体验 - **播放控制**:完整的播放控制功能,包括进度条、音量控制、播放速度调节、全屏模式等 -- **移动端优化**:专门为移动设备优化的播放器界面和手势控制 +- **自动跳过片头/片尾**:可设置自动跳过片头和片尾的秒数 +- **自动连播**:支持自动播放下一集 +- **移动端优化**:专门为移动设备优化的播放器界面和双击手势控制 +- **Chromecast 投屏**:支持通过 Google Cast 投屏到电视等设备 +- **全屏模式选择**:支持系统全屏和网页全屏两种模式 +- **代理播放**:三种代理模式(智能重试、仅直连、总是代理),灵活应对不同网络环境 +- **卡顿检测**:自动检测播放卡顿并提示 -### 🔍 多源并行搜索 +### 多源并行搜索 - **聚合搜索引擎**:同时在多个视频源中并行搜索,大幅提升搜索速度 - **自定义视频源**:支持添加、编辑和管理自定义视频源 +- **订阅源管理**:支持通过 JSON 链接批量导入和自动更新视频源 - **智能解析**:统一的解析器系统,自动处理不同源的数据格式 - **搜索历史**:自动保存搜索历史,支持快速重新搜索 -- **结果排序**:支持按评分、时间、相关性等多种方式排序搜索结果 +- **搜索结果显示**:支持默认显示和合并同名源两种模式 +- **实时延迟监测**:可选实时显示各源的网络延迟 +- **源过滤**:支持按源和类型筛选搜索结果 -### 🎬 豆瓣集成 +### 豆瓣集成 - **电影 & 电视剧分类**:支持在电影和电视剧之间无缝切换,方便查找不同类型的影视资源 - **详细影视信息**:自动获取豆瓣评分、演员阵容、剧情简介等详细信息 - **推荐系统**:基于豆瓣数据的相关推荐 -- **专业评价**:展示豆瓣用户评价和专业影评 +- **自定义标签管理**:支持拖拽排序的标签管理器,自定义首页推荐分类 -### 💾 观看历史管理 +### 收藏管理 + +- **一键收藏**:在搜索结果和播放页面快速收藏视频 +- **收藏列表**:独立的收藏侧边栏,快速访问已收藏的视频 +- **普通/高级隔离**:普通模式和高级模式的收藏互相独立 +- **数据隔离**:多账户场景下,每个用户拥有独立的收藏数据 + +### 观看历史管理 - **自动记录**:自动记录观看进度和历史 - **断点续播**:从上次观看位置继续播放 - **历史管理**:支持删除单条历史或清空全部历史 - **隐私保护**:所有数据存储在本地,不上传到服务器 -### 📱 响应式设计 +### 响应式设计 - **全端适配**:完美支持桌面、平板和移动设备 - **移动优先**:专门的移动端组件和交互设计 - **触摸优化**:针对触摸屏优化的手势和交互 -### 🌙 主题系统 +### 主题系统 - **深色/浅色模式**:支持系统级主题切换 - **动态主题**:基于 CSS Variables 的动态主题系统 - **无缝过渡**:主题切换时的平滑过渡动画 -### ⌨️ 无障碍设计 +### PWA 支持 -- **键盘导航**:完整的键盘快捷键支持 -- **ARIA 标签**:符合 WCAG 2.2 标准的无障碍实现 +- **可安装应用**:支持将 KVideo 安装为独立应用 +- **Service Worker**:离线缓存和资源预加载 +- **全屏体验**:独立应用模式下的沉浸式体验 + +### 无障碍设计 + +- **键盘导航**:完整的键盘快捷键支持(播放控制、音量、进度等) +- **ARIA 标签**:符合 WCAG 标准的无障碍实现 - **语义化 HTML**:使用语义化标签提升可访问性 -- **高对比度**:确保 4.5:1 的文字对比度 -### 💎 高级模式 +### 高级模式 - **独立入口**:在浏览器地址栏直接输入 `/premium` 即可进入独立的高级视频专区 - **内容隔离**:高级内容与普通内容完全物理隔离,互不干扰 - **专属设置**:拥有独立的内容源管理和功能设置 -### 🛡️ 广告过滤 -- **多模式选择**:支持关闭、关键词过滤、智能启发式过滤(Beta)和激进模式。 -- **UI 集成**:在播放器设置菜单中直接切换模式,实时生效。 -- **自定义关键词**:支持通过环境变量扩展过滤关键词。 -- **高性能**:基于流式处理,对播放加载速度几乎无影响。 +### 广告过滤 -## 🔐 隐私保护 +- **多模式选择**:支持关闭、关键词过滤、智能启发式过滤(Beta)和激进模式 +- **UI 集成**:在播放器设置菜单中直接切换模式,实时生效 +- **自定义关键词**:支持通过环境变量或文件扩展过滤关键词 +- **高性能**:基于流式处理,对播放加载速度几乎无影响 + +### 数据管理 + +- **设置导出/导入**:支持将所有设置导出为 JSON 文件,方便备份和迁移 +- **滚动位置记忆**:退出或刷新页面后,自动恢复到之前的滚动位置 +- **返回顶部**:一键返回页面顶部 + +## 隐私保护 本应用注重用户隐私: - **本地存储**:所有数据存储在本地浏览器中 - **无服务器数据**:不收集或上传任何用户数据 - **自定义源**:用户可自行配置视频源 +- **数据隔离**:多账户场景下,每个用户的数据(历史、收藏、设置)完全隔离 -## 🔒 密码访问控制 +## 账户与访问控制 -KVideo 支持两种密码保护方式: +KVideo 支持基于环境变量的账户认证系统,支持角色区分(管理员/观众)和数据隔离。 -### 方式一:本地保存密码 +### 方式一:单管理员密码 -在设置页面中启用密码访问,并添加密码: - -- **设备独立**:仅在当前浏览器/设备有效 -- **可管理**:可随时添加或删除 -- **多密码支持**:可设置多个有效密码 - -### 方式二:环境变量密码(推荐用于部署) - -通过 `ACCESS_PASSWORD` 环境变量设置全局密码: - -**Docker 部署:** +通过 `ADMIN_PASSWORD` 环境变量设置管理员密码: ```bash -docker run -d -p 3000:3000 -e ACCESS_PASSWORD=your_premium_password --name kvideo kuekhaoyang/kvideo:latest +# Docker +docker run -d -p 3000:3000 -e ADMIN_PASSWORD=your_password --name kvideo kuekhaoyang/kvideo:latest ``` -**Vercel 部署:** +登录后自动获得管理员权限,可管理所有设置。 -在 Vercel 项目设置中添加环境变量: -- 变量名:`ACCESS_PASSWORD` -- 变量值:你的密码 +> **向后兼容**:`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 +``` **特点:** -- **全局生效**:所有用户都需要此密码才能访问 -- **无法在界面删除**:只能通过修改环境变量更改 -- **与本地密码兼容**:两种密码都可以解锁应用 -- **密码持久化**:支持通过 `PERSIST_PASSWORD` 环境变量控制是否在当前设备上记住密码。 +- 每个账户拥有独立的收藏、历史和设置数据 +- 管理员可管理源和设置,观众仅可查看和播放 +- 可同时配置 `ADMIN_PASSWORD`(作为超级管理员入口) -### 方式三:密码持久化设置(ENV) +### 方式三:会话持久化设置 -通过 `PERSIST_PASSWORD` 环境变量,你可以控制用户在输入正确密码后,是否需要在下次打开时重新输入。 +通过 `PERSIST_SESSION` 环境变量控制用户登录后是否在设备上记住会话: | 变量名 | 选项 | 说明 | 默认值 | |--------|------|------|--------| -| `PERSIST_PASSWORD` | `true` / `false` | 是否在本地浏览器持久化保存解锁状态。设置为 `true` 时,用户只需输入一次密码,后续访问无需再次输入。 | `true` | +| `PERSIST_SESSION` | `true` / `false` | 是否在本地浏览器持久化保存登录状态。设置为 `true` 时,用户只需登录一次,后续访问无需再次登录。 | `true` | > [!NOTE] -> 此功能仅在设置了 `ACCESS_PASSWORD` 时才会生效。如果没有设置环境密码,此选项将被忽略。 +> 此功能仅在设置了 `ADMIN_PASSWORD`、`ACCESS_PASSWORD` 或 `ACCOUNTS` 时才会生效。 -## 🎨 站点名称自定义配置 +## 站点名称自定义配置 通过环境变量可以自定义站点名称、标题和描述,无需修改源代码。 @@ -152,10 +180,9 @@ docker run -d -p 3000:3000 -e ACCESS_PASSWORD=your_premium_password --name kvide | 变量名 | 说明 | 默认值 | |--------|------|--------| -| `NEXT_PUBLIC_SITE_TITLE` | 浏览器标签页标题 | `视频聚合平台 - KVideo` | -| `NEXT_PUBLIC_SITE_DESCRIPTION` | 站点描述 | `专属视频聚合播放平台,具备美观的 Liquid Glass UI` | -| `NEXT_PUBLIC_SITE_NAME` | 站点头部名称 | `视频聚合平台` | -| `PERSIST_PASSWORD` | 密码持久化 | `true` | +| `NEXT_PUBLIC_SITE_TITLE` | 浏览器标签页标题 | `KVideo - 视频聚合平台` | +| `NEXT_PUBLIC_SITE_DESCRIPTION` | 站点描述 | `视频聚合平台` | +| `NEXT_PUBLIC_SITE_NAME` | 站点头部名称 | `KVideo` | ### 配置示例: @@ -187,28 +214,34 @@ NEXT_PUBLIC_SITE_TITLE=我的视频 - 聚合播放平台 NEXT_PUBLIC_SITE_DESCRIPTION=专属视频聚合播放平台 ``` -## 📦 自动订阅源配置 +## 自动订阅源配置 -可以通过环境变量 `NEXT_PUBLIC_SUBSCRIPTION_SOURCES` 自动配置订阅源,应用启动时会自动加载并设置为自动更新。 +可以通过环境变量自动配置订阅源,应用启动时会自动加载并设置为自动更新。 -**格式:** JSON 数组字符串,包含 `name` 和 `url` 字段。 +支持两种环境变量名:`SUBSCRIPTION_SOURCES`(服务端) 和 `NEXT_PUBLIC_SUBSCRIPTION_SOURCES`(客户端构建时嵌入)。 + +**格式:** JSON 数组字符串,包含 `name` 和 `url` 字段;或直接提供订阅 URL(逗号分隔多个)。 **示例:** ```bash -NEXT_PUBLIC_SUBSCRIPTION_SOURCES='[{"name":"每日更新源","url":"https://example.com/api.json"},{"name":"备用源","url":"https://backup.com/api.json"}]' +# 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 NEXT_PUBLIC_SUBSCRIPTION_SOURCES='[{"name":"MySource","url":"..."}]' --name kvideo kuekhaoyang/kvideo:latest +docker run -d -p 3000:3000 -e SUBSCRIPTION_SOURCES='[{"name":"MySource","url":"..."}]' --name kvideo kuekhaoyang/kvideo:latest ``` **Vercel 部署:** 在 Vercel 项目设置中添加环境变量: -- 变量名:`NEXT_PUBLIC_SUBSCRIPTION_SOURCES` +- 变量名:`SUBSCRIPTION_SOURCES` - 变量值:`[{"name":"...","url":"..."}]` **Cloudflare Pages 部署:** @@ -217,7 +250,29 @@ docker run -d -p 3000:3000 -e NEXT_PUBLIC_SUBSCRIPTION_SOURCES='[{"name":"MySour - 变量名:`NEXT_PUBLIC_SUBSCRIPTION_SOURCES` - 变量值:`[{"name":"...","url":"..."}]` -## 📝 自定义源 JSON 格式 +## 广告过滤关键词配置 + +通过环境变量自定义广告过滤关键词,用于在 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 +``` + +## 自定义源 JSON 格式 如果你想创建自己的订阅源或批量导入源,可以使用以下 JSON 格式。 @@ -257,7 +312,7 @@ docker run -d -p 3000:3000 -e NEXT_PUBLIC_SUBSCRIPTION_SOURCES='[{"name":"MySour ] ``` -### ⚠️ 重要的区别说明:订阅源 vs 视频源 +### 重要的区别说明:订阅源 vs 视频源 **这是一个常见的误区,请仔细阅读:** @@ -276,44 +331,57 @@ docker run -d -p 3000:3000 -e NEXT_PUBLIC_SUBSCRIPTION_SOURCES='[{"name":"MySour > **简单来说**:如果你只有一个 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.js](https://nextjs.org/)** | 16.0.3 | React 框架,使用 App Router | -| **[React](https://react.dev/)** | 19.2.0 | UI 组件库 | +| **[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.0.2 | 轻量级状态管理 | +| **[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 9**:代码质量检查 +- **ESLint 10**:代码质量检查 - **PostCSS 8**:CSS 处理器 - **Vercel Analytics**:性能监控和分析 +- **Cloudflare Pages**:边缘部署支持 ### 架构特点 -- **App Router**:Next.js 13+ 的新路由系统,支持服务端组件和流式渲染 -- **API Routes**:内置 API 端点,处理豆瓣数据和视频源代理 -- **Service Worker**:离线缓存和智能预加载 +- **App Router**:Next.js 的新路由系统,支持服务端组件和流式渲染 +- **API Routes**:内置 API 端点,处理认证、豆瓣数据和视频源代理 +- **Service Worker**:PWA 支持和资源缓存 - **Server Components**:优化首屏加载性能 - **Client Components**:复杂交互和状态管理 +- **Edge Runtime**:API 路由运行在 Edge Runtime 上,提供更低延迟 -## 🚀 快速部署 - -### 在线体验 - -访问 **[https://kvideo.vercel.app/](https://kvideo.vercel.app/)** 立即体验,无需安装! +## 快速部署 ### 部署到自己的服务器 - - - - #### 选项 1:Vercel 一键部署(推荐) [](https://vercel.com/new/clone?repository-url=https://github.com/KuekHaoYang/KVideo) @@ -340,7 +408,7 @@ docker run -d -p 3000:3000 -e NEXT_PUBLIC_SUBSCRIPTION_SOURCES='[{"name":"MySour - **Build output directory**: 输入 `.vercel/output/static` - 点击 **Save and Deploy**。 -4. **⚠️ 关键步骤:修复运行时环境** +4. **关键步骤:修复运行时环境** > *注意:此时部署虽然显示"Success",但你会发现访问网页会报错。这是因为缺少必要的兼容性配置。请按以下步骤修复:* - 进入 **[项目设置页面](https://dash.cloudflare.com/?to=/:account/pages/view/kvideo/settings/production)** (如果你的项目名不是 kvideo,请在控制台手动查找 Settings -> Functions)。 @@ -365,7 +433,7 @@ docker run -d -p 3000:3000 --name kvideo kuekhaoyang/kvideo:latest 应用将在 `http://localhost:3000` 启动。 -> **✨ 多架构支持**:镜像支持 2 种主流平台架构: +> **多架构支持**:镜像支持 2 种主流平台架构: > - `linux/amd64` - Intel/AMD 64位(大多数服务器、PC、Intel Mac) > - `linux/arm64` - ARM 64位(Apple Silicon Mac、AWS Graviton、树莓派 4/5) @@ -403,7 +471,7 @@ npm start 应用将在 `http://localhost:3000` 启动。 -## 🔄 如何更新 +## 如何更新 ### Vercel 部署 @@ -435,9 +503,9 @@ npm run build npm start ``` -> **🔄 自动化部署**:本项目使用 GitHub Actions 自动构建和发布 Docker 镜像。每次代码推送到 main 分支时,会自动构建多架构镜像并推送到 Docker Hub。 +> **自动化部署**:本项目使用 GitHub Actions 自动构建和发布 Docker 镜像。每次代码推送到 main 分支时,会自动构建多架构镜像并推送到 Docker Hub。 -## 🤝 贡献代码 +## 贡献代码 我们非常欢迎各种形式的贡献!无论是报告 Bug、提出新功能建议、改进文档,还是提交代码,你的每一份贡献都让这个项目变得更好。 @@ -449,11 +517,11 @@ npm start 3. **代码贡献**:Fork → Branch → PR 4. **文档改进**:直接提交 PR -## 📄 许可证 +## 许可证 本项目基于 [MIT 许可证](LICENSE) 开源。 -## 🙏 致谢 +## 致谢 感谢以下开源项目: @@ -461,17 +529,16 @@ npm start - [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) - - - - ---