影片整合平台 (KVideo)

一個基於 Next.js 16 建構的現代化影片整合播放平台。採用獨特的 "Liquid Glass" 設計語言，提供流暢的視覺體驗和強大的影片搜尋功能。

🌐 線上體驗：https://kvideo.pages.dev/

KVideo 是一個高效能、現代化的影片整合與播放應用，專注於提供極致的用戶體驗和視覺設計。本專案利用 Next.js 16 的最新特性，結合 React 19 和 Tailwind CSS v4，打造了一個既美觀又強大的影片瀏覽平台。

專案的視覺設計基於 "Liquid Glass" 設計系統，這是一套融合了以下特性的現代化 UI 設計語言：

• 玻璃擬態效果：透過 backdrop-filter 實現的磨砂半透明效果，讓 UI 元素如同真實的玻璃材質
• 通用柔和度：統一使用 rounded-2xl 和 rounded-full 兩種圓角半徑，創造和諧的視覺體驗
• 光影互動：懸停和聚焦狀態下的內發光效果，模擬光線被「捕捉」的物理現象
• 流暢動畫：基於物理的 cubic-bezier 曲線，實現自然的加速和減速過渡
• 深度層級：清晰的 z-axis 層次結構，增強空間感和互動回饋

• HLS 串流媒體支援：原生支援 HLS (.m3u8) 格式，提供流暢的影片播放體驗
• 智慧快取機制：Service Worker 驅動的智慧快取系統，自動預先載入和快取影片片段
• 背景下載：利用觀看歷史，在背景自動下載歷史影片，確保離線也能觀看
• 播放控制：完整的播放控制功能，包括進度條、音量控制、播放速度調節、全螢幕模式等
• 行動端優化：專門為行動裝置優化的播放器介面和手勢控制

• 整合搜尋引擎：同時在多個影片源中並行搜尋，大幅提升搜尋速度
• 自定義影片源：支援新增、編輯和管理自定義影片源
• 智慧解析：統一的解析器系統，自動處理不同源的資料格式
• 搜尋歷史：自動儲存搜尋歷史，支援快速重新搜尋
• 結果排序：支援按評分、時間、相關性等多種方式排序搜尋結果

• 電影 & 電視劇分類：支援在電影和電視劇之間無縫切換，方便查找不同類型的影視資源
• 詳細影視資訊：自動獲取豆瓣評分、演員陣容、劇情簡介等詳細資訊
• 推薦系統：基於豆瓣資料的相關推薦
• 專業評價：展示豆瓣用戶評價和專業影評

• 自動記錄：自動記錄觀看進度和歷史
• 斷點續播：從上次觀看位置繼續播放
• 歷史管理：支援刪除單條歷史或清空全部歷史
• 隱私保護：所有資料儲存在本地，不上傳到伺服器

• 全端適配：完美支援桌面、平板和行動裝置
• 行動優先：專門的行動端組件和互動設計
• 觸控優化：針對觸控螢幕優化的手勢和互動

• 深色/淺色模式：支援系統級主題切換
• 動態主題：基於 CSS Variables 的動態主題系統
• 無縫過渡：主題切換時的平滑過渡動畫

• 鍵盤導覽：完整的鍵盤快速鍵支援
• ARIA 標籤：符合 WCAG 2.2 標準的無障礙實現
• 語義化 HTML：使用語義化標籤提升可存取性
• 高對比度：確保 4.5:1 的文字對比度

• 獨立入口：在瀏覽器網址列直接輸入 /premium 即可進入獨立的進階影片專區
• 內容隔離：進階內容與普通內容完全物理隔離，互不干擾
• 專屬設定：擁有獨立的內容源管理和功能設定

• 多模式選擇：支援關閉、關鍵字過濾、智慧啟發式過濾(Beta)和激進模式。
• UI 整合：在播放器設定選單中直接切換模式，即時生效。
• 自定義關鍵字：支援透過環境變數擴充過濾關鍵字。
• 高效能：基於串流處理，對播放載入速度幾乎無影響。

