1. paperless-ngx 到底是干什么的，我为什么换掉原来的方案
我最早接触 paperless-ngx，是因为办公室的纸质文件实在堆不下去了。合同、发票、说明书、银行回单、随手记的便签，每个月起码新添几十份，真到要用的时候翻得头大。后来试着把文件全部扫描成 PDF 存网盘，结果发现存进去是存进去了，要找的时候还是只能靠记忆翻文件夹名，扫描件本身是图片，里面的文字一个都搜不出来。那段时间我一度想过自己写一套“按文件名加日期”的归档脚本，但想想后续维护成本就放弃了。
paperless-ngx 的出现正好补上了这个空缺。它是一款开源的、可以自托管的文档管理系统，核心能力是把纸质文档数字化之后自动做 OCR 文字识别、自动打标签、归档，并提供一个支持全文检索的 Web 界面。你只需要把扫描件丢到指定的“消费目录”，它自己会完成剩下的事：识别文字、提取日期和文档类型、存成可搜索的 PDF、建立索引。最后你在网页里随便搜一个关键字，就能把几年前的发票找出来。它适合什么人？我觉得是这几类：家里纸质文件成堆、常年被“找文件”折磨的人；需要长期归档发票、合同、病例等资料的个体；还有想彻底告别文件夹套文件夹、用搜索代替手工整理的效率爱好者。
我最终选择 paperless-ngx 而不是自己折腾其他方案，主要看中三点：
第一，它是社区持续维护的项目，不是那种丢个脚本就跑路的玩具。paperless-ngx 原来是 paperless 的一个分支重命名而来，功能迭代很活跃，Bug 修复也快，而且部署最简单的方式就是官方 Docker Compose 一把梭，几乎没有编译和依赖地狱。
第二，它的自动化程度远超“扫描+重命名+丢网盘”。新版内置了基于随机森林的自动分类模型，你手动给一批文件打好标签、归好类型之后，它就能照着学，后面的文档大部分能自动归类。
第三，它把“查找”这件事做到了真正有用的程度。扫描件经过 OCR 后生成了文字层，你再也不用关心文件名是 IMG_1024.jpg 还是 合同扫描.pdf，直接在搜索框敲关键词就能命中。
下面我会从原理到实操，完整记录我这次从零部署 paperless-ngx 的过程，包括我在生产环境里用到的配置、踩过的坑，以及一套适合个人和中小工作室的归档工作流。内容很实在，照着操作基本可以一次跑通。
2. 核心逻辑拆解：一台“文档黑洞”是怎么工作的
2.1 消费目录：核心入口设计
paperless-ngx 最核心的设计思想是“消费目录”（consume folder）。你可以把它理解成一个共享的收件箱：只要把文件放进去，系统就会定期去检测并处理。
为什么这个设计很重要？因为它把“采集”和“整理”彻底解耦了。扫描仪、手机、微信传输助手，这些入口每天产生的文件都五花八门，但最终它们都能汇聚到同一个目录。paperless-ngx 只需要监控这一个目录，你就不需要安装任何客户端 Agent，也不需要手动上传文件。我现在的做法是：办公桌上放了一台带自动进纸的扫描仪，扫描仪直接输出到 NAS 上的一个共享目录，而我用 Docker 部署的 paperless-ngx 也绑定到这个目录。扫描结束的瞬间，系统就开始处理，基本等于“扫描即归档”。
这里有个细节值得留意：消费目录支持子目录，而且 paperless-ngx 能够识别文件名中的一些特殊标记，比如[日期]、[标签]之类的语法，能在一开始就对文件做粗略分类。不过我个人建议新用户先别用高级语法，老老实实按“文件名+内容”来就好，因为系统后续的 AI 分类足够聪明，手动语法反而容易给自己挖坑。
2.2 一条文档进入系统后的完整流水线
以一个 PDF 扫描件为例，它在 paperless-ngx 内部要经过 7 道工序，理解这条流水线，后面遇到问题才不慌：
- 轮询检测：容器里的 consumer 进程每隔一段时间（可配置，默认每 60 秒）检查一次消费目录，发现有新文件就进入处理队列。
- 等待文件完整写入：如果文件还在被写入（比如扫描仪刚写到一半），系统会检测到文件大小在变化，会等待文件稳定后再开始处理。避免读到一个半截文件。
- 格式转换：如果文件是图片、Word、HTML 或邮件导出件，系统会先把它转换成 PDF。这一步默认由内置的转换能力完成，或者交给可选的 Gotenberg 服务，Gotenberg 还能顺带把 office 文档渲染成标准 PDF。
- OCR 识别：调用 OCRmyPDF 配合 Tesseract，对 PDF 每一页做文字识别，并把识别出来的文字以“隐形文字层”的方式嵌入原 PDF。这一步完成后，你的扫描件就变成了“可以选中文字”的 PDF。
- 元数据解析：把文件交给 Apache Tika 提取内嵌的元数据，比如 PDF 的作者、标题、创建时间等，这些信息会被用来辅助判断文档日期。
- 日期与类型的智能预测：系统会尝试从文件名、OCR 得到的文字内容、元数据中提取文档日期；再用内置的分类模型判断文档类型、归属方、对应标签。
- 归档保存：按配置好的文件名格式和目录结构，把最终 PDF 移动到归档存储目录，并建立全文检索索引。
看起来复杂，但每一步都有成熟组件，稳定性我实测下来是很高的。有时候系统处理一个超大 PDF 会慢些，这是 OCR 的正常开销，不是死机。
2.3 全文检索：为什么搜索又快又准
paperless-ngx 没有用常见的 Elasticsearch，而是直接在 PostgreSQL 里做了全文检索。这听起来有点不常规，但实际效果很好：对个人和中小工作室来说，文档体量通常在几万份以内，Postgres 的 FTS 足够承担，而且少维护一套搜索集群，备份也简单。数据库里存的是文档内容分片和词向量索引，搜索时用tsquery做匹配，还支持中文分词吗？
这里必须提醒一句：中文搜索体验跟语言包和分词能力强相关。paperless-ngx 的全文检索底层用的是 PostgreSQL 自带分词器，默认对中文是“整句分一个 token”的，英文好用不代表中文好用。我实测发现，直接搜索中文文档里的关键词，经常匹配不到。解决方法是给 PostgreSQL 安装zhparser或pg_jieba扩展，让数据库能按中文词语切分。后面我会在配置章节详细说。
2.4 机器学习自动分类：用规矩喂出来的整理助手
paperless-ngx 的自动分类不是一开始就能用的。它的逻辑是：你先手动对文档设置“文档类型”“对应方”“标签”，系统把这些手动结果作为训练数据，训练一个随机森林分类器。之后新文档进来时，分类器会结合 OCR 出的文字内容、文件标题、元数据，给出预测结果。
所以我的建议是：不要一上来就期望它全自动，先人工维护一批典型文档，让它学。比如建好两三个常见文档类型（发票、合同、说明书），每类给它喂十几份样本，效果就比较稳了。如果某类文档格式变化大，可以继续补充训练。
分类模型和更新频率都可以在管理界面里看到，训练过程是自动的，每隔一段时间系统会拿“有明确人工标注”的文档重新训练，不需要额外操作。
3. 实操部署：我完整走通的 Docker Compose 方案
3.1 先评估资源，别下载完就跑不动
paperless-ngx 对硬件的要求不算高，但也不是一个普通网页应用。核心开销在 OCR 和数据库索引。按我的实践：
- CPU：2 核起步。文档量大、PDF 页数多的话，建议 4 核以上。OCR 是多线程的，核心越多处理越快。
- 内存：整个栈（webserver + PostgreSQL + Redis + Gotenberg + Tika）裸跑大约占 1GB 左右；处理大文件时 OCR 会额外吃内存。个人使用建议 2GB 保底，4GB 更舒服。
- 磁盘：归档 PDF 是最终产物，建议单独挂一个大容量卷。另外 OCR 过程中会有临时文件，目录默认在容器内的
/tmp，磁盘读写量不小，尽量用 SSD。
如果只是试用，一台 4 核 8GB 的服务器（物理机、首页高配 NUC、云主机都行）非常够用。没必要一开始就上高配。
3.2 官方 compose 文件逐段解读
paperless-ngx 官方仓库提供了一份 docker-compose.yml 样本，我是在它基础上改的。整个栈包含 6 个服务：
| 服务名 | 镜像 | 职责 |
|---|---|---|
| broker | redis:7 | 消息队列，负责任务调度和状态传递 |
| db | postgres:15 | 主数据库，存文档元数据和全文索引 |
| gotenberg | gotenberg/gotenberg:8 | 文档格式转换，把 Office/HTML 转 PDF |
| tika | apache/tika:latest | 解析文件元数据 |
| webserver | ghcr.io/paperless-ngx/paperless-ngx:latest | 主应用，包含 Web UI 和后台 worker |
| smtp（可选） | 邮件发送服务，不用可以先注释掉 |
先别急着把整份文件拉下来就跑，我看过不少人直接docker compose up -d后一脸懵，因为他们没改几个关键环境变量。下面我给你逐段解释我目前在生产环境用的配置。
3.3 环境变量：改这几个就够，别乱调
compose 文件里的环境变量非常多，但真正新手上路需要关心的其实就这些：
webserver: image: ghcr.io/paperless-ngx/paperless-ngx:latest environment: # 必改：用作 Django 的签名密钥，生产环境不能是默认值 PAPERLESS_SECRET_KEY: "请改成一段够长的随机字符串" # 时区，直接影响日期显示和文件名里的日期 PAPERLESS_TIME_ZONE: "Asia/Shanghai" # OCR 语言，默认只有英文，识别中文必须改 PAPERLESS_OCR_LANGUAGE: "chi_sim+eng" # 消费目录轮询间隔，单位秒，按需调整 PAPERLESS_CONSUMER_POLLING: "60" # 归档文件名格式，建议用这个，按日期/类型/标题组织 PAPERLESS_FILENAME_FORMAT: "{{ created_year }}/{{ correspondent }}/{{ title }}" # Web 地址，用于生成分享链接等，建议写成实际访问域名或IP PAPERLESS_URL: "http://192.168.1.100:8010" # 媒体文件根目录，默认在容器内 /usr/src/paperless，建议挂载持久化 PAPERLESS_MEDIA_ROOT: "/usr/src/paperless/media" volumes: - ./data:/usr/src/paperless/data - ./media:/usr/src/paperless/media - ./consume:/usr/src/paperless/consume - ./export:/usr/src/paperless/export这里面我重点说几个：
PAPERLESS_SECRET_KEY：不改成随机值的话，服务会拒绝启动。生成方式可以用openssl rand -hex 32。PAPERLESS_OCR_LANGUAGE：中文 OCR 必须加chi_sim。如果你的 Tesseract 镜像没内置中文语言包，你得把语言包文件放进去，我后面有一节专门讲这个。PAPERLESS_FILENAME_FORMAT：决定归档后的文件名和目录结构。开始别太花哨，我用的方案是年份/对应方/标题，例如2024/XX物业公司/2024年物业费发票.pdf。也可以直接平铺生成文件名，但文件多了以后，带目录结构会好找很多。PAPERLESS_URL：这个变量不少人忽略，但如果你日后要用“分享链接”功能，或者接入手机 App 扫描后直接上传，这个地址就很重要，最好一开始就配成你打算长期访问的地址。
另外提一句，默认 compose 里还有一堆PAPERLESS_REDIS、PAPERLESS_DBHOST之类的变量，它们已经通过服务名自动连上了，一般不用动。还有PAPERLESS_HTTP_PORT和USERMAP_UID、USERMAP_GID，如果你是在 NAS 上以非 root 用户跑容器，后两个会影响挂载目录的读写权限，我踩过这个坑，下面会讲。
3.4 初始化管理员账号
服务启动后，第一次要创建一个 Django 超级用户：
docker compose run --rm webserver createsuperuser按提示输入用户名、邮箱、密码即可。这步不需要启动整个栈，run --rm会临时起一个容器，等跑完命令就删掉，非常适合初始化。
之后浏览器访问http://你的IP:8010，用刚创建的管理员账号登录。首次登录后建议先进入“管理”界面，把默认文档类型、标签这些基础元数据建好，再到“设置”里调整语言、显示时区等。Web UI 想切成中文，在用户偏好里改语言即可，当前版本的中文翻译整体已经比较完整。
3.5 中文 OCR 语言包：一字不识别时的救急方案
如果你按官方镜像直接跑，PAPERLESS_OCR_LANGUAGE设置成chi_sim+eng之后，系统会尝试内置下载语言包。但在离线环境或者网络受限的情况下，Tesseract 会一直报错。
我的做法是提前把chi_sim.traineddata和eng.traineddata放到挂载进容器的 tessdata 目录。官方镜像里 Tesseract 的语言包路径一般是/usr/share/tesseract-ocr/5/tessdata/，但不同版本路径可能变。更稳妥的做法是单独挂载：
volumes: - ./tessdata:/usr/share/tessdata然后设置环境变量PAPERLESS_TESSDATA_DIR: "/usr/share/tessdata"，把语言包放进宿主机对应的./tessdata目录。语言包哪里来？GitHub 上 tessdata_fast 和 tessdata 仓库都有，选一个和镜像内 Tesseract 大版本匹配的版本下载就行，放进去后重启容器，中文识别立刻就能用了。
字体问题也顺便提一嘴：OCR 识别跟源文件清晰度有很大关系，扫描分辨率建议至少 300 DPI。如果扫描出来文字发虚，再好的识别引擎也没办法。
4. 日常归档：从扫描到检索的完整工作流
4.1 扫描仪接入：最推荐的自动化入口
我的工作流核心是：扫描仪直接输出到消费目录。具体操作是给扫描仪驱动设置“扫描到文件夹”，路径指向 NAS 上被容器挂载为/usr/src/paperless/consume的目录。这样扫描一结束，paperless-ngx 会在几十秒内开始处理。
这里有几个经验值：
- 扫描格式选 PDF 比选 JPG 更省事。JPG 也能处理，但多页文档 JPG 是一张张的，系统默认会把图片合并成 PDF，合的顺序有时候不是你要的，PDF 则不存在这个问题。
- 扫描分辨率 300 DPI 是黄金标准。低于 200 DPI，OCR 的准确率明显下降；高于 600 DPI，文件体积暴涨，处理时间翻倍，识别率提升非常有限。
- 扫描仪的“彩色”和“黑白”选择也影响结果：文字件用黑白，识别速度快，体积小；发票、盖章合同建议彩色保留原始视觉信息。
4.2 手机扫描和远程录入
没有扫描仪的时候，手机也完全可以。直接把拍好的 PDF 传进消费目录即可。更顺滑的方式是用 paperless-ngx 提供的“分享上传”功能，同一个局域网内手机浏览器访问 Web 界面，直接拍照上传，系统会像处理扫描件一样自动归档。
不过我个人的体会是：手机拍照的 OCR 效果受拍摄角度和光照影响很大，歪歪扭扭的票据识别率会打折扣。尽量用正经 PDF 扫描软件，拍完会做透视矫正和对比度增强，识别率能上去不少。网页上传还支持多选文件，批量处理旧文档时很方便。
4.3 邮件消费和网盘消费：值得配置的进阶入口
如果你有长期通过邮件接收电子发票或报表的需求，可以开启邮箱消费功能：设置 POP3/IMAP 地址、账号密码，系统定期去邮箱的指定文件夹拉取邮件附件，然后走同样的 OCR 归档流程。配置在管理界面的“邮件账户”和“邮件规则”里，规则可以按发件人、主题关键字做过滤。
网盘同步我用得不多，但逻辑类似：用 Syncthing 或 rclone 把网盘里的“待归档”目录和消费目录做单向同步，手机上把文件丢进网盘，到电脑上就自动归档了。这算是一个无代码的远程接入方式，挺适合经常在外面跑、文件都从微信发到手机上的场景。
4.4 批量迁移旧文件的正确姿势
把过去几年攒的 PDF 和图片一股脑倒进消费目录听起来很解压，但千万别这么干。一次性塞几百个文档，系统会全部进入处理队列，OCR 会占满 CPU 很长时间，期间你新扫描的文件反而排队排在后面。而且老文件命名乱、内容杂，自动预测的准确率一开始也很低，回头整理标签要哭。
我的建议：分几批导入，每批最多二三十份。导入前先用文件名简单归个类：合同放一起、发票放一起、说明书放一起。这样系统在处理时，同类文档的 OCR 文本模式比较接近，自动分类器能学到更好的规律。导入完进 Web 界面再看一眼，把识别错的地方手动纠正，这就变成了它后续自动分类的训练样本。
5. 这段时间踩过的坑和排查思路
5.1 Redis 版本不匹配导致消费任务堆积
我第一次部署时用的是老教程里的redis:6-alpine镜像，webserver 一直报一些奇怪的连接错误，消费目录里的文件没有被处理。查了半天发现是新版 paperless-ngx 依赖 Redis 7 的某些命令，旧版 Redis 对它不友好。
所以如果你看到容器日志里出现redis.exceptions.ResponseError或者Consumer: no directory ...这类字样，优先检查 Redis 版本。直接用官方 compose 里的redis:7是最省心的。
5.2 挂载目录权限不对导致容器反复重启
在 NAS 或某些 Linux 主机上，容器内进程默认以 root 跑，但挂载的宿主机目录却属于某个普通用户，两边权限对不上，就会出现 webserver 容器启动后立刻退出、日志里全是 Permission denied 的情况。
解决方案有两个：
- 在 compose 文件里给 webserver 加
user: "1000:1000"，把宿主机用户的 UID/GID 显式告诉容器； - 或者设置
USERMAP_UID、USERMAP_GID环境变量，paperless-ngx 官方镜像会在启动时自动把容器内用户映射成对应 UID/GID，并把挂载目录的属主也改掉。
我个人更推荐后者，因为不用自己维护 UID 的一致性。但注意USERMAP_UID要填宿主机上实际拥有挂载目录的那个用户的 UID，用id -u查一下。
5.3 中文 OCR 结果为空或乱码
如果你设置了PAPERLESS_OCR_LANGUAGE: "chi_sim"，但识别出来的文字全是乱码，或者干脆没文字层，大概率是语言包缺失或版本不匹配。用下面的命令检查容器内语言包：
docker compose exec webserver tesseract --list-langs如果列表里没有chi_sim，按照前面 3.5 节的方法放语言包并重启即可。
另一种常见情况是扫描件本身质量太差。比如深色背景上的白字、花哨的艺术字、倾斜严重的文稿，OCR 引擎都容易翻车。这种情况下没有银弹，只能先从扫描质量入手，尽量保证源文件清晰。
5.4 文件名格式配置错误导致归档失败
PAPERLESS_FILENAME_FORMAT这个变量语法很灵活，但也是有风险的。比如我一开始写了类似{{ created_year }}/{{ correspondent }}/{{ title }}/{{ title }}这种路径，结果某些文档标题包含/或\字符，直接导致文件保存失败，整条任务在后台报错。
解决方法是给标题变量加上清洗符。语法上可以在变量名后加| slugify或者使用系统默认的处理逻辑，最优解是控制在归档格式里尽量少用title本身做目录，改成像{{ created_year }}/{{ correspondent }}/{{ created_month }}/{{ id }}这样由系统可控字段组成的结构。系统字段不会出现非法字符，处理起来稳得多。
我现在的归档格式是：
PAPERLESS_FILENAME_FORMAT: "{{ created_year }}/{{ created_month }}/{{ correspondent }}/{{ id }}"文件最终落地变成2024/06/XX物业公司/1234.pdf。配合网页搜索，完全够用。不必强求文件名一看就懂，因为搜索才是第一入口。
5.5 升级版本前必须做的事
paperless-ngx 的升级频率不低，我经历过一次小版本升级把数据库 schema 也改了，如果没有提前备份，起不来的时候真的会慌。官方其实有提供文档导出工具，但最保底的做法是直接备份 PostgreSQL 数据和媒体目录。
简单可靠的备份脚本思路：
# 备份数据库 docker compose exec db pg_dump -U paperless paperless > paperless-db.sql # 备份媒体文件（归档 PDF 和原始文件） tar czf paperless-media.tar.gz ./media # 备份配置文件 tar czf paperless-config.tar.gz ./docker-compose.yml ./.env恢复的时候，先把容器停掉，把备份的数据库文件导回去，再恢复媒体目录，最后启动容器。顺序不能反，否则数据库里的记录和磁盘上的物理文件会对应不上。
5.6 常见问题速查表
| 症状 | 大概率原因 | 处理办法 |
|---|---|---|
| 容器启动后立刻退出 | 挂载目录权限不对 / SECRET_KEY 未配置 | 配置 USERMAP_UID、USERMAP_GID；生成随机 SECRET_KEY |
| 文件放进消费目录没反应 | Redis 版本不对 / consumer 服务停了 | 检查 Redis 版本升级到 7；看 webserver 日志确认 worker 状态 |
| 中文搜不到 | PostgreSQL 缺中文分词扩展或检索配置不对 | 安装 zhparser/pg_jieba，或对标题和内容都建立索引 |
| OCR 结果为空 | 语言包缺失 / 扫描质量差 | 检查 tessdata 语言包；提升扫描分辨率到 300 DPI |
| 文件名格式报错 | 文档标题含非法字符 | 归档格式尽量用系统字段，少用 title 做目录 |
| 上传超大 PDF 网页卡死 | OCR 处理耗时太长占用全部资源 | 调低 OCR 线程或分拆文档，限制单文件大小 |
6. 我的私有经验与细节建议
6.1 标签体系别铺太开
很多人一开始很兴奋，在系统里建了几十个标签，结果标签之间互相重叠，自动分类的学习难度也陡增。我的经验是：标签尽量控制在 15 个以内，按“用途 + 状态”两个维度打就行。比如“合同”“发票”“说明书”是用途类型，“待处理”“已归档”“需要留档”是状态标签。
文档类型（Document Type）是另一个维度，它更接近“这是一份什么类型的法律/财务/行政文件”，我建议单独设置，不要和标签混用。分类器训练时对“文档类型”的预测效果比“标签”更稳定，优先把类型建好。
6.2 归档格式里保留原文件信息
虽然搜索是主入口，但偶尔你还是需要直接去磁盘里找文件。我的建议是在系统里保留原始文件名到一个自定义字段（比如自定义字段 “original_name”），这样即使归档文件名被系统改成1234.pdf，你也能通过 UI 看到原始文件名，遇到需要给外部人员发原始文件的情况时不会找不到。
paperless-ngx 新版本支持自定义字段，在管理界面里加一个“原始文件名”字段，然后消费后自动化规则或手动维护都行。别小看这个细节，真到审计或者交接的时候，很能说明问题。
6.3 备份策略要覆盖数据库和媒体目录
前面备份脚本已经给了，我再强调一次：媒体目录里存的是所有归档 PDF 和原始文件，数据库里存的是索引、标签、预测模型、文档元数据。两者是配合关系，缺一不可。
我日常的备份策略是：数据库每天凌晨做一次pg_dump，保留 7 天；媒体目录每周做一次增量同步到另一块硬盘，保留两个版本。因为文档系统的读多写少，这种频率完全足够。恢复时进 docker compose 里操作，细节照着官方文档走一遍就能回来。
6.4 别把 Web 界面直接暴露到公网
如果你像我一样用的是内网 NAS 部署，默认只在局域网访问就好了，不需要做端口映射。非要公网访问的话，务必在前面加一层反向代理和鉴权，不要裸奔在公网 IP 上。paperless-ngx 默认没有任何多因子认证，一旦端口暴露，你的所有合同、发票、病例可能就全裸了。这不是危言耸听，是我见过不少自托管服务被扫端口攻破的案例。
6.5 自动化规则是好东西，但别一次性配太多
paperless-ngx 的自动化规则（Automation Rules）可以在文档被消费后自动执行动作，比如自动改标签、自动分配属主、自动发通知。功能很好，但我建议把它当成“最后一道关卡”而不是“全程管家”。刚开始只配一两条覆盖最高频的文档类型（比如把来自某个邮箱的发票自动打标签），跑稳了再加。规则越多，相互覆盖导致的意外也越多，到时候排查优先级比写规则还累。
我个人在实际维护中的最大体会是：paperless-ngx 的价值不在于“把文件存起来”，而在于帮你彻底建立一套“从纸到可检索资产”的自动化管道。前期花一点时间把扫描质量、语言包、归档格式这几个基础项调好，后面基本进入“扫描-丢进消费目录-搜索命中”的良性循环。现在再让我回到当年那个翻箱倒柜找发票的状态，我是真的回不去了。
