📌 项目地址：paperless-ngx/paperless-ngx | ⭐ 41,283 颗星 | 🔧 Python | 📜 未标注
这东西解决什么问题
你手头有合同、发票、病历、收据的扫描件或照片吗？它们散落在硬盘、手机、云盘里，想找一张三年前的发票要翻半小时。Paperless-ngx 是一个自托管的文档管理系统，把 PDF 和图片丢进去，它自动做 OCR、按规则分类、建全文索引，之后你搜个关键词就能定位文件。
它其实是 Paperless 和 Paperless-ng 的官方继任者。目前 GitHub 上 41,283 个 Star，维护活跃，每两周发一次 release。你可以在官方 demo 上先试试：https://demo.paperless-ngx.com ，登录用 demo / demo。我自己传了一张手机拍的中文收据，几秒后文字被识别出来，按我设定的规则（内容含“发票”且金额>100）自动归到了“杂项发票”分类。
安装：一条命令搞定
官方推荐 Docker Compose。仓库的 /docker/compose 目录里已经写好了配置文件。最省事的方法是直接跑官方安装脚本：
bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"这个脚本自动从 GitHub Container Registry 拉镜像，生成 docker-compose.yml 和 docker-compose.env，然后启动容器。你不需要手写任何 YAML。如果你需要自定义数据库（比如 PostgreSQL 替代默认的 SQLite）、挂载 NAS 目录、配置反向代理，就去读文档：https://docs.paperless-ngx.com/setup/#installation
我自己的体验：跑在一台 4 核 8G 的 Intel NUC 上，处理 300 页的扫描件（每页 200dpi 黑白 PDF）大约 10 秒完成 OCR，内存占用约 1.2GB。如果机器配置低，可以设置环境变量 PAPERLESS_OCR_THREADS=2 减少并行任务，避免拖慢其他服务。
核心工作流：丢进去，自动处理
Paperless-ngx 的处理流程分三步，全部自动化，不需要人工干预。
1. OCR 识别
底层用的是 Tesseract，官方 Docker 镜像已内置，支持中文、英文、日文等几十种语言。如果你只处理中文文档，可以在环境变量里只配 PAPERLESS_OCR_LANGUAGE=chi_sim，省掉加载其他语言模型的时间。识别效果关键看你原始图片的分辨率，300dpi 以上基本没问题。
2. 自动分类与元数据抽取
你可以在管理后台定义多条匹配规则。规则可以基于文件名、内容里的关键词、日期，甚至正则表达式。例如：文件名包含“invoice”或“发票”，就自动打上“发票”标签、指定对应方（correspondent）为“某公司”、文档类型为“发票”。规则按顺序匹配，一旦匹配就不再继续。还可以用机器学习分类器，它根据你手动标记的历史样本学习，但需要你前期打标足够（至少 100 份文档才比较准）。
3. 全文索引
所有文本、标签、对应方、文档类型都存入数据库，支持模糊搜索、布尔查询（AND/OR/NOT）、日期范围、标签组合过滤。搜索结果用关键词高亮显示，点击就能预览原文。数据库默认是 SQLite，量大的话可以换 PostgreSQL。
从 Paperless-ng 迁移：换镜像就行
如果你之前用的是 Paperless-ng，迁移简单到令人意外：停掉旧容器，把镜像 tag 改成 ghcr.io/paperless-ngx/paperless-ngx:latest，重新启动。数据库和 media 目录完全兼容。不过我还是建议先备份数据库（默认 SQLite 文件在 /data/db.sqlite3）和 /data/media 目录。迁移文档：https://docs.paperless-ngx.com/setup/#migrating-to-paperless-ngx
如果你用的是最早的 Paperless（the-paperless-project/paperless），数据格式差异太大，官方没有迁移路径。你需要手动导出再导入，或者重新处理一遍原始文件。注意：旧版 Paperless 已经停止维护，Paperless-ngx 完全不兼容它的数据库。
社区与文档质量
- CI：GitHub Actions 跑测试，Codecov 显示测试覆盖率（目前约 80%+），代码质量透明。
- 文档：从安装、配置、API 到开发指南都非常详细，是同类项目里最好的。地址：https://docs.paperless-ngx.com
- 翻译：Crowdin 平台有社区翻译，中文界面覆盖率超过 95%，几乎没有英文残留。
- 交流：Matrix 频道
#paperlessngx:matrix.org活跃。我周三问过 OCR 配置问题，当天就有人回复。 - 许可证：GPL-3.0，可商用，无需担心合规问题。
实际使用注意事项
我踩过几个坑，写出来帮你省时间。
OCR 速度
默认会用所有 CPU 核心。如果你在同一台机器上跑着 Jellyfin、Nextcloud 等服务，设置 PAPERLESS_OCR_THREADS=2 或更少，避免 CPU 被占满。
消费目录权限
Docker 容器内的用户 UID 是 1000。如果你挂载了宿主目录作为消费目录（比如 /opt/paperless/consume），要确保宿主目录的 owner 是 UID 1000，或者 1000 所在组有读写权限。否则容器无法消费文件，文档会一直卡在“等待处理”状态。
文件名处理
Paperless-ngx 默认把文件重命名为“日期-标题”，原文件名只存在数据库里。如果你希望保留原始文件名，可以在管理后台的“文档文件名格式”里改成 {original_filename} 或其他组合。这一点很适合需要和他人共享文件的场景。
你需要自己搞定的周边
Paperless-ngx 只管存储和搜索，不处理扫描输入和备份。
- 扫描：手机 app（Adobe Scan、Microsoft Lens、vFlat）或实体扫描仪。
- 文件导入：可以用 Syncthing 把手机里的扫描件自动同步到消费目录，或者用 Paperless-ngx 的 REST API 上传。也有第三方移动客户端（如 Paperless Mobile 等）。
- 备份：定期备份数据库和 media 目录。如果用的是 Docker 卷，可以用
docker run --volumes-from备份，或者直接打包卷路径。官方没有提供自动化备份方案，需要自己写脚本或配合 cron。
对于已经攒了一批扫描件或照片的人来说，Paperless-ngx 是目前最省心的自动化归档工具。项目还在快速迭代，bug 修复勤快。