Paperless-ng 文档管理系统部署指南

系统架构解析

Paperless-ng 是一个现代化的文档管理系统，相比前代产品具有更先进的架构设计。系统采用模块化设计，各组件分工明确，协同工作。

核心组件

1. Web服务器

   • 提供管理界面、API接口和前端展示
   • 可通过Gunicorn或Apache等WSGI服务器启动
   • 启动命令示例：

     cd /path/to/paperless/src/
     gunicorn -c ../gunicorn.conf.py paperless.wsgi
     

2. 文档消费者(Consumer)

   • 监控指定文件夹的新文档
   • 将发现的新文档通知任务处理器
   • 启动命令：

     cd /path/to/paperless/src/
     python3 manage.py document_consumer
     

3. 任务处理器(Task Processor)

   • 基于Django Q框架实现
   • 支持并行处理多个任务
   • 主要功能：
     • 文档消费处理
     • 邮件附件处理
     • 维护搜索索引
     • 执行自动匹配算法
   • 启动命令：

     python3 manage.py qcluster
     

4. Redis消息代理

   • 轻量级消息中间件
   • 负责组件间通信

5. 数据库(可选)

   • 支持PostgreSQL和SQLite

部署方案选择

1. Docker快速安装(推荐)

使用安装脚本(最简单)

curl -L https://raw.githubusercontent.com/jonaswinkler/paperless-ng/master/install-paperless-ng.sh | bash

手动Docker部署

1. 创建配置目录
2. 下载docker-compose配置文件和.env文件
3. 修改配置：
   • 消费目录路径
   • 端口映射
   • 用户UID/GID设置
4. 启动服务：

   docker-compose pull
   docker-compose up -d
   

5. 创建管理员：

   docker-compose run --rm webserver createsuperuser
   

自定义Docker镜像

1. 克隆代码库
2. 修改docker-compose.yml使用本地构建
3. 编译前端
4. 构建镜像：

   docker-compose build
   

2. 裸机安装(适合开发)

系统要求

• Linux系统(推荐Debian/Ubuntu)
• Python 3.6+
• Redis 5.0+
• 可选PostgreSQL

安装步骤

1. 安装依赖包：

   sudo apt install python3 python3-pip python3-dev \
   imagemagick fonts-liberation optipng gnupg libpq-dev \
   libmagic-dev mime-support unpaper ghostscript icc-profiles-free \
   qpdf liblept5 libxml2 pngquant zlib1g tesseract-ocr
   

2. 配置Redis和PostgreSQL

3. 下载并解压Paperless-ng

4. 配置文件调整：

   • 设置Redis连接
   • 配置数据库
   • 指定消费目录
   • 生成随机密钥

5. 创建系统用户：

   adduser paperless --system --home /opt/paperless --group
   

6. 安装Python依赖：

   sudo -Hu paperless pip3 install --upgrade pip
   sudo -Hu paperless pip3 install -r requirements.txt
   

7. 初始化数据库：

   sudo -Hu paperless python3 manage.py migrate
   sudo -Hu paperless python3 manage.py createsuperuser
   

8. 配置系统服务(使用提供的systemd脚本)

最佳实践建议

1. 文件系统选择

   • 避免使用NFS等不支持inotify的文件系统
   • 如需使用，需启用轮询模式：

     PAPERLESS_CONSUMER_POLLING=1
     

2. 性能优化

   • 多核系统可并行处理文档
   • 推荐使用PostgreSQL提升性能
   • 合理设置OCR语言参数

3. 安全建议

   • 务必设置强密钥
   • 生产环境避免使用开发服务器
   • 合理配置用户权限

4. 维护提示

   • 定期检查任务处理器状态
   • 监控消费目录权限
   • 保持系统依赖更新

通过以上部署方案，您可以根据实际需求选择最适合的安装方式，快速搭建起功能完善的Paperless-ng文档管理系统。