Paperless-ngx 完整教學 2026：把家中紙本文件全部數位化，中文 OCR＋AI 自動分類的自架文件管理系統（Docker 安裝、繁中 OCR 設定、Ollama 本機 AI、備份還原一次學會）

**一句話結論：**Paperless-ngx 是一套能自架的文件管理系統（Document Management System），你把紙本掃描成 PDF 丟進一個資料夾，它就會自動 OCR、抽文字、建索引，讓你在瀏覽器上用關鍵字找到十年前那張保單——而且預設不把任何文件送到雲端。

為什麼要自架一套文件管理系統？

紙本文件真正的問題不是「佔空間」，而是找不回來。你知道那張收據存在，但不知道它在哪個抽屜；你想查三年前買的那台除濕機保固幾年，只能翻箱倒櫃。掃描成 PDF 只解決了一半：檔案散在資料夾裡，檔名全靠自己命名，搜尋結果永遠只比紙本好一點。

Paperless-ngx 解決的是這個：**你負責掃描，它負責理解。**它會對每一份文件做光學字元辨識（OCR），把內容變成可全文檢索的文字，再搭配往來對象、文件類型、標籤、日期與自訂欄位，建立一套真正查得動的個人檔案庫。整套系統跑在你自己的機器上，原始檔案與資料庫都是你的。

它的前身是 Paperless 與 Paperless-ng，ngx 版本是目前社群共同維護的官方後繼專案——這點對長線使用很重要：你不會用了一個三年沒更新的孤兒專案。

核心功能一次看

架構：5 個容器在做什麼

官方 Docker Compose 範本會拉起五個服務。搞懂它們的分工，後面排錯會輕鬆很多。

gotenberg 與 tika 是可選的：如果你只收 PDF 與圖片，可以省略；但只要你想匯入 Word、Excel 或 Outlook 郵件，這兩個就要留著。

安裝：Docker Compose 兩條路

路徑 A：官方互動式安裝腳本（最快）

bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

腳本會問你資料庫要用 PostgreSQL 或 SQLite、要不要 Tika、OCR 語言、時區、管理員帳密，然後把 docker-compose.yml、docker-compose.env、.env 都生好，最後幫你 docker compose up -d。裝完打開 http://127.0.0.1:8000 就能登入。

路徑 B：手動 Compose（想完全掌握設定）

在一個專案目錄（例如 /opt/paperless）建立三個檔案：

docker-compose.yml

services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on: [db, broker, gotenberg, tika]
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.37
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    image: docker.io/apache/tika:3.3.1.0
    restart: unless-stopped

volumes:
  data:
  media:
  pgdata:
  redisdata:

docker-compose.env（Paperless 自己的設定，重點在中文 OCR）

PAPERLESS_TIME_ZONE=Asia/Taipei
PAPERLESS_OCR_LANGUAGE=chi_tra+eng
PAPERLESS_OCR_LANGUAGES=chi-tra
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=請改成強密碼
PAPERLESS_URL=https://paperless.example.com

.env（Compose 本身用，可留空或放 COMPOSE_PROJECT_NAME）

COMPOSE_PROJECT_NAME=paperless

啟動與更新：

docker compose pull      # 抓映像
docker compose up -d     # 啟動
docker compose logs -f webserver   # 看啟動與消費任務日誌

繁體中文 OCR 的關鍵兩行

這是中文使用者最容易踩的坑。Paperless-ngx 映像預設只安裝英文、德文、義大利文、西班牙文、法文的 Tesseract 語言包，中文要自己加：

官方文件特別提醒：PAPERLESS_OCR_LANGUAGES 不可用在 rootless 容器；另外啟用多語言會明顯增加 OCR 的 CPU 時間，如果文件以中文為主，用 chi_tra 單一語言會比 chi_tra+eng 快很多。

**小技巧：**200 頁的掃描檔在樹莓派上 OCR 可能要跑好幾分鐘。想省資源可以設 PAPERLESS_OCR_PAGES=1，只 OCR 第一頁——對「找得到文件」這件事來說，第一頁通常已經足夠。

v3.2.0 幫中文使用者加了什麼？

2026-09-19 發布的 v3.2.0 中有一條對中文檢索特別有感：「Match CJK terms through their bigram fields in place」——CJK（中日韓）文字沒有空白分詞，搜尋引擎改用 bigram（雙字組）處理。這次改動讓中文查詢能直接在 bigram 欄位命中，中文全文檢索的命中率與排序都有改善。若你之前覺得「中文搜尋怪怪的」，值得升級。

AI 功能：本機 Ollama 或遠端 API

Paperless-ngx 的 AI 功能預設關閉。要開啟，需要設定兩個層次：LLM 後端（產生建議、回答問題）與向量嵌入後端（RAG 檢索）。

啟用範例（本機 Ollama + 本機嵌入）：

PAPERLESS_AI_ENABLED=true
PAPERLESS_AI_LLM_BACKEND=ollama
PAPERLESS_AI_LLM_MODEL=llama3.1
PAPERLESS_AI_LLM_ENDPOINT=http://ollama:11434
PAPERLESS_AI_LLM_EMBEDDING_BACKEND=ollama
PAPERLESS_AI_LLM_EMBEDDING_MODEL=embeddinggemma
PAPERLESS_AI_LLM_OUTPUT_LANGUAGE=zh-TW
PAPERLESS_LLM_INDEX_TASK_CRON=0 3 * * *

幾個值得記住的參數：

