一套自托管文档管理系统，让 OCR 技术赋予你的扫描件「灵魂」，实现全文检索与智能分类。
📌 项目概览
Paperless-ngx 是一个开源的文档管理系统（DMS），通过 OCR（光学字符识别） 技术将物理文档转化为可搜索的数字档案。它由社区维护，是已停止更新的 Paperless-ng 项目的官方继承者。
✨ 核心价值
为什么选择 Paperless-ngx？
| 传统痛点 |
Paperless-ngx 解决方案 |
| 📄 纸质文档堆积成山 |
📱 数字化归档，释放物理空间 |
| 🔍 手翻查找效率低下 |
⚡ 全文 OCR 检索，秒级定位 |
| 🏷️ 人工分类耗时耗力 |
🤖 ML 智能标签，自动归类 |
| 💰 商业 DMS 价格昂贵 |
💸 完全免费，自托管无订阅费 |
| 🔐 云存储隐私担忧 |
🛡️ 本地部署，数据完全自主 |
🔧 核心功能
文档处理能力
| 功能模块 |
技术实现 |
说明 |
| OCR 文字提取 |
Tesseract + OCRmyPDF |
支持 100+ 语言，从 PDF/图片中提取可搜索文本层 |
| 智能分类 |
机器学习模型 |
根据文档内容自动建议标签、联系人、文档类型 |
| 双文件消费 |
原始文件 + 搜索 PDF |
保留原件，同时生成带 OCR 层的可搜索 PDF |
组织管理体系
| 元数据维度 |
用途 |
| Tags（标签） |
灵活的层级标签系统，如「财务/税务/发票」 |
| Correspondents（联系人） |
记录文档来源，如「税务局」「电力公司」 |
| Document Types（文档类型） |
分类归档，如「合同」「发票」「凭证」 |
| Custom Fields（自定义字段） |
扩展元数据，满足特定业务需求 |
| Storage Paths（存储路径） |
自定义文件存储规则 |
输入方式
| 入口 |
适用场景 |
| 监控文件夹（Consume Directory） |
扫描仪自动投递、批量导入 |
| 邮件采集 |
自动导入指定邮箱的邮件附件 |
| Web 界面上传 |
手动拖拽上传，即时处理 |
| REST API |
程序化集成，自动化流水线 |
用户界面
- 🌙 深色模式：护眼主题
- 📊 仪表盘统计：文档分布可视化
- ✏️ 批量编辑：多文档属性同时修改
- 🔗 分享链接：生成临时分享 URL
- 📱 响应式设计：移动端友好
🏗️ 技术架构
技术栈一览
| 层级 |
技术选型 |
| 后端语言 |
Python 3.10+ |
| Web 框架 |
Django + Django REST Framework |
| 前端框架 |
Angular 15+（TypeScript） |
| UI 样式 |
Bootstrap 5 + Angular Material + SCSS |
| 任务队列 |
Celery + Redis |
| 数据库 |
SQLite（开发）/ PostgreSQL（生产推荐） |
| 搜索引擎 |
Whoosh（内嵌 Python 库） |
| OCR 引擎 |
OCRmyPDF + Tesseract |
Docker 服务架构
┌─────────────────────────────────────────────────────────────┐
│ Paperless-ngx 容器架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Webserver │ │ Broker │ │ DB │ │
│ │ (Django + │ │ (Redis) │ │ (PostgreSQL) │ │
│ │ Gunicorn) │ │ │ │ │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ │ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Gotenberg │ │ Tika │ ← 文档转换服务 │
│ │ (Office→PDF) │ │ (文本提取) │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Celery Workers │ │
│ │ (OCR 处理 | 缩略图生成 | 搜索索引 | 定时任务) │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
OCR 处理流水线
文档上传
↓
预处理（图像清洁、倾斜校正）
↓
OCRmyPDF + Tesseract
↓
添加文本层到 PDF
↓
Whoosh 全文索引
↓
可搜索文档入库
API 设计
| 特性 |
实现 |
| API 类型 |
RESTful API |
| 文档规范 |
OpenAPI Schema |
| 交互式文档 |
Swagger UI（/swagger/） |
| 认证方式 |
API Token（用户配置页生成） |
核心端点：
/api/documents/ --- 文档 CRUD/api/tags/ --- 标签管理/api/search/ --- 全文检索/api/tasks/ --- 后台任务状态
🚀 安装部署
部署方式
Docker Compose 是官方推荐的部署方式。
快速启动
# 1. 创建目录结构
mkdir -p ./paperless-ngx/{data,media,export,consume}
# 2. 下载官方 compose 配置
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.yml
# 3. 配置环境变量
cp docker-compose.env .env
# 编辑 .env 文件，设置关键参数
# 4. 启动服务
docker compose up -d
# 5. 创建管理员账户（如未在 env 中设置）
docker compose exec --user paperless webserver createsuperuser
完整 Docker Compose 示例
version: "3.8"
services:
broker:
image: redis:7
restart: unless-stopped
volumes:
- redisdata:/data
db:
image: postgres:15
restart: unless-stopped
volumes:
- pgdata:/var/lib/postgresql/data
environment:
POSTGRES_DB: paperless
POSTGRES_USER: paperless
POSTGRES_PASSWORD: paperless
webserver:
image: ghcr.io/paperless-ngx/paperless-ngx:latest
restart: unless-stopped
depends_on:
- db
- broker
- gotenberg
- tika
ports:
- "8010:8000"
volumes:
- data:/usr/src/paperless/data
- media:/usr/src/paperless/media
- ./export:/usr/src/paperless/export
- ./consume:/usr/src/paperless/consume
environment:
PAPERLESS_REDIS: redis://broker:6379
PAPERLESS_DBHOST: db
PAPERLESS_TIKA_ENABLED: 1
PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
PAPERLESS_TIKA_ENDPOINT: http://tika:9998
gotenberg:
image: gotenberg/gotenberg:7.8
restart: unless-stopped
command:
- "gotenberg"
- "--chromium-disable-javascript=true"
- "--chromium-allow-list=file:///tmp/.*"
tika:
image: ghcr.io/paperless-ngx/tika:latest
restart: unless-stopped
volumes:
data:
media:
pgdata:
redisdata:
关键环境变量
| 变量 |
用途 |
示例 |
PAPERLESS_URL |
公网访问地址 |
https://paperless.yourdomain.com |
PAPERLESS_SECRET_KEY |
Django 密钥 |
python -c "import secrets; print(secrets.token_urlsafe(50))" |
PAPERLESS_ADMIN_USER |
初始管理员用户名 |
admin |
PAPERLESS_ADMIN_PASSWORD |
初始管理员密码 |
your-secure-password |
PAPERLESS_OCR_LANGUAGE |
OCR 语言 |
eng（英语）/ chi_sim（简体中文） |
PAPERLESS_TIME_ZONE |
时区设置 |
Asia/Shanghai |
硬件需求
| 项目 |
最低配置 |
推荐配置 |
| 内存 |
2GB |
4GB+（OCR 资源密集） |
| CPU |
单核 |
多核（并行处理加速） |
| 存储 |
10GB |
SSD（IO 性能提升） |
| 数据库 |
SQLite |
PostgreSQL（>1000 文档或多用户） |
支持平台
| 平台 |
说明 |
| Ubuntu / Debian |
服务器首选 |
| Raspberry Pi |
Pi 4/5（4GB+ RAM） |
| Synology DSM / QNAP QTS |
NAS 内置 Docker |
| macOS / Windows（WSL2） |
本地开发测试 |
🔗 集成生态
认证集成
| 提供商 |
类型 |
| LDAP / Active Directory |
目录服务 |
| Keycloak / Authentik / Authelia |
OIDC/OAuth |
存储后端
| 后端 |
用途 |
| 本地文件系统 |
默认存储 |
| AWS S3 / MinIO |
云端/私有对象存储 |
| Azure Blob / GCS |
云厂商对象存储 |
自动化集成
| 平台 |
集成方式 |
| Home Assistant |
官方集成组件 |
| n8n / Zapier / Node-RED |
Webhook/API |
| Telegram / Slack / Gotify |
通知推送 |
AI 增强
- paperless-ai：接入 OpenAI/Anthropic/Ollama，实现 AI 驱动的智能标签
📈 社区生态
项目演进历程
Paperless（原始项目，已停止维护）
↓
Paperless-ng（增强版，已停止维护）
↓
Paperless-ngx（社区继承者，活跃维护） ← 2022年1月 fork
fork 背景：Paperless-ng 项目停滞，社区成员无权限合并 PR，遂创建 Paperless-ngx 继续开发。
社区渠道
安全响应
| CVE |
类型 |
修复版本 |
| CVE-2023-46492 |
SSRF（中危） |
1.17.0 |
| CVE-2023-45543 |
认证绕过（高危） |
1.16.3 |
| CVE-2023-42046 |
XSS（中危） |
1.15.1 |
🎯 适用场景
个人家庭
| 场景 |
示例 |
| 账单管理 |
水电燃气、信用卡账单自动归类 |
| 税务文档 |
工资单、完税证明集中归档 |
| 医疗记录 |
家庭健康档案统一管理 |
| 家庭资产 |
房产证、保险单、保修卡 |
小微企业
| 场景 |
示例 |
| 发票处理 |
自动识别发票类型，关联供应商 |
| 合同管理 |
客户合同归档，到期提醒 |
| 合规文档 |
审计材料、资质证书留档 |
| 人事档案 |
员工入职资料、证书认证 |
📚 参考资源
结语
Paperless-ngx 是自托管文档管理的标杆项目：功能完整、架构清晰、社区活跃。对于追求隐私控制、成本节约、定制自由的技术用户而言，它是替代商业 DMS 的理想选择。
一句话总结：扫描即索引，检索秒级响应，分类自动化------纸质文档的「数字涅槃」。