小岳
2026-11-12
点 赞
0
热 度
2
评 论
0

Paperless-ngx:把纸质文件全部扫进电脑

  1. 首页
  2. 开源分享
  3. Paperless-ngx:把纸质文件全部扫进电脑

文章摘要

摸鱼小助手

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 并用"授权码"

十一、下一步

跑顺之后,通常还会想两件事:

  1. 加一个扫描仪:支持 eSCL/WIA 的网络扫描仪可以直接在网页端点"扫描"(Settings → Scanner)
  2. 配自动化:用 n8n 或系统 cron 定时把某个文件夹的新文件推进 consume

十二、出处与参考

项目以 GPL-3.0 许可开源。命令在 2026-11 的官方镜像上验证;版本迭代较快,配置项名称以官方 configuration 页面为准。


本站站长,主角光环,怎么滴,你还想攻击你的站长吗,真是好big的狗胆

小岳

intp 逻辑家

站长

不具版权性
不具时效性

文章内容不具时效性。若文章内容有错误之处,请您批评指正。

目录

欢迎来到摸鱼干货栈,这里为您提供开源与摸鱼源码

43 文章数
7 分类数
0 评论数
47标签数
最近评论