系統需求
- 已安裝 1Panel 控制面板
- 至少 2GB RAM(建議 4GB 以上,OCR 需要較多內存)
- 至少 10GB 存儲空間(視文檔量增長)
- 已準備好域名和 SSL 證書
- 確保服務器防火牆開放必要端口(80/443)
前置服務部署
1. PostgreSQL 數據庫部署
基本配置:
- 進入 1Panel 應用商店
- 搜索並選擇 PostgreSQL
- 選擇版本:
postgres:13
詳細設置:
- 容器名稱:
paperless-db
- 網路選擇:
1panel-network
- 記錄自動生成的:
- 數據庫名稱
- 用戶名
- 密碼
- 記錄容器 IP 地址(例:
172.18.0.2
)
2. Redis 快取服務部署
基本配置:
- 進入 1Panel 應用商店
- 搜索並選擇 Redis
- 選擇版本:
redis:7
詳細設置:
- 容器名稱:
paperless-redis
- 網路選擇:
1panel-network
- 記錄自動生成的密碼
- 記錄容器 IP 地址(例:
172.18.0.3
)
3. 創建必要目錄
在部署 Paperless-ngx 之前,需要創建所需的目錄:
# 創建主目錄
mkdir -p /opt/1panel/apps/paperless
# 創建子目錄
mkdir -p /opt/1panel/apps/paperless/data # 配置文件和數據
mkdir -p /opt/1panel/apps/paperless/media # 處理後的文檔
mkdir -p /opt/1panel/apps/paperless/export # 導出文件
mkdir -p /opt/1panel/apps/paperless/consume # 自動導入目錄
# 設置目錄權限
chmod -R 755 /opt/1panel/apps/paperless
Paperless-ngx 部署步驟(按界面順序)
1. 基本配置
1.1 名稱設置
- 說明:容器的識別名稱
- 建議名稱:
paperless-ngx
- 注意:使用小寫字母,避免特殊字符
- 用途:用於容器管理和日誌查看
1.2 鏡像配置
- 選擇「手動輸入」
- 鏡像地址:
ghcr.io/paperless-ngx/paperless-ngx:latest
- 「強制拉取鏡像」說明:
- 勾選:每次都重新下載最新鏡像
- 不勾選:本地有緩存時使用緩存
- 建議:首次部署時建議勾選,確保使用最新版本
1.3 埠配置
- 選擇「暴露埠」
- 配置說明:
- 本機埠:
8000
(可修改) - 容器埠:
8000
(固定) - 用途:Web 界面訪問端口
- 注意:如果 8000 被占用,可以修改本機埠為其他值
1.4 網路配置
- 選擇:
1panel-network
- 重要性:必須選擇此網絡
- 原因:
- 確保與 Redis 和 PostgreSQL 通信
- 使用 Docker 內部網絡,提高安全性
- 避免不必要的端口暴露
1.5 掛載配置
每個目錄的具體用途:
本地目錄 | 容器目錄 | 用途 |
---|---|---|
/opt/1panel/apps/paperless/data |
/usr/src/paperless/data |
配置文件和數據庫 |
/opt/1panel/apps/paperless/media |
/usr/src/paperless/media |
處理後的文檔 |
/opt/1panel/apps/paperless/export |
/usr/src/paperless/export |
導出文件目錄 |
/opt/1panel/apps/paperless/consume |
/usr/src/paperless/consume |
自動導入目錄 |
- 權限要求:確保目錄可讀寫
- 建議:定期備份這些目錄
1.6 高級選項
- Command 和 Entrypoint:保持默認為空,除非需要特殊啟動參數
- 特權模式:建議保持關閉,非必要不開啟特權
- 控制臺交互:
- 偽終端(-t):調試時可開啟
- 標準輸入(-i):一般無需開啟
1.7 重啟策略
選項說明:
- 不重啟:容器關閉後不自動重啟
- 一直重啟:無論何種情況都重啟
- 失敗後重啟:僅在容器異常退出時重啟
- 未手動停止則重啟:適用於需要維護的情況
建議:選擇「失敗後重啟」,預設重啟次數 5 次
1.8 資源限制
- CPU 配置:
- CPU 權重:
1024
(默認值) - CPU 限制:
0
:不限制- 建議值:
2-4
核(根據需求)
- 說明:OCR 處理時 CPU 佔用較高
- 記憶體限制:
- 設置為
0
:不限制 - 建議值:
2048MB
起 - 注意:OCR 處理大文件需要更多內存
1.9 標籤配置
重要標籤說明:
org.opencontainers.image.title=paperless-ngx
:容器標識名稱org.opencontainers.image.authors=paperless-ngx team <hello@paperless-ngx.com>
:開發團隊信息org.opencontainers.image.created=2025-01-31T15:58:42.382Z
:鏡像創建時間org.opencontainers.image.description=A community-supported supercharged version of paperless: scan, index and archive all your physical documents
:項目描述org.opencontainers.image.documentation=https://docs.paperless-ngx.com/
:文檔地址
1.10 環境變數詳解
基本配置:
# 語言設置
LANGUAGE_CODE=zh-tw # 界面語言
PAPERLESS_LANGUAGE=zh-tw # 系統語言
PAPERLESS_TIME_ZONE=Asia/Taipei # 時區設置
# 數據庫配置
PAPERLESS_DBHOST=172.18.0.2 # PostgreSQL 容器 IP
PAPERLESS_DBPORT=5432 # 數據庫端口
PAPERLESS_DBNAME=paperless # 數據庫名
PAPERLESS_DBUSER=your-db-user # 數據庫用戶
PAPERLESS_DBPASS=your-db-password # 數據庫密碼
# Redis 配置
PAPERLESS_REDIS=redis://:your-redis-password@172.18.0.3:6379
# 格式:redis://:密碼@Redis 容器 IP:端口
# 管理員設置
PAPERLESS_ADMIN_USER=your-admin-user # 管理員賬號
PAPERLESS_ADMIN_PASSWORD=your-admin-password # 管理員密碼
# OCR 設置
PAPERLESS_OCR_LANGUAGES=chi-tra chi-tra-vert # 繁體中文識別
PAPERLESS_OCR_LANGUAGE=chi_tra+eng # 支持中英文
# 安全設置
PAPERLESS_SECRET_KEY=your-random-string # 系統安全密鑰
PAPERLESS_ALLOWED_HOSTS=your-domain,localhost,127.0.0.1,172.18.0.*
PAPERLESS_CSRF_TRUSTED_ORIGINS=https://your-domain
# 性能設置
PAPERLESS_WORKERS=2 # OCR 工作進程數
常見問題與解決方案
1. 系統訪問問題
- 無法訪問網頁:
- 檢查端口映射
- 確認域名解析
- 驗證 SSL 證書
- 登入失敗:
- 確認賬號密碼
- 檢查數據庫連接
- 查看錯誤日誌
2. OCR 相關問題
- 識別失敗:
- 確認語言包安裝
- 檢查文件權限
- 驗證內存充足
- 處理速度慢:
- 調整 worker 數量
- 增加 CPU 限制
- 優化文件大小
參考資料
- 官方資源:
- Paperless-ngx 文檔
- Github
- Docker Hub
- 中文資源:
- 1Panel 官方文檔
- Docker 中文社群
正文完