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 和数据库索引。按我的实践CPU2 核起步。文档量大、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 个服务服务名镜像职责brokerredis:7消息队列负责任务调度和状态传递dbpostgres:15主数据库存文档元数据和全文索引gotenberggotenberg/gotenberg:8文档格式转换把 Office/HTML 转 PDFtikaapache/tika:latest解析文件元数据webserverghcr.io/paperless-ngx/paperless-ngx:latest主应用包含 Web UI 和后台 workersmtp可选邮件发送服务不用可以先注释掉先别急着把整份文件拉下来就跑我看过不少人直接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_simeng # 消费目录轮询间隔单位秒按需调整 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_simeng之后系统会尝试内置下载语言包。但在离线环境或者网络受限的情况下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 DPIOCR 的准确率明显下降高于 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 的价值不在于“把文件存起来”而在于帮你彻底建立一套“从纸到可检索资产”的自动化管道。前期花一点时间把扫描质量、语言包、归档格式这几个基础项调好后面基本进入“扫描-丢进消费目录-搜索命中”的良性循环。现在再让我回到当年那个翻箱倒柜找发票的状态我是真的回不去了。