本應用注重用戶隱私：

• 本地存儲：所有資料儲存在本地瀏覽器中
• 無伺服器資料：不收集或上傳任何用戶資料
• 自定義源：用戶可自行配置影片源

KVideo 支援兩種密碼保護方式：

在設定頁面中啟用密碼存取，並新增密碼：

• 裝置獨立：僅在目前瀏覽器/裝置有效
• 可管理：可隨時新增或刪除
• 多密碼支援：可設定多個有效密碼

透過 ACCESS_PASSWORD 或 ACCESS_PASSWORD_2 環境變數設定全域密碼：

Docker 部署：

docker run -d -p 3000:3000 \
  -e ACCESS_PASSWORD=your_password_1 \
  -e ACCESS_PASSWORD_2=your_password_2 \
  --name kvideo kuekhaoyang/kvideo:latest

Vercel 部署：

在 Vercel 專案設定中新增環境變數：

• 變數名：ACCESS_PASSWORD
• 變數值：你的第一個密碼
• 變數名：ACCESS_PASSWORD_2
• 變數值：你的第二個密碼

特點：

• 全域生效：所有用戶都需要此密碼之一才能存取
• 無法在介面刪除：只能透過修改環境變數變更
• 與本地密碼相容：三種密碼都可以解鎖應用
• 密碼持久化：支援透過 PERSIST_PASSWORD 環境變數控制是否在目前裝置上記住密碼。

透過 PERSIST_PASSWORD 環境變數，你可以控制用戶在輸入正確密碼後，是否需要在下次打開時重新輸入。

透過環境變數可以自定義站台名稱、標題和描述，無需修改原始碼。

Vercel 部署： 在 Vercel 專案設定中新增環境變數：

• 變數名：NEXT_PUBLIC_SITE_NAME
• 變數值：我的影片平台

Cloudflare Pages 部署： 在 Cloudflare Pages 專案設定中新增環境變數：

• 變數名：NEXT_PUBLIC_SITE_NAME
• 變數值：我的影片平台

Docker 部署：

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 檔案：

NEXT_PUBLIC_SITE_NAME=我的影片平台
NEXT_PUBLIC_SITE_TITLE=我的影片 - 整合播放平台
NEXT_PUBLIC_SITE_DESCRIPTION=專屬影片整合播放平台

可以透過環境變數 NEXT_PUBLIC_SUBSCRIPTION_SOURCES 自動配置訂閱源，應用啟動時會自動載入並設定為自動更新。

格式： JSON 陣列字串，包含 name 和 url 欄位。

範例：

NEXT_PUBLIC_SUBSCRIPTION_SOURCES='[{"name":"每日更新源","url":"https://example.com/api.json"},{"name":"備用源","url":"https://backup.com/api.json"}]'

Docker 部署：

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

Vercel 部署：

在 Vercel 專案設定中新增環境變數：

• 變數名：NEXT_PUBLIC_SUBSCRIPTION_SOURCES
• 變數值：[{"name":"...","url":"..."}]

Cloudflare Pages 部署：

泛在 Cloudflare Pages 專案設定中新增環境變數：

• 變數名：NEXT_PUBLIC_SUBSCRIPTION_SOURCES
• 變數值：[{"name":"...","url":"..."}]

如果你想建立自己的訂閱源或批次導入源，可以使用以下 JSON 格式。

基本結構：

可以是單個物件陣列，也可以是包含 sources 或 list 欄位的物件。

源物件欄位說明：

範例 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
  }
]

这是一个常见的误区，请仔细阅读：

• 视频源 (Source)：

  • 指向单个 CMS/App API 接口
  • 例如：https://api.example.com/vod
  • 这种链接不能直接作为"订阅"添加
  • 只能在"自定义源管理"中作为单个源添加

