先说问题:文件越来越多,能找出来的越来越少
每个人的文档都在以一种失控的方式增长:租房合同在微信收藏里,发票在邮箱附件里,保单是纸质的塞在抽屉里,产品说明书扫过一次就不知道存哪了。真到要用的时候——报销找发票、维权找合同、报修找保修卡——翻箱倒柜半小时是常态。
网盘能解决「存」的问题,解决不了「找」的问题:文件名起得随手,内容搜不到,扫描件就是一张死图。这一篇的主角 Paperless-ngx 补的正是这一环:它把文档统一收进来,用 OCR 把扫描件和图片变成可搜索的文字,再用标签、通讯方、文档类型自动归档。目标是以后找任何一份文件,只需要记得里面出现过的任意一个词。
本篇主线:
- 用官方 Compose 三件套把 Paperless-ngx 跑起来
- 配好中文 OCR,让中文合同发票也能识别
- 打通消费目录、邮箱、API 等进料通道
- 用匹配规则实现自动打标签、自动归类
- 把备份这件事做对
部署方式延续本系列的一贯路线:Docker Compose 起服务,域名与 HTTPS 交给 Nginx Proxy Manager 统一入口,方法不再重复。
Paperless-ngx 的架构:三个容器各司其职
Paperless-ngx 不是单体应用,官方推荐的 Compose 由三个服务组成:
| 组件 | 镜像 | 职责 |
|---|---|---|
| webserver | ghcr.io/paperless-ngx/paperless-ngx | 主程序:网页界面、OCR、文档消费与搜索 |
| broker | redis:7 | 任务队列:OCR、索引等耗时任务排队执行 |
| db | postgres:16 | 存元数据:标题、标签、通讯方、全文索引 |
文档原文件本身不进数据库,存在 media 卷里;数据库只存「这份文档是谁的、什么时候、讲了什么」。这个分工决定了后面的备份策略:两边都得备,缺一不可。
Docker Compose 部署
在服务器上建目录,把官方结构落下来:
mkdir -p ~/paperless/{export,consume}cd ~/paperlessdocker-compose.yml:
services: broker: image: docker.io/library/redis:7 restart: unless-stopped volumes: - redisdata:/data
db: image: docker.io/library/postgres:16 restart: unless-stopped volumes: - pgdata:/var/lib/postgresql/data environment: POSTGRES_DB: paperless POSTGRES_USER: paperless POSTGRES_PASSWORD: 改成你的数据库密码
webserver: image: ghcr.io/paperless-ngx/paperless-ngx:latest restart: unless-stopped depends_on: - db - broker ports: - "8000: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_SECRET_KEY: 改成一长串随机字符串 PAPERLESS_TIME_ZONE: Asia/Shanghai PAPERLESS_OCR_LANGUAGE: chi_sim PAPERLESS_OCR_LANGUAGES: chi_sim PAPERLESS_ADMIN_USER: admin PAPERLESS_ADMIN_PASSWORD: 改成强密码 USERMAP_UID: 1000 USERMAP_GID: 1000
volumes: data: media: pgdata: redisdata:几个关键点:
PAPERLESS_ADMIN_USER与PAPERLESS_ADMIN_PASSWORD只在首次启动时生效,自动创建管理员账号,之后改密码请在界面里改。USERMAP_UID/GID要和宿主机上你的用户对齐(id命令查看),否则消费目录放进去的文件容器可能读不了。PAPERLESS_SECRET_KEY是加密敏感数据用的密钥,一旦丢失或更换,已保存的邮箱密码等加密字段将无法解开,生成后请连同 Compose 文件一起纳入备份。
启动:
docker compose up -ddocker compose logs -f webserver日志出现应用启动完成字样后,浏览器打开 http://服务器IP:8000,用上面设置的管理员账号登录。首次启动会多花一点时间:容器要按 PAPERLESS_OCR_LANGUAGES 下载中文语言包并初始化数据库。
WARNING8000 端口只是调试入口,正式使用请走反向代理加 HTTPS,并且不要把 Paperless 直接裸奔在公网——里面躺着的是你全部合同、票据和证件扫描件,是家里隐私密度最高的服务之一。访问控制的完整思路见本系列的安全加固篇。
中文 OCR:让中文文档也能被搜到
Paperless 底层用 Tesseract 做 OCR。默认语言是英文,识别中文必须做两件事,上面 Compose 里已经包含:
PAPERLESS_OCR_LANGUAGE: chi_sim——默认 OCR 语言设为简体中文(繁体是chi_tra)。PAPERLESS_OCR_LANGUAGES: chi_sim——官方镜像默认只带英、德、法、意、西几种语言,中文语言包靠这个变量在容器启动时额外下载安装。中英混排文档可以写chi_sim+eng,识别语言一项里把两种都带上。
效果预期要放平:印刷体中文合同、发票识别率相当可用;手写体、歪斜拍照、分辨率太低的图,识别质量会明显下降。扫描环节给三个硬指标:分辨率 300 DPI 起步、页面摆正、光线均匀。手机扫描建议用系统自带「扫描文稿」或专业扫描 App 先生成规整的 PDF 再导入,比直接拍照片再让 OCR 硬啃靠谱得多。
如果存量文档已经入库才改的语言设置,旧文档不会自动重跑 OCR,需要在文档列表里批量选中执行「重新处理」,或者对单份文档在详情页触发。
文档怎么进来:四条进料通道
| 通道 | 适合场景 | 说明 |
|---|---|---|
| 网页上传 | 零散文件随手存 | 登录界面拖拽上传,支持 PDF、图片、Office 文档等 |
| 消费目录 | 扫描仪、手机同步 | 丢进 consume 文件夹的文件会被自动处理并删除原文件 |
| 邮箱抓取 | 发票、对账单 | 配置 IMAP 邮箱与规则,附件自动入库 |
| REST API | 脚本与自动化 | POST /api/documents/post_document/,令牌认证 |
消费目录是最值得打通的一条:把它和本系列 文件同步篇 的 Syncthing 组合起来——手机上扫完的文档同步到服务器的 consume 目录,几秒后就出现在 Paperless 里并完成 OCR 和归类,全程不用手动上传。两个细节:
- 消费目录里的文件被成功处理后会从目录中删除,这是设计行为不是故障;想按子文件夹自动打标签可以开启
PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS。 - 如果
consume挂在网络文件系统上,文件变化通知可能不灵,补一个PAPERLESS_CONSUMER_POLLING: 10让它每 10 秒轮询一次。
邮箱抓取在设置里的「邮件」中配置:先加邮件账户(IMAP 服务器、账号、密码),再建处理规则——按发件人、主题关键词过滤,指定附件处理后把邮件标记已读、移动到指定文件夹或删除。电子发票、对账单这类定期到达的文档,用这条通道可以做到完全无人值守。
自动化归类:标签、通讯方与文档类型
手动给每份文档打标签是不可持续的,Paperless 的自动化靠三类元数据加匹配规则:
- 通讯方(Correspondent):文档的来源方,比如税务局、银行、房东、公司行政。
- 文档类型(Document Type):合同、发票、保单、说明书、账单。
- 标签(Tag):自由维度,比如「待报销」「2026」「重要」。
在管理界面给每一类建好条目后,为条目设置匹配方式:
| 匹配方式 | 行为 |
|---|---|
| 任意词 / 全部词 | OCR 文本里出现指定关键词即命中 |
| 精确匹配 / 正则 | 按整段文本或正则表达式命中 |
| 模糊匹配 | 容忍 OCR 识别错误,适合扫描质量参差的来源 |
| 自动 | 机器学习分类器,根据你已归类好的历史文档自动判断 |
实战建议:先手动认真归类二三十份文档打底,通讯方和文档类型尽量切到「自动」,分类器学到的样本越多越准;关键词特征特别明显的(比如发票上的「增值税专用发票」)用关键词匹配兜底。新版 Paperless 还提供「工作流」功能,可以按「文档新增/消费/更新」触发,自动赋标题模板、标签、通讯方甚至权限,比单条匹配规则更成体系,文档量大了值得迁过去。
标题也建议用模板规范化,比如 {correspondent} - {document_type} - {created},列表里一眼就能扫清。
备份:原文件与数据库,一个都不能少
Paperless 自带导出工具,把全部文档连同元数据导成一个可迁移的目录:
docker compose exec webserver document_exporter ../export导出的 export 目录里有原始文件、归档版 PDF 和一份 manifest.json 元数据清单。换机器恢复时把目录拷回,执行 document_importer 即可完整重建。最忌讳的备份方式是只备份 PostgreSQL 数据库——数据库里没有文档原件,原件全在 media 卷里,只备一半等于没备。
日常备份策略和本系列 备份与迁移篇 一致:document_exporter 定期导出 + pgdata、media、data 三个卷整目录打包,两份材料互相印证,再同步一份到机器之外。
常见问题与排障
放进消费目录的文件没被处理。
先看权限:文件属主与 USERMAP_UID 对不上时容器读不到。再看日志 docker compose logs webserver,消费失败的原因(格式不支持、文件损坏)都会写明。网络盘挂载的目录记得加轮询变量。
中文识别结果一塌糊涂。
九成是源文件质量问题:确认扫描分辨率到 300 DPI、页面没有倾斜。再确认语言变量生效——在文档详情的 OCR 文本里如果全是乱码方块,多半是语言包没装上,重启容器看启动日志有没有下载 chi_sim 的记录。
反向代理后登录一直跳转或提示 CSRF 失败。
通过域名访问时补上环境变量 PAPERLESS_CSRF_TRUSTED_ORIGINS: https://你的域名,并确认反代传递了正确的 Host 头,改完重建容器。
文档量大了界面变卡。
OCR 是吃 CPU 和内存的大户,批量导入时把 PAPERLESS_TASK_WORKERS 按机器核数调(默认会自动取),小内存机器同时跑的消费任务别贪多;搜索慢则多半是数据库没跟上,先给 db 的卷换到 SSD 上再谈调参。
想批量修改已入库文档的标签。 文档列表页勾选多份后有批量编辑功能,可以统一改通讯方、类型和标签,改完分类器的训练样本也随之更新,越用越准。
小结
Paperless-ngx 干的事可以概括成一句话:把「存文件」升级成「存得进、找得出、不用手动整理」的档案系统。部署就是官方三件套 Compose,真正的功夫在后面三件小事上:中文 OCR 语言配对、消费目录和同步工具打通、匹配规则先手动打底再交给自动分类。备份记住原文件和数据库两条腿走路,这个装满全家隐私的服务才算真正落在自己手里。
它是本系列扩充篇的一员,同批的还有 Open WebUI、Immich 与 Gitea,都是把数据和服务握回自己手里的路子。