KVideo：開源影片聚合播放外殼，自架前要先想清楚你要接什麼源

用 AI 摘要這篇文章：

ChatGPT Claude Perplexity Google Grok

KVideo 是一套用 Next.js 16 寫的開源影片聚合與播放平台，作者 KuekHaoYang 以 MIT 授權在 GitHub 公開。它把「搜尋、播放、看片紀錄」這三件事收進一個網頁介面，並採用一套叫 Liquid Glass（液態玻璃）的視覺風格。下載下來不會有任何片可看，這是整篇要反覆回到的那一句話：它只給你外殼，內容你自己決定，而這個決定就是法律責任落在誰身上的分界。

本篇給的是認識，不是評測。播放穩不穩、廣告過濾擋不擋得住這類只有實際跑過才知道的事，本文不替它們背書，留給你自己部署時驗證。

它實際做什麼：聚合外部源的播放前端

要理解 KVideo，先看它跟 Plex、Jellyfin 那種媒體庫伺服器差在哪。Plex 的核心是你把影片檔放進自己的資料夾，它幫你掃海報、抓演員卡、轉碼給不同裝置。KVideo 不做這件事。它不管你的本地檔案，而是讓你把一或多個「影片源」（用作者定的 JSON 格式描述，欄位像是 baseUrl、searchPath、detailPath）填進設定，再用一套統一解析器把不同來源的資料格式轉成同一套介面能顯示的樣子。

換句話說，它的核心判斷發生在「搜尋」這一步。你打一個片名，KVideo 透過 Server-Sent Events（一種讓伺服器主動把結果推給瀏覽器的技術）平行問你配置的所有源，把結果摺疊、排序、顯示。文件還提到它會即時監測每個源的回應延遲，把慢的源往後排。來源數量太多時，介面把多出來的源收進「展開更多」這一層，避免一次攤出幾十條結果。另外有一條獨立的優化：用 sessionStorage 把源資料快取起來，避免網址列參數過長被 CDN 擋下（HTTP 網址有長度上限，叫 414 URI Too Long）。播放時吃的是 HLS（HTTP Live Streaming，蘋果提出的串流協定，附檔名 .m3u8），靠 hls.js 這個業界主流的開源函式庫在瀏覽器裡解。

源在這套系統裡分成兩種。一種是「影片源」，就是一個會回傳搜尋與詳情資料的 API 端點，配置時用 JSON 描述，欄位有 id、name、baseUrl、searchPath、detailPath、group、enabled、priority、headers。另一種是「訂閱源」，就是一個指向 JSON 清單檔的網址，那份清單裡放著一整批影片源的設定，讓你一次匯入。README 特別把這兩者分開命名，因為實務上常見的誤解是把訂閱源當成單一來源，結果設定了十個訂閱源等於一次匯入上百個源，搜尋時全部被打開。

KVideo 還整合了豆瓣。它把豆瓣的評分、演員、劇情簡介抓回來，在播放頁旁邊顯示，演員和導演的名字可以點，點下去會去搜你配置的源裡有沒有那個人的其他作品。豆瓣本身是中國的影視資料庫，類似 IMDb 的角色；KVideo 抓的是公開資料，不是影片本身，所以這條整合跟「能不能播」無關，只是讓選片資訊更完整。這部分同樣屬於作者宣稱。

這套設計有一個直接後果。Plex 的內容邊界是你硬碟裡合法買來的檔案，KVideo 的內容邊界是你接的那份源。如果你接的是正版 VOD 服務提供的 API、自己的 IPTV 訂閱、或你自己架的媒體伺服器，那它就是一個把分散來源收進同一個介面的方便工具。如果你接的是別人盜版抓來的採集站，那不是 KVideo 讓你違法，是你接的那份源本來就違法。README 在這點上寫得很白：「倉庫預設不內建任何影片源、高級源或 IPTV 源。部署者必須自行配置已獲授權、可合法使用且允許當前部署方式訪問的內容來源。」

這也是它跟我們介紹過的 neTV 自架 IPTV 播放器 在定位上的差別。neTV 服務「手上就是一條 IPTV，嫌 Plex 太重」的人；KVideo 服務「想自己拼一套多源聚合搜尋介面」的人。兩者都是「不自帶內容」的播放前端，但 neTV 著重直播與 EPG 節目表，KVideo 著重跨源搜尋與豆瓣資訊整合。

