Paperless-ngx:把纸质文件全部扫进电脑
读者假设:会敲命令行,没部署过服务。 需要:一台常开的小机器(2 核 2 GB 就够)+ 30 分钟。 读完你能:把一箱纸质文件变成"输入关键词就能搜出来"的电子档案。
一、先算清这笔账
家里/办公室总有一类文件:一年用不到一次,但要用的时候翻箱倒柜——
- 家电保修单(坏了才想起)
- 体检报告(换医院要带上一次的结果)
- 合同、发票、房产资料
- 孩子的疫苗本、入学材料
它们的共同点:低频、关键、容易丢。
云笔记能存 PDF,但搜不了图片里的字;网盘能存,但不会告诉你"这堆 600 个文件里哪张是 2023 年的空调发票"。
Paperless-ngx 干的就这一件事:把扫描件/照片扔进去,它做 OCR(文字识别)、建索引,然后你能像搜网页一样搜自己家的纸。
二、它能干什么
| 能力 | 说明 |
|---|---|
| OCR 全文检索 | 扫描件里的字被识别成文本,搜"保修"能命中那张照片 |
| 自动入库 | 往一个文件夹里丢文件,它自动吃掉并归档 |
| 自动分类 | 按"通信方/文档类型/标签"组织,可配规则自动打标 |
| 邮件导入 | 配一个邮箱,附件自动进库 |
| 多用户 | 一家人各自权限 |
| 原文件保留 | 原始 PDF/图片一直留着,导出时连带元数据一起走 |
| 不依赖云 | 全部存在你自己硬盘上 |
它不是什么:不是网盘、不是笔记软件、不做在线协作编辑。它是档案柜。
三、准备
| 项目 | 最低 | 舒服 |
|---|---|---|
| CPU | 1 核 | 2 核 |
| 内存 | 2 GB | 4 GB(OCR 吃内存) |
| 硬盘 | 文档量 × 3 | 文档量 × 5(含备份) |
| 系统 | 任意能跑 Docker 的 Linux | Ubuntu 22.04/Debian 12 |
| Docker | 20.10+ | 最新 |
Windows/macOS 用 Docker Desktop 也能跑,但建议放在常开的小主机或 NAS 上——档案柜要在你需要它的时候醒着。
四、部署:官方一条命令
Paperless-ngx 官方提供了一个交互式安装脚本,不用手抄 compose:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"
脚本会依次问你几个问题(直接回车用默认值):
1) 数据目录 → ./paperless(回车即可)
2) 端口 → 8000
3) 数据库 → PostgreSQL(推荐)
4) OCR 语言 → eng(后面我们改成中文)
5) 时区 → Asia/Shanghai
6) 管理员用户名/密码 → 自己定,记下来
最后它会生成 docker-compose.yml 和 .env,并提示你执行:
docker compose up -d
你应该看到
[+] Running 4/4
✔ Container paperless-broker Started
✔ Container paperless-db Started
✔ Container paperless-webserver Started
✔ Container paperless-gotenberg Started
四个容器(broker/redis、db、webserver、gotenberg)都 Up 就是起来了。
国内网络拉镜像慢?先给 Docker 配镜像加速,否则
docker compose up会卡在 pulling 很久。这一步不通,后面全都白搭。
五、改三处配置,让中文能搜
打开生成目录里的 .env,改这三行:
# 1) OCR 识别语言:中文简体 + 英文
PAPERLESS_OCR_LANGUAGE=chi_sim+eng
# 2) 让容器额外安装中文语言包(官方镜像默认只带英文)
PAPERLESS_OCR_LANGUAGES=chi_sim
# 3) 时区,影响文档日期和日志
PAPERLESS_TIME_ZONE=Asia/Shanghai
保存后重建容器,让语言包生效:
docker compose up -d
验证语言包装上了
docker compose exec webserver tesseract --list-langs
输出里应该能看到:
eng
chi_sim
看不到 chi_sim 就是没装成功——去 docker compose logs webserver | grep -i language 看日志,通常是镜像源问题或内存不足。
六、第一次用:把文件丢进去
Paperless 有一个神奇的设计:consume 目录。
你的数据目录/
├── consume/ ← 往这里丢文件,它自动吃掉
├── media/ ← 正式归档(别手动动)
├── data/ ← 索引和数据库
└── export/ ← 备份导出位置
操作
# 把一叠 PDF / 扫描图片拷进 consume
cp ~/Desktop/扫描件/*.pdf ./paperless/consume/
大约 10–60 秒后(看文件大小和机器性能),consume/ 里的文件会消失,同时网页端多出这些文档。
网页端
浏览器打开:
http://你的机器IP:8000
用安装时设的账号登录。左边是"文档 / 标签 / 通信方 / 文档类型 / 保存的视图"。
点开任意一篇,右边会显示识别出的文本——能找到字,就说明 OCR 成功。
搜一下
顶部搜索框输入文件里的任意关键词(中文也行):
保修
能命中那张扫描件,这件事就成了。
七、手机拍照怎么进去
纸质文件不一定都有扫描仪——手机拍照 + 自动上传是最实用的路径。
方案 A:手机浏览器
手机连同一 Wi-Fi,打开 http://机器IP:8000,点右上角上传按钮选照片。
方案 B:装客户端
应用商店搜 Paperless Mobile(开源第三方客户端,Android/iOS 都有),填服务器地址和账号,之后拍完直接上传。
拍照时尽量正对、光线均匀、别裁边。OCR 对倾斜和阴影很敏感,歪 15° 识别率就明显下降。
方案 C:邮件导入(懒人首选)
在 .env 里配好 IMAP:
PAPERLESS_EMAIL_HOST=imap.qq.com
PAPERLESS_EMAIL_PORT=993
PAPERLESS_EMAIL_USERNAME=你的邮箱
PAPERLESS_EMAIL_PASSWORD=授权码
PAPERLESS_EMAIL_USE_SSL=true
之后给这个邮箱发邮件,附件自动进库。出差在外拍完直接发邮件,回家就已经归档好了。
八、自动打标签(省掉 90% 的手工活)
Paperless 的杀手功能是匹配规则:同一类文件第一次手动归类,以后自动归。
路径:文档类型 / 通信方 / 标签 → 编辑某个对象 → Matching 里填规则。
举例:给"国家电网"这个通信方加规则:
匹配方式:Content contains
内容:国网
以后任何 OCR 文本里出现"国网"的文档,自动归到"国家电网"名下。
文件名也能自动排:
PAPERLESS_FILENAME_FORMAT={created_year}/{correspondent}/{title}
归档后就是 2026/国家电网/2026-03-电费单.pdf,比 扫描件_0034.pdf 好找一万倍。
九、备份:一定要做,而且很简单
Paperless 的备份分两层:
第一层:原始文件——media/ 目录就是你的 PDF 和图片,直接拷走就行。
第二层:完整导出(带元数据、标签、对应关系):
docker compose exec -T webserver document_exporter ../export
这会在 export/ 下生成一份完整档案(含 manifest)。恢复时:
docker compose exec -T webserver document_importer ../export
建议:每月导出一次,用 rsync 或 restic 同步到另一块硬盘/另一台机器。站内有一篇 restic 备份 可以配合看。
十、九条常见报错
| 现象 | 原因 | 处理 |
|---|---|---|
| 8000 打不开 | 容器还在跑数据库迁移 | docker compose logs -f webserver 等它跑完,首次可能 1–2 分钟 |
| consume 里的文件不消失 | 权限不对 | 在 .env 里设 USERMAP_UID/USERMAP_GID 为本机用户 id(id -u) |
| 中文搜不到 | 语言包没装 | 检查 tesseract --list-langs 有没有 chi_sim |
| OCR 全是乱码 | 扫描分辨率太低 | 300 dpi 以上;手机拍照别压缩 |
| 内存爆掉、容器反复重启 | OCR 并发太高 | 设 PAPERLESS_TASK_WORKERS=1 |
| 日期全是今天 | 文件没有元数据 | 在网页端手动改 Created,或用匹配规则 |
| 上传大 PDF 失败 | 反向代理限制 | Nginx 加 client_max_body_size 100m; |
| 磁盘涨得比预期快 | 每篇都存了原图 + 缩略图 + 归档副本 | 预留 3–5 倍空间,定期清回收站 |
| 邮件导入不工作 | 用的是登录密码而不是授权码 | QQ/163 要开 IMAP 并用"授权码" |
十一、下一步
跑顺之后,通常还会想两件事:
- 加一个扫描仪:支持 eSCL/WIA 的网络扫描仪可以直接在网页端点"扫描"(Settings → Scanner)
- 配自动化:用 n8n 或系统 cron 定时把某个文件夹的新文件推进 consume
十二、出处与参考
- 官网/文档:https://docs.paperless-ngx.com/
- 源码仓库:https://github.com/paperless-ngx/paperless-ngx
- 官方安装脚本:
https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh - 官方 compose 模板:
https://github.com/paperless-ngx/paperless-ngx/tree/main/docker/compose - 配置项全集(
.env每个变量都有说明):https://docs.paperless-ngx.com/configuration/ - Tesseract 语言包:https://github.com/tesseract-ocr/tessdata
项目以 GPL-3.0 许可开源。命令在 2026-11 的官方镜像上验证;版本迭代较快,配置项名称以官方 configuration 页面为准。
默认评论
Halo系统提供的评论