一套自托管文档管理系统，让 OCR 技术赋予你的扫描件「灵魂」，实现全文检索与智能分类。
📌 项目概览 Paperless-ngx 是一个开源的文档管理系统（DMS），通过OCR（光学字符识别） 技术将物理文档转化为可搜索的数字档案。它由社区维护，是已停止更新的 Paperless-ng 项目的官方继承者。
项目属性 详情 开源协议 MIT License GitHub Stars ~25,000+ Docker Hub 拉取量 10M+ 维护状态 活跃（社区驱动） 官方网站 https://paperless-ngx.com
✨ 核心价值 为什么选择 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 composeexec --user paperless webserver createsuperuser完整 Docker Compose 示例 version : "3.8" services : broker : image : redis: 7 restart : unless- stoppedvolumes : - redisdata: /datadb : image : postgres: 15 restart : unless- stoppedvolumes : - pgdata: /var/lib/postgresql/dataenvironment : POSTGRES_DB : paperlessPOSTGRES_USER : paperlessPOSTGRES_PASSWORD : paperlesswebserver : image : ghcr.io/paperless- ngx/paperless- ngx: latestrestart : unless- stoppeddepends_on : - db- broker- gotenberg- tikaports : - "8010:8000" volumes : - data: /usr/src/paperless/data- media: /usr/src/paperless/media- ./export: /usr/src/paperless/export- ./consume: /usr/src/paperless/consumeenvironment : PAPERLESS_REDIS : redis: //broker: 6379 PAPERLESS_DBHOST : dbPAPERLESS_TIKA_ENABLED : 1 PAPERLESS_TIKA_GOTENBERG_ENDPOINT : http: //gotenberg: 3000 PAPERLESS_TIKA_ENDPOINT : http: //tika: 9998 gotenberg : image : gotenberg/gotenberg: 7.8 restart : unless- stoppedcommand : - "gotenberg" - "--chromium-disable-javascript=true" - "--chromium-allow-list=file:///tmp/.*" tika : image : ghcr.io/paperless- ngx/tika: latestrestart : unless- stoppedvolumes : data : media : pgdata : redisdata : 关键环境变量 变量 用途 示例 PAPERLESS_URL公网访问地址 https://paperless.yourdomain.comPAPERLESS_SECRET_KEYDjango 密钥 python -c "import secrets; print(secrets.token_urlsafe(50))"PAPERLESS_ADMIN_USER初始管理员用户名 adminPAPERLESS_ADMIN_PASSWORD初始管理员密码 your-secure-passwordPAPERLESS_OCR_LANGUAGEOCR 语言 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月 forkfork 背景 ：Paperless-ng 项目停滞，社区成员无权限合并 PR，遂创建 Paperless-ngx 继续开发。
社区渠道 渠道 地址 官方文档 https://docs.paperless-ngx.com GitHub Discussions https://github.com/paperless-ngx/paperless-ngx/discussions GitHub Wiki https://github.com/paperless-ngx/paperless-ngx/wiki Reddit r/selfhosted 社区活跃讨论
安全响应 CVE 类型 修复版本 CVE-2023-46492 SSRF（中危） 1.17.0 CVE-2023-45543 认证绕过（高危） 1.16.3 CVE-2023-42046 XSS（中危） 1.15.1
🎯 适用场景 个人家庭 场景 示例 账单管理 水电燃气、信用卡账单自动归类 税务文档 工资单、完税证明集中归档 医疗记录 家庭健康档案统一管理 家庭资产 房产证、保险单、保修卡
小微企业 场景 示例 发票处理 自动识别发票类型，关联供应商 合同管理 客户合同归档，到期提醒 合规文档 审计材料、资质证书留档 人事档案 员工入职资料、证书认证
📚 参考资源 资源 链接 GitHub 仓库 https://github.com/paperless-ngx/paperless-ngx 官方文档 https://docs.paperless-ngx.com Docker Hub https://hub.docker.com/r/paperless-ngx/paperless-ngx API 文档 https://docs.paperless-ngx.com/api/ Swagger Demo https://demo.paperless-ngx.com/swagger/ 安装指南 https://docs.paperless-ngx.com/setup/ 配置参考 https://docs.paperless-ngx.com/configuration/
结语 Paperless-ngx 是自托管文档管理的标杆项目：功能完整、架构清晰、社区活跃。对于追求隐私控制、成本节约、定制自由的技术用户而言，它是替代商业 DMS 的理想选择。
一句话总结 ：扫描即索引，检索秒级响应，分类自动化——纸质文档的「数字涅槃」。
