系統需求

• 已安裝 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 掛載配置

每個目錄的具體用途：

• 權限要求：確保目錄可讀寫
• 建議：定期備份這些目錄

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 中文社群