[Python] Paperless-ngx：用 Django 搭建文档管理系统

开篇

扫描的PDF堆满硬盘却搜不到想要的那份？纸质发票归档后再也找不到？今天拆解一个GitHub 3万+星的开源项目Paperless-ngx，看它如何用Django构建智能文档归档系统。

---

项目介绍

Paperless-ngx是一个基于Django的自托管文档管理系统，核心功能是通过OCR技术将纸质文档转为可搜索的数字档案。技术栈采用Django后端、Angular前端和PostgreSQL数据库。

---

架构设计

三进程分离架构

系统采用生产者-消费者模式，拆分为三个独立进程：

Web Server层

• 基于Gunicorn和Django提供REST API
• 处理文档查询和用户请求
• 启动命令：gunicorn paperless.wsgi

Document Consumer层

• 监控consume目录的新增文件
• 将文档处理任务推送到Redis队列
• 启动命令：python manage.py document_consumer

Task Processor层

• 使用Django-Q从队列拉取任务
• 执行OCR识别和智能分类
• 支持配置多个worker并行处理

数据处理流程

文档上传后，Consumer检测到新文件并推送到Redis队列，Django-Q从队列取出任务进行OCR识别，最后将结构化数据存入PostgreSQL。这种设计让文档上传立即返回，耗时的OCR处理在后台完成。

---

技术特点

任务队列选型

项目使用Django-Q而非常见的Celery，原因是Django-Q与Django原生集成更好，配置简单，支持定时任务和失败重试，依赖Redis作为消息队列。

OCR引擎支持

系统支持多种文档解析器：

• Tesseract：开源OCR引擎，支持100多种语言
• Tika：Apache项目，处理Office文档
• Gotenberg：PDF转换工具

通过抽象Parser接口，可以灵活切换不同引擎。

智能分类功能

内置自动匹配算法，根据文档内容自动打标签、分配类型和存储路径。系统会基于历史数据学习，使用越久准确率越高。

---

部署方式

Docker Compose部署

项目提供docker-compose.yml配置文件，包含webserver、redis和postgres三个服务，运行docker-compose up -d即可启动。

裸机部署步骤

需要先安装Redis和PostgreSQL，然后配置paperless.conf文件，分别启动webserver、consumer和qcluster三个进程。

---

适用场景

这个系统适合企业文档归档场景，比如合同、发票、报告的统一管理；也适合个人知识库建设，将扫描的书籍和笔记数字化；还可以用于财务系统，实现票据OCR识别后自动入账。

---

架构启示

从这个项目可以看到几个设计思路：

一是职责分离。监控、处理、展示三层解耦，每层可以独立扩展。

二是异步优先。耗时任务放到后台处理，提升用户体验。

三是技术务实。Django-Q比Celery轻量，对于中小规模应用够用就好。

四是开放集成。提供RESTful API支持二次开发。

对于需要构建文档管理系统的团队，这套架构值得参考。

---

关注我们

《云栈后端架构》专注后端开发与架构设计，每周拆解优质开源项目，分享实战经验。

👉 关注公众号，获取更多技术干货

---

项目资源

GitHub仓库
https://github.com/paperless-ngx/paperless-ngx

官方文档
https://docs.paperless-ngx.com

1024程序员节课程推荐  

Java就业班 : https://yunpan.plus/t/412-1-1
Python大数据 : https://yunpan.plus/t/417-1-1
爬虫+JS逆向 : https://yunpan.plus/t/419-1-1

---

标签：#Paperless-ngx #Github #Django #文档管理系统 #OCR技术 #后端架构