2695 字
13 分钟
Paperless-ngx:文档票据数字化归档与全文搜索
2026-11-15

先说问题:文件越来越多,能找出来的越来越少#

每个人的文档都在以一种失控的方式增长:租房合同在微信收藏里,发票在邮箱附件里,保单是纸质的塞在抽屉里,产品说明书扫过一次就不知道存哪了。真到要用的时候——报销找发票、维权找合同、报修找保修卡——翻箱倒柜半小时是常态。

网盘能解决「存」的问题,解决不了「找」的问题:文件名起得随手,内容搜不到,扫描件就是一张死图。这一篇的主角 Paperless-ngx 补的正是这一环:它把文档统一收进来,用 OCR 把扫描件和图片变成可搜索的文字,再用标签、通讯方、文档类型自动归档。目标是以后找任何一份文件,只需要记得里面出现过的任意一个词。

本篇主线:

  1. 用官方 Compose 三件套把 Paperless-ngx 跑起来
  2. 配好中文 OCR,让中文合同发票也能识别
  3. 打通消费目录、邮箱、API 等进料通道
  4. 用匹配规则实现自动打标签、自动归类
  5. 把备份这件事做对

部署方式延续本系列的一贯路线:Docker Compose 起服务,域名与 HTTPS 交给 Nginx Proxy Manager 统一入口,方法不再重复。

Paperless-ngx 的架构:三个容器各司其职#

Paperless-ngx 不是单体应用,官方推荐的 Compose 由三个服务组成:

组件镜像职责
webserverghcr.io/paperless-ngx/paperless-ngx主程序:网页界面、OCR、文档消费与搜索
brokerredis:7任务队列:OCR、索引等耗时任务排队执行
dbpostgres:16存元数据:标题、标签、通讯方、全文索引

文档原文件本身不进数据库,存在 media 卷里;数据库只存「这份文档是谁的、什么时候、讲了什么」。这个分工决定了后面的备份策略:两边都得备,缺一不可。

Docker Compose 部署#

在服务器上建目录,把官方结构落下来:

Terminal window
mkdir -p ~/paperless/{export,consume}
cd ~/paperless

docker-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 文件一起纳入备份。

启动:

Terminal window
docker compose up -d
docker compose logs -f webserver

日志出现应用启动完成字样后,浏览器打开 http://服务器IP:8000,用上面设置的管理员账号登录。首次启动会多花一点时间:容器要按 PAPERLESS_OCR_LANGUAGES 下载中文语言包并初始化数据库。

WARNING

8000 端口只是调试入口,正式使用请走反向代理加 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 自带导出工具,把全部文档连同元数据导成一个可迁移的目录:

Terminal window
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,都是把数据和服务握回自己手里的路子。

Paperless-ngx:文档票据数字化归档与全文搜索
https://www.anexns.cloudns.org/posts/selfhost-paperless-ngx/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0