官方給你看的東西：repo 數字與 demo

從 GitHub API 查得到的事實是這些：repo 於 2025 年 11 月 16 日建立，截至 2026-08-01 有 3928 顆 star、6716 個 fork，開出的 issue 是 0，最後一次 push 在 2026 年 8 月 1 日，最新一個 commit 訊息是「feat: add self-contained strict verification chain」，只有一個正式 release（2026 年 4 月的 Android TV APK）。LICENSE 檔案解開來是標準 MIT 文字，著作權屬 Kuek Hao Yang。

Pin

3928 之於 6716 是反常比例。絕大多數 repo 的 star 遠多於 fork，這裡反而 fork 多將近一倍。一個合理的解讀是：這是一個重部署輕追蹤的專案，多數人 fork 不是為了貢獻或收藏，而是為了 fork 一份到自己帳號再架起來用。這個解讀屬於推測，fork 的實際動機只有 fork 的人自己知道。

作者還給了一個 demo 站 kvideo.pages.dev。靜態抓取只看得到標題列「KVideo：影片聚合平台」就停住了，因為內容是 Next.js 在瀏覽器端才渲染的單頁應用，靜態抓取看不到介面。所以我只能告訴你 demo 存在且可連，沒辦法替你描述搜尋框、播放器或設定頁長什麼樣，這部分你得自己開來看。

Pin

本地優先這條設計，是它最值得理解的一件事

KVideo 把隱私當成明確的架構選擇來設計。README 的隱私段寫了三條宣稱：所有資料存在本地瀏覽器、不收集或上傳任何使用者資料、多帳號情境下每個人的歷史與收藏完全隔離。識別使用者的方式是把密碼做 SHA-256 雜湊當 profileId，這個過程不可逆，所以即使有人拿到本地資料也還原不出原密碼。

這三條是作者在 README 的宣稱，未經獨立驗證。不過這套設計思路對應到一個真實的工程問題，值得拆開來看。

問題是這樣的。KVideo 是一個你可以 PWA 安裝到 iOS Safari 主畫面的應用。iOS Safari 對「加到主畫面」的 PWA 有個長期存在的限制：它的 localStorage 會跟一般 Safari 分開隔離，導致你在主畫面版打開看不到一般瀏覽器設定的資料。如果你想把收藏和看片紀錄同步到另一台裝置，光靠本地瀏覽器做不到。KVideo 給的解法是選配 Upstash Redis，在伺服器端存一份設定，安裝時自動 pull、變動時自動 push。沒有設 Redis 的話，README 寫「配置同步功能靜默降級，應用正常運行，僅本地存儲生效」。

這裡有一個讀者常忽略的層次。「本地存儲、不收集」這句只擋到工具作者，意思是 KuekHaoYang 不會收到你的資料。它不擋你接的源。你打開一個採集站提供的源，那個源所屬的伺服器就看得到你搜了什麼、點了什麼。一旦你開了 Upstash Redis 做跨裝置同步，又多一個第三方能看到你的設定。所以「本地優先」要精準讀成「預設不經作者伺服器」，離「完全沒有人看得到你」還有一段距離。這條誠實的讀法，比 README 的宣稱句子更值得帶走。

存取控制是另一條值得展開的設計。README 列了五種登入方式。單一管理員密碼是設一個 ADMIN_PASSWORD 環境變數，登入即超級管理員；多帳號系統用 ACCOUNTS 變數一次定義多名使用者，每人各帶角色與細項權限；託管帳號模式是作者推薦的路線，要額外設 AUTH_SECRET 加 Upstash Redis，用 HTTP-only 的簽章 cookie 維持登入狀態，超級管理員能在設定頁直接增刪帳號。另外兩個是針對 /premium 路徑的獨立密碼，以及控制登入要不要持續的 PERSIST_SESSION 開關。

