Paperless-ngx 於 2026 年 10 月底累積 47,297 個星標，是一套以 Python 與 Angular 建構的自架文件管理系統，把紙本掃描、光學字元辨識與全文檢索整合在同一個介面。專案在 10 月 6 日推出 3.3.0 版本，加入可切換的大型語言模型後端與向量索引，讓既有文件庫具備語意檢索能力。
Paperless-ngx 是什麼？
它是 Paperless 與 Paperless-ng 的官方後繼專案，採 GPL-3.0 授權，以 Docker Compose 部署，把掃描文件轉為可全文搜尋的線上檔案庫。
倉庫建立於 2022 年 2 月 12 日，定位是承接前代專案並把維護責任分散到一組團隊，而不是由單一開發者長期承擔。技術組成以 Python 後端搭配 Angular 前端，資料層使用 Django 與關聯式資料庫，部署則以容器映像為主要形式。
系統在概念上分成兩個部分。consumer 監看指定資料夾，把落入該資料夾的檔案納入處理流程；web server 提供介面，負責檢索、編輯與管理。這樣的分工讓掃描器或手機應用只需把檔案放進共用目錄，其餘流程由系統接手。
每份文件可掛上多種中繼資料，包括 correspondent（往來對象）、tag（標籤）、document type（文件類型）、storage path（儲存路徑）與自訂欄位。其中標籤取代了傳統資料夾，允許一份文件同時屬於多個分類，也避免同一份文件在樹狀結構中重複存放。
47,297 個星標反映怎樣的使用需求？
專案累積約 12,384 次提交、464 位貢獻者與 167 個版本，公開議題僅 6 個，需求討論主要集中到 Discussions，維護節奏相當緊密。
星標數在這類工具中具有明確含義。文件管理屬於長期基礎設施，使用者把紙本與憑證交出去之前，通常會先觀察專案是否仍在維護。近 1.2 萬次提交與 167 個版本提供了一個可核對的答案，而 Fork 數接近 3,300 則說明不少人選擇自行改造而非單純使用。
維護模式也值得注意。公開議題只有 6 個，功能請求被導向 GitHub Discussions 的投票分類，錯誤回報則走 Issue。這種分流減少了重複條目，也讓討論留在可搜尋的位置。專案同時透過 Crowdin 接受翻譯，並設有前端與 CI 等分工團隊，屬於少見的把治理寫進 README 的專案。
AI 功能如何運作且是否預設開啟？
全部 AI 功能預設關閉。需設定 PAPERLESS_AI_ENABLED 並選擇 Ollama 或 OpenAI 相容後端，才會啟用建議、向量索引與文件對話三項能力。
三項功能各有分工。AI 建議會在文件詳情頁提供標題、標籤、往來對象、文件類型、儲存路徑與日期的候選值，並可與既有的機器學習分類器結果合併。向量索引則把文件切塊後建立索引，讓建議結果以相似文件為依據。文件對話在索引建立後可用，回答會附上引用來源。
後端選擇決定資料流向。設定為 Ollama 時模型在本機執行，設定為 openai-like 時可指向 OpenAI 或任何相容端點。嵌入流程另有獨立開關，huggingface 選項會在本機下載模型並建立索引，首次執行需要網路與額外磁碟空間。索引預設每日透過排程重建，也可手動觸發。
官方文件把隱私界線寫得相當直接。啟用功能即代表文件內容與中繼資料會送往所選的模型後端，若後端為遠端服務，內容會離開自家伺服器並可能產生費用。此外文件內容被視為不可信資料處理，並提供設定項封鎖指向內部或迴環位址的端點，避免模型後端被誘導去讀取內網資源。
3.3.0 版本帶來哪些實際改動？
3.3.0 加入獨立的嵌入 API 金鑰、條碼內容儲存與搜尋、Django 管理介面雙因素驗證，並把額外的 LLM 參數原樣傳遞給所選後端。
版本節奏反映了維護強度。3.3.0 於 10 月 6 日發佈，之後在 10 月 12 日、16 日、19 日與 22 日連續推出四個修補版本，平均不到一週一次。3.3.4 屬於安全性維護，處理憑證授權機構事件相關的根憑證更新，並修補 Pillow 與 aiohttp 的已知弱點，官方建議所有使用者升級。
對中文使用者而言，3.3.0 的一項修正特別相關。該版本把 pdf.js 的字型對照檔一併打包，解決中日韓文件在檢視器中顯示異常的問題。同一版本還加入條碼內容的儲存、列表與搜尋，讓掃描時讀到的條碼成為可查詢欄位，對單據歸檔流程有實際幫助。
管理介面也補上雙因素驗證，並讓已解析的密鑰能傳遞到互動式容器 shell。這兩項改動指向同一個方向：部署在家庭伺服器或小型辦公環境時，存取控制與維運便利性往往比新功能更影響長期使用意願。
文件版本與巢狀標籤解決什麼問題？
版本功能把同一份文件的多個檔案歸在同一個條目，巢狀標籤支援最多五層父子結構，兩者共同降低文件長期累積後的整理成本。
版本機制可以理解為文件層級的檔案歷史。同一個條目下的檔案以 _v1、_v2 後綴區分，搜尋與內容預設取最新版本，切換版本時預覽、中繼資料與下載按鈕會同步切換。使用者可在清單中選取多份文件後合併為版本，被合併的文件會釋出實體編號，並在紀錄中留下異動。
巢狀標籤則是分類層級的調整。自 2.19 版起標籤可設定父層，形成最多五層的樹狀結構；把標籤加到文件時，其父層標籤會自動附加，移除時子層標籤也會一併處理。對同時處理稅務、保險與醫療單據的使用者，這種階層比扁平標籤更接近實際的櫃位安排。
兩項設計都指向同一個現實：文件庫的價值隨時間累積，而混亂也隨時間累積。能否在三年後仍找得到某張憑證，取決於當初有沒有留下可追溯的版本與一致的分類，而不是取決於介面美觀程度。
部署成本與安全邊界在哪裡？
官方以 Docker Compose 為主要安裝方式並提供安裝腳本，資料以明文儲存且未加密，官方要求部署在自家可信任主機並定期備份。
安裝門檻設得相當低。官方提供一鍵腳本建立 Compose 環境，映像直接從 GitHub 容器倉庫拉取；若偏好手動設定，docker/compose 目錄內已備妥範本。專案另設公開示範站，帳號與密碼皆為 demo，方便先確認介面再決定是否自架。
安全邊界在 README 內以獨立段落說明。文件以明文保存且未加密，因此官方明確表示不應部署在不受信任的主機上，並建議放在自家區域網路內的伺服器、配合備份使用。這個說明並不浪漫，卻是把風險講清楚的做法，也讓採用者能據此評估是否符合自身情境。
對有意導入的團隊，實際成本落在三處：儲存空間隨掃描量線性成長、OCR 與向量索引需要可觀的運算資源、以及備份策略必須自行設計。軟體本身免費，維運責任則完整轉移到部署者身上。
出處連結有哪些？
原始碼位於 GitHub 的 paperless-ngx/paperless-ngx，官方文件站為 docs.paperless-ngx.com，另設公開示範站供試用。
倉庫同時維護完整的文件站，涵蓋安裝、設定、使用、進階功能、API 與疑難排解，並保留 v3 的遷移說明。對於需要評估是否從舊版 Paperless-ng 遷移的使用者，文件中提供了直接替換映像的路徑說明。
- GitHub 倉庫：https://github.com/paperless-ngx/paperless-ngx
- 官方文件：https://docs.paperless-ngx.com
- 公開示範站：https://demo.paperless-ngx.com
- 版本紀錄：https://github.com/paperless-ngx/paperless-ngx/releases
總結：Paperless-ngx 適合什麼團隊？
適合有大量紙本憑證、願意自行維運伺服器並重視資料留在本地的個人或小型團隊；以雲端優先、無人維運的組織則需另尋方案。
這個專案的分量來自時間。47,297 個星標背後是近 1.2 萬次提交與 167 個版本，而 10 月的五次發佈說明維護並未因規模擴大而放慢。3.3.0 把語言模型接進既有流程的方式也相對克制，功能預設關閉、後端可自選、隱私風險寫在前方。
仍待觀察的是 AI 功能的實際採用率。分類器與正規表達式已足夠處理多數固定格式單據，語言模型的價值主要出現在欄位不規則或需要跨文件問答的場景。在索引重建成本與資料外送疑慮取得平衡之前，多數使用者較可能維持關閉狀態，把它當作可選的加分項而非必要條件。