• 订阅源 (Subscription)：

  • 指向一个 JSON 文件（如上面的示例）的 URL
  • 这个 JSON 文件里包含了一个或多个视频源的列表
  • 例如：https://mysite.com/kvideo-sources.json
  • 这是一个配置文件的链接，不是视频 API 的链接
  • 只有这种返回 JSON 列表的链接才能在"订阅管理"中添加

简单来说：如果你只有一个 m3u8 或 API 接口地址，请去"自定义源"添加。如果你有一个包含多个源的 JSON 文件链接，请去"订阅管理"添加。

• ESLint 9：代码质量检查
• PostCSS 8：CSS 处理器
• Vercel Analytics：性能监控和分析

• App Router：Next.js 13+ 的新路由系统，支持服务端组件和流式渲染
• API Routes：内置 API 端点，处理豆瓣数据和视频源代理
• Service Worker：离线缓存和智能预加载
• Server Components：优化首屏加载性能
• Client Components：复杂交互和状态管理

存取 https://kvideo.vercel.app/ 立即體驗，無需安裝！

1. 點擊上方按鈕
2. 連接你的 GitHub 帳號
3. Vercel 會自動檢測 Next.js 專案並部署
4. 幾分鐘後即可存取你自己的 KVideo 實例

此方法完全免費且速度極快，是部署本專案的最佳選擇。

1. Fork 本倉庫：首先將專案 Fork 到你的 GitHub 帳戶。

2. 建立專案：

   • 點擊存取 Cloudflare Pages - Connect Git。
   • 如果未連接 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"，但你會發現存取網頁會報錯。這是因為缺少必要的相容性配置。請按以下步驟修復：

   • 進入 專案設定頁面 (如果你的專案名不是 kvideo，請在控制台手動查找 Settings -> Functions)。
   • 拉到頁面底部找到 Compatibility flags 部分。
   • 新增標誌：nodejs_compat

5. 重試部署 (生效配置)：

   • 回到 專案概覽頁面。
   • 在 Deployments 列表中，找到最新那次部署。
   • 點擊右側的三個點 ... 選單，選擇 Retry deployment。
   • 等待新的部署完成後，你的 KVideo 就部署成功了！

從 Docker Hub 拉取（最簡單）：

# 拉取最新版本
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）

自己建構映像檔：

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：

docker-compose up -d

# 1. 克隆倉庫
git clone https://github.com/KuekHaoYang/KVideo.git
cd KVideo

# 2. 安裝依賴
npm install

# 3. 建構專案
npm run build

# 4. 啟動生產伺服器
npm start

應用將在 http://localhost:3000 啟動。

Vercel 會自動檢測 GitHub 倉庫的更新並重新部署，無需手動操作。

當有新版本釋出時：

# 停止并删除旧容器
docker stop kvideo
docker rm kvideo

# 拉取最新镜像
docker pull kuekhaoyang/kvideo:latest

# 运行新容器
docker run -d -p 3000:3000 --name kvideo kuekhaoyang/kvideo:latest

cd KVideo
git pull origin main
npm install
npm run build
npm start

🔄 自动化部署：本项目使用 GitHub Actions 自动构建和发布 Docker 镜像。每次代码推送到 main 分支时，会自动构建多架构镜像并推送到 Docker Hub。

我们非常欢迎各种形式的贡献！无论是报告 Bug、提出新功能建议、改进文档，还是提交代码，你的每一份贡献都让这个项目变得更好。

想要参与开发？请查看 贡献指南 了解详细的开发规范和流程。

快速开始：

1. 报告 Bug：提交 Issue
2. 功能建议：在 Issues 中提出你的想法
3. 代码贡献：Fork → Branch → PR
4. 文档改进：直接提交 PR

本项目基于 MIT 许可证 开源。

感谢以下开源项目：

• Next.js - React 框架
• Tailwind CSS - CSS 框架
• Zustand - 状态管理
• React - UI 库

• 作者：KuekHaoYang
• 项目主页：https://github.com/KuekHaoYang/KVideo
• 问题反馈：GitHub Issues