企业官网建设流程全解析

Paperless-ngx 在 Raspberry Pi 等低性能设备上怎么调整 Worker、OCR 与归档设置提速

【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx

在树莓派这类低性能硬件上运行 Paperless-ngx 时，OCR、自动匹配算法更新等任务会明显变慢，文档消费期间系统响应也会变得迟钝。本文基于项目文档中 “Running Paperless-ngx on less powerful devices” 一节的建议，给出一组可以落地的环境变量调整：压低后台 Worker/线程占用、限制 OCR 工作量、跳过 PDF/A 归档文件生成，并说明每处配置的写入位置和生效后的可核对现象。适用于 arm64 的 Raspberry Pi（文档中测试环境为 Raspberry Pi 3 B）以及其他核心数较少或单核性能较弱的设备。

适用前提

先确认你的部署方式，因为配置写入位置不同：

• Docker 部署：arm64 硬件有官方 Docker 镜像，可直接按 docs/setup.md 的 Docker Compose 流程安装，Docker 在树莓派上几乎无额外开销。此时paperless.conf不生效，所有配置项需要复制到docker-compose.env（可参考仓库中的 docker/compose/docker-compose.env 模板）。
• 裸机部署：Paperless 会按顺序查找PAPERLESS_CONFIGURATION_PATH、/path/to/paperless/paperless.conf、/etc/paperless.conf、/usr/local/etc/paperless.conf，把配置写入找到的第一个文件（参考 paperless.conf.example）。注意 docs/faq.md 说明：部分 Python 依赖没有 ARM/ARM64 预编译包，安装时需要额外的开发库且编译耗时很长。
• 32 位 ARMv7：文档提示 32 位系统可能仍可运行，但 Docker 部署可能需要修改 Dockerfile，裸机则需要额外工具，官方建议升级到 arm64。

数据库方面，docs/setup.md 明确建议低性能设备上继续使用 SQLite 以节省资源；如果后续遇到 SQLite 锁问题，文档指向 troubleshooting 的 "Creating PaperlessTask failed" 一节，可调整PAPERLESS_DB_TIMEOUT或改用 PostgreSQL。

调整 Worker 与线程数

Paperless 的后台任务（消费文档、维护索引、检查邮件等）由 Worker 并发执行。文档说明这些参数默认按“用满所有核心”的方式配置：Raspberry Pi 3 及以后的型号有 4 个核心，意味着默认约 2 个 Worker × 2 线程/Worker，消费期间可能导致响应迟钝。

对应两个变量（定义见 docs/configuration.md）：

• PAPERLESS_TASK_WORKERS：并行执行多少件后台任务。
• PAPERLESS_THREADS_PER_WORKER：单份文档 OCR 时并行处理多少页。

PAPERLESS_THREADS_PER_WORKER条目里有一个明确的约束警告：

Ensure that the productPAPERLESS_TASK_WORKERS * PAPERLESS_THREADS_PER_WORKERdoes not exceed your CPU core count or else paperless will be extremely slow.

即两者乘积不要超过 CPU 核心数。文档给出的低性能设备示例是2 个 Worker + 1 线程（2 × 1 = 2，小于 4 核），目的是“always have some computing power left for other tasks”。如果你的设备核心数不同，按这条乘积规则自行取值。不设置PAPERLESS_THREADS_PER_WORKER时，Paperless 使用max(floor(cpu_count / PAPERLESS_TASK_WORKERS), 1)，即把线程数摊满剩余核心。

Docker 部署下在docker-compose.env中写入：

PAPERLESS_TASK_WORKERS=2 PAPERLESS_THREADS_PER_WORKER=1

裸机部署则写入paperless.conf，写法相同。

降低 OCR 开销

OCR 是树莓派上最慢的环节，docs/faq.md 的回答直接指出 “certain parts of Paperless will run very slow, such as the OCR”（例如在树莓派 3 B 上）。围绕 OCR 的四个开关：

1.PAPERLESS_OCR_MODE保持默认auto。该模式会用 pdftotext 检测文档是否已有嵌入文本：文本足够时跳过 OCR（--skip-text），没有文本才运行 OCR。文档建议低性能设备保持此值，并考虑在文档进入 Paperless 之前就先完成 OCR——不少扫描仪本身就能输出带文本层的 PDF，这样 Paperless 可以直接复用已有文本。

2.PAPERLESS_OCR_PAGES=1，只 OCR 第一页。设置后只有第一页参与 OCR；页数不足指定值的文档会被完整 OCR。文档的原话是“在大多数情况下，第一页包含足够的信息来找到这份文档”。该值必须 ≥ 1，未设置时对所有页面 OCR。若与PAPERLESS_OCR_MODE=redo或force组合，被排除的页面上的已有文本会原样保留、不做修改。

3.PAPERLESS_OCR_CLEAN=none，跳过 unpaper 预处理。默认clean会先用 unpaper 清洗图像再交给 Tesseract，效果更好但消耗更多资源。文档明确给出低性能设备的取舍：“This will speed up OCR times and use less memory at the expense of slightly worse OCR results”——更快、更省内存，代价是 OCR 质量略差。

