在 Synology Docker 與 Nginx Proxy Manager 部署 Paperless-ngx：完整教學

---

為什麼選擇 Paperless-ngx？

• 文件集中管理：PDF、影像檔自動歸檔與索引。
• OCR 支援：可搜尋掃描檔內文字。
• 開源社群活躍：持續更新。
• 支援 Docker：能快速在 NAS 上部署。

搭配 Synology 群暉 NAS，可以做到高效能、低成本的文件管理解決方案。

---

1. 建立資料夾 (Persistent Volume)

在 NAS 建立固定目錄，避免容器刪掉時資料遺失：

mkdir -p /volume1/docker/paperless-ngx/{data,media,export,consume,pgdata}

這些資料夾分別對應：

• data → 系統資料
• media → 文件與 OCR 結果
• export → 匯出檔案
• consume → 丟進去的檔案會自動被處理
• pgdata → PostgreSQL 資料庫資料

---

2. 建立必要容器

PostgreSQL (資料庫)

• 映像檔：postgres:latest
• 容器名稱：postgres-paperless
• 環境變數：

POSTGRES_DB=paperless
POSTGRES_USER=paperless
POSTGRES_PASSWORD=your-password

Volume：

/volume1/docker/paperless-ngx/pgdata:/var/lib/postgresql/data

Redis

• 映像檔：redis:latest
• 容器名稱：redis-paperless
• 環境變數/Volume：無需特別設定

Paperless-ngx Web

• 映像檔：paperlessngx/paperless-ngx:latest
• 容器名稱：paperless-web
• Volume：

/volume1/docker/paperless-ngx/data:/usr/src/paperless/data
/volume1/docker/paperless-ngx/media:/usr/src/paperless/media
/volume1/docker/paperless-ngx/export:/usr/src/paperless/export
/volume1/docker/paperless-ngx/consume:/usr/src/paperless/consume

環境變數：

PAPERLESS_DBHOST=postgres-paperless
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=paperless6789
PAPERLESS_REDIS=redis://redis-paperless:6379

PAPERLESS_SECRET_KEY=隨機長字串
PAPERLESS_TIME_ZONE=Asia/Taipei
PAPERLESS_OCR_LANGUAGE=eng
PAPERLESS_ALLOWED_HOSTS=paper.yourdomain.com,localhost,127.0.0.1,<NAS_IP>
PAPERLESS_URL=https://paper.yourdomain.com
PAPERLESS_CSRF_TRUSTED_ORIGINS=https://paper.yourdomain.com

• Port：

8000:8000

---

3. 自訂網路設定

在 DSM → Docker → 網路 建立一個自訂 bridge 網路 (例如 paperless-net)，並將三個容器都加入，確保能透過容器名稱互相連線。

---

4. 啟動順序

建議依照以下順序啟動：

1. Postgres
2. Redis
3. Paperless Web

---

5. 建立管理員帳號

Paperless-ngx 啟動後會要求你建立管理員帳號，有兩種方式：

• 方式 A：透過網頁介面 打開 http://<NAS_IP>:8000 或 https://paper.yourdomain.com，系統會自動引導你註冊第一個管理員帳號。
• 方式 B：透過命令列 在 DSM Docker → paperless-web → 終端機執行：

python manage.py createsuperuser

兩種方法效果相同，選你方便的即可。

---

6. 配置 Nginx Proxy Manager (NPM)

新增 Proxy Host

• Domain Names：paper.yourdomain.com
• Scheme：http
• Forward Hostname/IP：<NAS_IP>
• Forward Port：8000
• 勾選 Block Common Exploits、Websockets Support

SSL 設定

• 選擇 Request a new SSL Certificate
• 勾選 Force SSL、HTTP/2 Support、（可選）HSTS Enabled

Advanced 設定

proxy_set_header Host              $host;
proxy_set_header X-Real-IP         $remote_addr;
proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

client_max_body_size 100m;
proxy_connect_timeout 600;
proxy_send_timeout    600;
proxy_read_timeout    600;
send_timeout          600;

---

7. 常見問題排查

403 Forbidden / CSRF 驗證失敗

• 檢查 PAPERLESS_URL、PAPERLESS_CSRF_TRUSTED_ORIGINS 是否與實際網域一致
• PAPERLESS_ALLOWED_HOSTS 必須包含當前使用的 Host
• 清理瀏覽器 Cookie 後重試

Redis 無法連線

• 確保 PAPERLESS_REDIS=redis://redis-paperless:6379
• 三個容器必須在同一個自訂網路

PostgreSQL 無法連線

• 確認 PAPERLESS_DBHOST=postgres-paperless
• DB 容器已啟動並能解析名稱

OCR 中文失敗

• 預設僅支援 eng，若要中文需安裝 Tesseract 語言包
• 臨時解法：PAPERLESS_OCR_LANGUAGE=eng

上傳檔案超時

• 在 NPM Advanced 增加 client_max_body_size 與 proxy_read_timeout

---

總結

利用 Synology NAS + Docker + Nginx Proxy Manager，你可以快速在本地環境部署一套 Paperless-ngx 文件管理系統。只要設定好環境變數、Volume、網路，就能穩定運行並支援 HTTPS 存取，完美解決文件數位化、OCR 與安全存取需求。

---