權限細到 source_management（改源）、account_management（改帳號）、danmaku_api（改彈幕 API）、data_management（改資料）、player_settings（改播放器）、iptv_access（用 IPTV）等欄位，預設把角色分成 super_admin、admin、viewer 三種。這套設計的意思是：如果你架給家人或一群朋友共用，可以給每個人不同的能見度，不會人人都動到源設定。要付出的是你得多設一個 Redis 才能用完整的託管帳號模式，這跟前面講的跨裝置同步是同一個 Redis，一個帳號兩種用途。

四條會決定部署方式的硬限制

如果你打算自己架一份，有四條限制會直接決定你的部署方式。

授權與內容是兩回事。 MIT 授權讓你隨意改作、商用、自架，但「MIT」只覆蓋程式碼本身，不覆蓋你接進去的影片。你接的源合不合法，是你在選源的時候就決定好的事，跟 KVideo 的開源授權無關。這跟 CookHero 自架食譜 Agent 之類的本地優先自架工具一樣，工具的開源授權跟它處理的內容是兩條分開的授權軸，必須各自想清楚。

託管平台會吃掉功能。 如果你圖方便直接 fork 到 Vercel 或 Cloudflare Pages 跑，README 寫這兩個平台會自動進入「合規模式」，關閉外部媒體代理、熱鏈轉發、IPTV 流中繼，只保留直連播放。理由是這兩家託管平台對能當代理轉發流量的應用有政策限制。換句話說，IPTV 和需要代理才能播的源在 Vercel 上跑不起來，你必須改用 Docker 或 Node 自架，才有 IPTV 與媒體代理這類功能。官方推 Docker，映像檔 kuekhaoyang/kvideo:latest 支援 amd64 與 arm64，NAS 或小主機都吃。

技術棧非常新。 Next.js 16.1.7、React 19.2.4、Tailwind v4，這幾個版本在 2026 年 8 月都是非常新的主版本。新版本帶來效能與功能改進，但生態系的第三方套件成熟度、文件與除錯討論數量，會比穩定版少。自架遇到怪問題時，能搜到的解答也會比較少。這是寫實的取捨，談不上誰優誰劣。

跨裝置同步要付出第三方帳號成本。 前面提過 Upstash Redis 是選配，但如果你要在 iOS Safari PWA、桌機、Android TV 之間共享同一份收藏與看片紀錄，Redis 幾乎是必開的。開了 Redis 之後，你的設定資料就經過 Upstash 這個第三方。Upstash 本身是正規的 serverless Redis 服務，有免費額度，但這條邊界要知道。

自架玩家會用得到，想找開箱追劇站的人不會

KVideo 不是給「打開就想看片」的人。它給的是這兩種人：一種是本來就在自架媒體工具、想把多個源收進同一個介面的玩家，跟 OpenCut 開源影片編輯器 那種「願意自己架、自己設定、自己負責」的人是同一群；另一種是開發者，想把一套可直接改源的影片聚合前端當成基礎，再自己改源、改介面、改推薦邏輯。

不該碰的人也很明確。如果你要的是打開就有一堆片的 Netflix 替代品，KVideo 給不了你，因為它根本不附內容。如果你看見 GitHub 上「影片聚合」「Liquid Glass」這些字就期待一個開箱即用的免費追劇站，那這個期待會害你接上不該接的源，把法律責任往自己身上攬。工具的開源是乾淨的，內容的合法性完全是另一回事。

如果你讀完這幾段，確認自己屬於該考慮的那一群，那自架前要先決定的一件事就是：你要接的源，是你有權使用的嗎？這個問題先回答清楚，再去看 Docker 指令、去看 Liquid Glass 介面、去看豆瓣整合，順序才會對。KVideo 的價值在它把外殼做得乾淨、把責任畫得清楚，剩下那個最關鍵的決定，它刻意不替你做。

最後補一個閱讀這類專案的小訣竅。看一個聚合型工具會不會踩到你的紅線，最快的方式是讀它的免責聲明和部署限制，勝過讀功能表。KVideo 在 README 把「不附源」「Vercel 合規模式關代理」這幾條白紙黑字寫出來，本身就是一種負責任的訊號，代表作者知道這套工具的邊界在哪、也知道把邊界講清楚比把功能吹大更重要。你看見這種寫法，可以比看見一堆形容詞更放心一點；但放心不等於免責，源是不是合法，答案永遠在你手上，不在工具裡。