4. 大文档可能超时：PAPERLESS_WORKER_TIMEOUT。该变量条目写明：核心少或性能弱的机器可能无法在默认1800 秒内完成大文档的 OCR，适当延长超时有用。只有你确实遇到 OCR 超时报错时才需要动它，文档未给出建议数值，按文档时长自行放大。

组合写法（Docker 的docker-compose.env或裸机的paperless.conf）：

PAPERLESS_OCR_MODE=auto PAPERLESS_OCR_PAGES=1 PAPERLESS_OCR_CLEAN=none

另外，docs/configuration.md 开头说明部分 OCR 相关设置也可以在 UI 中设置，且 UI 值优先于环境变量，修改 UI 配置需要AppConfig权限（实例级、等同管理员权限）。如果你的实例已经有人在 UI 里设过 OCR 参数，注意环境变量可能被覆盖。

跳过归档文件生成

PAPERLESS_ARCHIVE_FILE_GENERATION控制是否生成 PDF/A 归档副本（归档文件与原文件并存，供 Web 界面展示）。低性能设备文档建议设为never：

SetPAPERLESS_ARCHIVE_FILE_GENERATIONtoneverto skip archive file generation entirely, saving disk space at the cost of in-browser PDF/A viewing.

即省磁盘空间、省生成耗时，代价是 Web 查看器直接显示原始文件而非 PDF/A 版本。默认auto会为扫描/图像类文档生成归档、跳过自带文本的 born-digital PDF；never下所有类型都不生成归档。注意文档中一条边界：DOCX/ODT 这类经 Tika 解析的文件无论如何都会生成 PDF 渲染用于展示，不受该设置影响。

PAPERLESS_ARCHIVE_FILE_GENERATION=never

其他可选的低功耗开关

以下三项文档同样列在低性能设备建议中，按你的使用方式选择性启用：

• PAPERLESS_CONSUMER_DISABLE：如果不用目录消费（docker 下的 filesystem consumer），设置该变量（任意值即可）可完全禁用它，省一份持续的资源占用。
• PAPERLESS_WEBSERVER_WORKERS=1（Docker 部署）：减少 Web 服务器进程数以省内存。该变量默认就是 1，如果你的 compose 文件里曾调大过，改回 1 即可；文档说明每个 Worker 进程都会把整个应用载入内存。
• PAPERLESS_ENABLE_NLTK=false：关闭自动分类中使用的高级自然语言处理，减少内存和处理时间；文档说明关闭后 Paperless 仍会做基础文本预处理再匹配。

自动匹配算法更新也值得处理：文档提示更新自动匹配算法“takes quite a bit of time”，但更新机制会先检查数据是否变化；如果算法占用 CPU 时间过长，可在管理界面把更新计划改为每天一次，也可以把“下次运行时间”改成当前时间手动触发任务。文档同时说明，算法的实际匹配过程本身很快，在树莓派上也没有问题。

核对配置是否生效

配置写入位置确认：Docker 只看docker-compose.env，裸机看paperless.conf（及上述三个查找路径）。改完后按 docs/setup.md 安装一节的说法，实例应可访问http://127.0.0.1:8000（或按你的端口配置），首次访问会提示创建账户——页面能正常打开并完成文档上传，说明 Worker 与 Web 服务都按新配置在跑。

判断调优是否针对了你原来的问题，文档给出的可核对现象是日志中的数据库锁报错。docs/troubleshooting.md 描述了这类日志：

[ERROR] [paperless.management.consumer] Creating PaperlessTask failed: db locked

文档的归因是：sqlite 安装 + Worker 数偏多，同时上传或消费多个文件时大量 Worker 并发访问数据库，撞上 sqlite 的并发限制。对应处理：经常批量处理文档就换 PostgreSQL；否则调整PAPERLESS_DB_TIMEOUT给数据库更多解锁时间，或让 SQLite 启用 Write-Ahead Logging（文档注明这些改动可能有轻微性能影响）。按本文建议把PAPERLESS_TASK_WORKERS压低后，这个报错的触发面也随之缩小。

限制与边界

• PAPERLESS_OCR_PAGES=1意味着后续页的文本不会被 OCR 提取，多页文档只有第一页可被全文搜索命中；如果依赖全文检索，这是有意识的取舍。
• PAPERLESS_ARCHIVE_FILE_GENERATION=never会让浏览器内直接查看原始文件，不再提供 PDF/A 归档视图。
• PAPERLESS_OCR_CLEAN=none的文档结论是 OCR 结果“slightly worse”，对扫描件质量要求高的场景不要套用。
• 本文所有调整针对的是 CPU 与内存占用；文档没有给出各参数的性能基准数据，不要期待某个固定提速数值。

进一步排查时，docs/troubleshooting.md 的其他条目（如消费卡死、日志轮转配置）和 docs/configuration.md 的完整变量表可以继续按需查阅。

【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx