Paperless-ngx 无纸化文档管理系统部署教程

Paperless-ngx 是一款开源的文档管理系统，可以将纸质文档扫描件和电子文档统一管理。它通过 OCR 光学字符识别技术自动提取文档文字内容，支持全文搜索、标签分类、自动匹配规则等功能，帮助你告别纸质文档的混乱。本文将介绍如何在搬瓦工 VPS 上使用 Docker 部署 Paperless-ngx。部署前请确保已安装好 Docker 和 Docker Compose。

一、系统要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 2GB，建议 4GB（OCR 处理比较耗内存）。
磁盘：至少 10GB，实际需求取决于文档数量。

二、创建项目目录

mkdir -p /opt/paperless/{consume,data,media,export}
cd /opt/paperless

三、编写 Docker Compose 配置

cat > /opt/paperless/docker-compose.yml <<'EOF'
version: '3.8'

services:
  broker:
    image: redis:7-alpine
    restart: always

  db:
    image: postgres:15-alpine
    restart: always
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: your_db_password
    volumes:
      - postgres_data:/var/lib/postgresql/data

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: always
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: your_db_password
      PAPERLESS_SECRET_KEY: your_random_secret_key
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: your_admin_password
      PAPERLESS_ADMIN_MAIL: admin@example.com
      PAPERLESS_URL: https://docs.yourdomain.com
      PAPERLESS_TIME_ZONE: Asia/Shanghai
      PAPERLESS_OCR_LANGUAGE: chi_sim+eng
      PAPERLESS_OCR_MODE: skip
      PAPERLESS_TASK_WORKERS: 2
      PAPERLESS_CONSUMER_POLLING: 30
      USERMAP_UID: 1000
      USERMAP_GID: 1000
    volumes:
      - /opt/paperless/data:/usr/src/paperless/data
      - /opt/paperless/media:/usr/src/paperless/media
      - /opt/paperless/export:/usr/src/paperless/export
      - /opt/paperless/consume:/usr/src/paperless/consume

volumes:
  postgres_data:
EOF

关键环境变量说明：

PAPERLESS_OCR_LANGUAGE：设置为 chi_sim+eng 支持简体中文和英文 OCR。
PAPERLESS_OCR_MODE：skip 表示如果文档已有文字层则跳过 OCR。
PAPERLESS_CONSUMER_POLLING：每 30 秒扫描一次消费目录。

四、启动 Paperless-ngx

cd /opt/paperless
docker compose up -d

首次启动会自动下载 OCR 语言包，可能需要几分钟：

docker compose logs -f webserver

五、配置 Nginx 反向代理

cat > /etc/nginx/sites-available/paperless <<'EOF'
server {
    listen 80;
    server_name docs.yourdomain.com;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        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;
    }
}
EOF

ln -s /etc/nginx/sites-available/paperless /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d docs.yourdomain.com

六、使用管理面板

访问 https://docs.yourdomain.com，使用配置的管理员账户登录。主要功能模块：

文档列表：浏览、搜索和过滤所有已导入的文档。
上传：通过 Web 界面上传文档。
标签管理：创建和管理文档标签。
通讯员：管理文档来源（发件人/机构）。
文档类型：分类管理（如发票、合同、收据等）。

七、文档导入方式

Paperless-ngx 支持多种文档导入方式：

7.1 消费目录

将文档放入 /opt/paperless/consume/ 目录，Paperless-ngx 会自动检测并处理：

# 将文档复制到消费目录
cp document.pdf /opt/paperless/consume/

7.2 Web 界面上传

在管理面板中点击上传按钮，支持拖拽上传。

7.3 邮件导入

配置邮箱 IMAP 信息后，Paperless-ngx 可以自动从指定邮箱中提取附件并导入。

八、自动分类规则

Paperless-ngx 的智能匹配功能可以自动为新导入的文档分配标签、通讯员和文档类型。在系统设置中创建匹配规则：

精确匹配：根据文档内容中的关键词精确匹配。
正则匹配：使用正则表达式进行灵活匹配。
模糊匹配：基于相似度的模糊匹配。
自动学习：基于机器学习自动分类。

九、数据备份与导出

# 使用内置导出工具
docker compose exec webserver document_exporter ../export

# 备份数据库
docker exec paperless-db-1 pg_dump -U paperless paperless > /opt/paperless/backup_db_$(date +%Y%m%d).sql

# 备份完整数据
tar -czf /opt/paperless/backup_full_$(date +%Y%m%d).tar.gz /opt/paperless/data/ /opt/paperless/media/

十、常见问题

中文 OCR 识别不准确

确保 PAPERLESS_OCR_LANGUAGE 包含 chi_sim。对于繁体中文使用 chi_tra。扫描件的分辨率建议在 300 DPI 以上以获得更好的识别效果。

处理速度慢

OCR 处理比较耗费 CPU 和内存。可以适当增加 PAPERLESS_TASK_WORKERS 的数量（建议不超过 CPU 核心数），或者升级到更高配的 VPS 方案。

总结

Paperless-ngx 是一款出色的自托管文档管理系统，OCR 识别和自动分类功能让文档管理变得智能高效。建议选择 2GB 以上内存的搬瓦工方案来运行 Paperless-ngx。更多教程请参考：Immich 照片管理、Nextcloud 云盘部署、Docker 安装教程。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的循环折扣。