• PAPERLESS_AI_LLM_CONTEXT_SIZE 預設 8192；對 Ollama 後端會一併當成 num_ctx 傳入，避免超大上下文模型被以最大長度載入而爆記憶體。
• PAPERLESS_AI_LLM_REQUEST_TIMEOUT 預設 120 秒；本機模型較慢時要調高。
• PAPERLESS_AI_LLM_EMBEDDING_CHUNK_SIZE 預設 1024；若嵌入模型會截斷輸入、檢索品質變差，就把它調小。
• PAPERLESS_LLM_INDEX_TASK_CRON 控制向量索引的更新排程（只有啟用 AI 且有嵌入後端時才會跑）。
• PAPERLESS_AI_LLM_ALLOW_INTERNAL_ENDPOINTS 預設 true，允許指向內網端點——用本機 Ollama 就是靠這個；反之若你要從公網拉 API，可以設 false 擋掉非公網位址。

沒有 LLM 也能自動分類。這是很多人忽略的一點：標籤、往來對象、文件類型、儲存路徑的建議，用的是在你自己的文件庫上訓練的傳統機器學習模型，不是 LLM，資料不會離開機器，也不需要任何 API key。當你打開一份還掛著 inbox 標籤的文件，系統會自動請求建議；你也可以在「設定 → 文件」關掉自動請求，改成手動按 Suggest。

日常動線：讓文件自己走進來

裝好之後，真正決定你會不會持續用的是動線設計。建議的收納節奏：

幾條實用的小設定：

# 電子郵件自動收單（IMAP）
PAPERLESS_EMAIL_HOST=imap.example.com
PAPERLESS_EMAIL_HOST_USER=you@example.com
PAPERLESS_EMAIL_HOST_PASSWORD=你的密碼
# 消費資料夾改為輪詢（預設 0 = 用原生檔案系統事件；NFS/SMB 分享資料夾建議改成輪詢秒數）
PAPERLESS_CONSUMER_POLLING_INTERVAL=30
# 檔名格式：年 / 往來對象 / 標題
PAPERLESS_FILENAME_FORMAT={{ created_year }}/{{ correspondent }}/{{ title }}

重複文件：v3 的行為變了

這是升級到 v3 之後最容易誤會的地方：v3 預設不再拒收重複文件。如果你丟進一份內容（checksum）與現有文件完全相同的檔案，它仍會被收下，只是在文件詳情頁的 Duplicates 分頁列出內容相同的文件（含垃圾桶裡的，會標示）讓你自己決定留哪一份；任務紀錄也會標記偵測到重複並連到既有文件。

想回到舊行為（消費時直接拒收並刪除重複檔）就設：

PAPERLESS_CONSUMER_DELETE_DUPLICATES=true

備份與還原：這一步絕對不能省

Paperless-ngx 幫你準備了官方的匯出／匯入指令。**最簡單的做法是把 export 目錄定期匯出，連同資料庫備份一起保存。**匯出的目的不是「還原到另一台機器」而已，更重要的是——你永遠可以帶著完整中繼資料離開這套系統（官方 FAQ 也把「一年後想換工具時能不能搬走」列為常見問題）。

# 匯出（文件檔案 + 中繼資料 + 縮圖）
docker compose exec -T webserver document_exporter ../export

# 匯入到新環境
docker compose exec -T webserver document_importer ../export

搭配你的備份策略時要記得三件事：

1. data 與 media 兩個 volume 都要備份（data 放資料庫與索引相關檔案，media 放原始檔與縮圖）。
2. export 目錄才是可攜格式；只複製 volume 不算「能搬家」的備份。
3. 備份要離線。這套系統的資料是明文儲存的，備份檔若跟著主機一起損毀就沒意義了。想延伸可以參考自架 S3 物件儲存這類方案。

安全性紅線與常見搭配

官方 README 用非常直白的語氣寫著：Paperless-ngx 處理的是身分證號、稅務紀錄、發票這類敏感文件，而且資料是以明文儲存、沒有加密，因此絕對不要在不受信任的主機上執行，最安全的方式是在自己家裡的伺服器上跑，並確實做好備份。

在這個前提下，實務上建議這樣組：

Raspberry Pi 效能調校

官方文件給的建議很具體，照抄即可：

PAPERLESS_OCR_PAGES=1              # 只 OCR 第一頁
PAPERLESS_OCR_CLEAN=none           # 換取更快的 OCR
PAPERLESS_ARCHIVE_FILE_GENERATION=never   # 不產生 PDF/A 存檔版本
PAPERLESS_WEBSERVER_WORKERS=1      # 省記憶體
PAPERLESS_TASK_WORKERS=2
PAPERLESS_THREADS_PER_WORKER=1

如果資料庫遇到 SQLite 鎖定問題，再把 PAPERLESS_DBENGINE 換成 PostgreSQL。

適合誰、不適合誰

本站已經介紹過一整套自架工作流：從自架密碼管理、Docker 完整教學，到開源自架服務總整理。Paperless-ngx 是這條路上最容易被忽略、但長期回報最高的一塊——因為它處理的是「你以後一定會想找回來」的東西。

延伸閱讀

• Docker 完整教學 — 本文所有部署步驟的基礎。
• Cloudflare Tunnel 完整教學 2026 — 不想開防火牆 port 就把 Paperless 搬上網。
• Caddy 完整教學 2026 — 用兩行設定換到自動 HTTPS。
• Ollama 本機 LLM 完整教學 — 搭配本文的 AI 功能，讓文件內容完全不外流。
• Marker PDF 完整介紹 — 掃描檔轉 Markdown 的另一條路。

資料來源

• Paperless-ngx GitHub 專案與 README：github.com/paperless-ngx/paperless-ngx
• 官方文件：docs.paperless-ngx.com（Setup、Configuration、Usage、FAQ 章節）
• v3.2.0 release notes（2026-09-19）：GitHub Releases
• 官方 Compose 範本：docker/compose/docker-compose.postgres-tika.yml