尧图网站建设 
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.mdPAPERLESS_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_WORKERS2 PAPERLESS_THREADS_PER_WORKER1裸机部署则写入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_PAGES1只 OCR 第一页。设置后只有第一页参与 OCR页数不足指定值的文档会被完整 OCR。文档的原话是“在大多数情况下第一页包含足够的信息来找到这份文档”。该值必须 ≥ 1未设置时对所有页面 OCR。若与PAPERLESS_OCR_MODEredo或force组合被排除的页面上的已有文本会原样保留、不做修改。3.PAPERLESS_OCR_CLEANnone跳过 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.confPAPERLESS_OCR_MODEauto PAPERLESS_OCR_PAGES1 PAPERLESS_OCR_CLEANnone另外docs/configuration.md 开头说明部分 OCR 相关设置也可以在 UI 中设置且 UI 值优先于环境变量修改 UI 配置需要AppConfig权限实例级、等同管理员权限。如果你的实例已经有人在 UI 里设过 OCR 参数注意环境变量可能被覆盖。跳过归档文件生成PAPERLESS_ARCHIVE_FILE_GENERATION控制是否生成 PDF/A 归档副本归档文件与原文件并存供 Web 界面展示。低性能设备文档建议设为neverSetPAPERLESS_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 PDFnever下所有类型都不生成归档。注意文档中一条边界DOCX/ODT 这类经 Tika 解析的文件无论如何都会生成 PDF 渲染用于展示不受该设置影响。PAPERLESS_ARCHIVE_FILE_GENERATIONnever其他可选的低功耗开关以下三项文档同样列在低性能设备建议中按你的使用方式选择性启用PAPERLESS_CONSUMER_DISABLE如果不用目录消费docker 下的 filesystem consumer设置该变量任意值即可可完全禁用它省一份持续的资源占用。PAPERLESS_WEBSERVER_WORKERS1Docker 部署减少 Web 服务器进程数以省内存。该变量默认就是 1如果你的 compose 文件里曾调大过改回 1 即可文档说明每个 Worker 进程都会把整个应用载入内存。PAPERLESS_ENABLE_NLTKfalse关闭自动分类中使用的高级自然语言处理减少内存和处理时间文档说明关闭后 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_PAGES1意味着后续页的文本不会被 OCR 提取多页文档只有第一页可被全文搜索命中如果依赖全文检索这是有意识的取舍。PAPERLESS_ARCHIVE_FILE_GENERATIONnever会让浏览器内直接查看原始文件不再提供 PDF/A 归档视图。PAPERLESS_OCR_CLEANnone的文档结论是 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Paperless-ngx 在 Raspberry Pi 等低性能设备上怎么调整 Worker、OCR 与归档设置提速
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.mdPAPERLESS_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_WORKERS2 PAPERLESS_THREADS_PER_WORKER1裸机部署则写入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_PAGES1只 OCR 第一页。设置后只有第一页参与 OCR页数不足指定值的文档会被完整 OCR。文档的原话是“在大多数情况下第一页包含足够的信息来找到这份文档”。该值必须 ≥ 1未设置时对所有页面 OCR。若与PAPERLESS_OCR_MODEredo或force组合被排除的页面上的已有文本会原样保留、不做修改。3.PAPERLESS_OCR_CLEANnone跳过 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.confPAPERLESS_OCR_MODEauto PAPERLESS_OCR_PAGES1 PAPERLESS_OCR_CLEANnone另外docs/configuration.md 开头说明部分 OCR 相关设置也可以在 UI 中设置且 UI 值优先于环境变量修改 UI 配置需要AppConfig权限实例级、等同管理员权限。如果你的实例已经有人在 UI 里设过 OCR 参数注意环境变量可能被覆盖。跳过归档文件生成PAPERLESS_ARCHIVE_FILE_GENERATION控制是否生成 PDF/A 归档副本归档文件与原文件并存供 Web 界面展示。低性能设备文档建议设为neverSetPAPERLESS_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 PDFnever下所有类型都不生成归档。注意文档中一条边界DOCX/ODT 这类经 Tika 解析的文件无论如何都会生成 PDF 渲染用于展示不受该设置影响。PAPERLESS_ARCHIVE_FILE_GENERATIONnever其他可选的低功耗开关以下三项文档同样列在低性能设备建议中按你的使用方式选择性启用PAPERLESS_CONSUMER_DISABLE如果不用目录消费docker 下的 filesystem consumer设置该变量任意值即可可完全禁用它省一份持续的资源占用。PAPERLESS_WEBSERVER_WORKERS1Docker 部署减少 Web 服务器进程数以省内存。该变量默认就是 1如果你的 compose 文件里曾调大过改回 1 即可文档说明每个 Worker 进程都会把整个应用载入内存。PAPERLESS_ENABLE_NLTKfalse关闭自动分类中使用的高级自然语言处理减少内存和处理时间文档说明关闭后 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_PAGES1意味着后续页的文本不会被 OCR 提取多页文档只有第一页可被全文搜索命中如果依赖全文检索这是有意识的取舍。PAPERLESS_ARCHIVE_FILE_GENERATIONnever会让浏览器内直接查看原始文件不再提供 PDF/A 归档视图。PAPERLESS_OCR_CLEANnone的文档结论是 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考