Paperless-ngx 故障排查-未完纪

消费程序没有添加任何文件

请检查以下问题：

确认放入文档的目录就是 Paperless 正在监视的目录。使用 Docker 时，在 docker-compose.yml 中配置；不使用 Docker 时，查看 CONSUMPTION_DIR。如果使用 Docker，不要调整后者。
确认消息代理已经启动。Paperless 异步处理任务，文档要到达任务处理器，消息代理必须正常运行。
确认任务处理器已经运行。Docker 会自动完成这一步，也可以手动执行以下命令启动任务处理器。

celery --app paperless worker

查看 Paperless 的输出，检查是否存在错误。
进入管理界面，查看是否存在失败任务。失败的任务中会包含错误消息。

消费程序提示 OCR for XX failed

如果 OCR 识别准确率太低，或者消费程序报告 OCR for XX failed, but we're going to stick with what we've got since FORGIVING_OCR is enabled，可能需要安装与文档语言相匹配的 Tesseract 语言文件。

例如，在 Ubuntu 或 Debian 上运行 Paperless-ngx，而文档为西班牙语时，可能需要运行：

apt-get install -y tesseract-ocr-spa

消费程序不能发现后续新增的文件

如果消费程序只在启动时发现消费目录中的文件，却无法发现之后加入的文件，需要通过配置选项 PAPERLESS_CONSUMER_POLLING_INTERVAL 启用文件系统轮询。这会禁用自动监听文件系统变化，改为由 Paperless 主动检查消费目录的变化。

Paperless 总是重定向到 /admin

你可能曾经安装过旧版 Paperless。旧版在浏览器中设置了指向 /admin 的永久重定向，清除浏览数据或缓存即可解决。

Operation not permitted

可能出现以下错误：

chown: changing ownership of '../export': Operation not permitted

容器正在尝试设置列出目录的文件所有权，以确保 Docker 内运行 Paperless 的用户对这些目录有写入权限。例如，将这些目录指向 NFS 共享时，就可能发生这种问题。

请确保这些目录允许执行 chown。

分类器错误：No training data available

这表示自动匹配算法没有找到可供学习的文档，可能有两个原因：

没有使用自动匹配算法：这种情况下可以安全地忽略该错误。
正在使用自动匹配算法：分类器会明确排除带有“收件箱”标签的文档。检查归档中是否存在不带收件箱标签的文档；算法只会从收件箱之外的文档学习。

每个文档都会触发 sklearn 的 UserWarning

可能看到类似的警告：

/usr/local/lib/python3.7/site-packages/sklearn/base.py:315:
UserWarning: Trying to unpickle estimator CountVectorizer from version 0.23.2 when using version 0.24.0.
This might lead to breaking code or invalid results. Use at your own risk.

Paperless 中负责自动匹配算法的某些依赖更新后，就可能出现这种情况。更新后，当前训练数据可能不再兼容。多数情况下可以忽略；Paperless 更新训练数据后，警告会自动消失。

如果想消除警告，或者自动匹配确实发生问题，可以删除数据目录中的 classification_model.pickle，让 Paperless 重新创建它。

添加 Office 文档时出现 504 Server Error: Gateway Timeout

使用可选的 TIKA 集成时，可能出现以下错误：

requests.exceptions.HTTPError: 504 Server Error: Gateway Timeout for url: http://gotenberg:3000/forms/libreoffice/convert

Gotenberg 是将 Office 文档转换为 PDF 的服务器，默认超时为 30 秒。转换超过这个时间时，就会产生该错误。

可以通过配置 Gotenberg 的命令参数延长超时时间，相关说明见 Gotenberg 文档。使用 Docker Compose 时，在 docker-compose.yml 中作如下修改：

# The gotenberg chromium route is used to convert .eml files. We do not
# want to allow external content like tracking pixels or even javascript.
command:
  - 'gotenberg'
  - '--chromium-disable-javascript=true'
  - '--chromium-allow-list=file:///tmp/.*'
  - '--api-timeout=60s'

消费目录中出现 Permission denied

可能遇到以下错误：

The following error occurred while consuming document.pdf: [Errno 13] Permission denied: '/usr/src/paperless/src/../consume/document.pdf'

这是因为 Paperless 没有删除消费目录中文件的权限。如果宿主机所用用户和用户组的 ID 不是 1000，确保将 USERMAP_UID 和 USERMAP_GID 分别设置为对应的用户 ID 和组 ID。详见 Docker 配置。

同时确认，在宿主机上可以读写消费目录。

Web 界面一直停在 Loading…

这可能有多种原因：

如果自行构建了 Docker 镜像，或采用裸机部署，检查 <paperless-root>/static/frontend/<lang-code>/ 中是否存在文件。如果没有，确保已经成功执行 collectstatic，无论是手动执行，还是在 Docker 镜像构建过程中执行。
如果仍然缺少前端，确认前端已经编译，即 src/documents/static/frontend 中存在文件。否则需要自行编译前端，或者下载发行版压缩包，而不是克隆仓库。

读取元数据出错

日志中可能出现：

[WARNING] [paperless.parsing.tesseract] Error while reading metadata

这表示 Paperless 无法读取某份文档的 PDF 元数据。在 Paperless 中打开受影响文档进行编辑时，会发生这种情况。Paperless 仍会继续工作，只是不显示无效的元数据。

消费程序出现 FileNotFoundError

日志中可能出现以下消息：

[ERROR] [paperless.consumer] Error while consuming document SCN_0001.pdf: FileNotFoundError: [Errno 2] No such file or directory: '/tmp/ocrmypdf.io.yhk3zbv0/origin.pdf'
Traceback (most recent call last):
  File "/app/paperless/src/paperless_tesseract/parsers.py", line 261, in parse
    ocrmypdf.ocr(**args)
  File "/usr/local/lib/python3.8/dist-packages/ocrmypdf/api.py", line 337, in ocr
    return run_pipeline(options=options, plugin_manager=plugin_manager, api=True)
  File "/usr/local/lib/python3.8/dist-packages/ocrmypdf/_sync.py", line 385, in run_pipeline
    exec_concurrent(context, executor)
  File "/usr/local/lib/python3.8/dist-packages/ocrmypdf/_sync.py", line 302, in exec_concurrent
    pdf = post_process(pdf, context, executor)
  File "/usr/local/lib/python3.8/dist-packages/ocrmypdf/_sync.py", line 235, in post_process
    pdf_out = metadata_fixup(pdf_out, context)
  File "/usr/local/lib/python3.8/dist-packages/ocrmypdf/_pipeline.py", line 798, in metadata_fixup
    with pikepdf.open(context.origin) as original, pikepdf.open(working_file) as pdf:
  File "/usr/local/lib/python3.8/dist-packages/pikepdf/_methods.py", line 923, in open
    pdf = Pdf._open(
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/ocrmypdf.io.yhk3zbv0/origin.pdf'

这通常表示 Paperless 尝试消费同一个文件两次。原因取决于文档如何进入消费目录，例如扫描仪在扫描期间可能多次修改文件。

可以尝试增大文件稳定等待时间。

日志报告 Creating PaperlessTask failed

日志中可能出现：

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

你很可能在使用 SQLite，并增加了工作进程数量，从而遇到了 SQLite 的并发限制。一次上传或消费多个文件，会让许多工作进程同时尝试访问数据库。

如果经常同时处理大量文档，应考虑改用 PostgreSQL。否则，可以调整 PAPERLESS_DB_TIMEOUT，给数据库更多解除锁定的时间。还可以让 SQLite 数据库使用“预写式日志（Write-Ahead Logging）”。这些修改可能对性能有轻微影响，但有助于避免数据库锁定问题。

granian 启动失败并提示 is not a valid port number

这通常发生在 Kubernetes 环境中。Kubernetes 会自动创建名为 ${serviceName}_PORT 的环境变量，而 Paperless 恰好也使用同一个环境变量来覆盖 granian 的监听端口。

重新设置 PAPERLESS_PORT 为所需端口，或默认的 8000，即可解决。

数据库报告唯一约束 documents_tag_name_uniq

数据库日志中可能出现：

ERROR:  duplicate key value violates unique constraint "documents_tag_name_uniq"
DETAIL:  Key (name)=(NameF) already exists.
STATEMENT:  INSERT INTO "documents_tag" ("owner_id", "name", "match", "matching_algorithm", "is_insensitive", "color", "is_inbox_tag") VALUES (NULL, 'NameF', '', 1, true, '#a6cee3', false) RETURNING "documents_tag"."id"

使用轮询并高强度消费文档时，可能发生这种情况。Paperless 会正确处理，文件仍然会被消费。

消费失败并提示 Ghostscript PDF/A rendering failed

较新版本的 OCRmyPDF 遇到处理错误时会直接失败。这是有意设计的，因为输出的归档文件可能以意外或不希望发生的方式偏离原始文件。

如日志所提示，遇到此错误时，可以设置 PAPERLESS_OCR_USER_ARGS: '{"continue_on_soft_render_error": true}'，尝试“强制”处理有此问题的文档。

删除文档时日志提示 possible incompatible database column

删除文档时可能出现：

Data too long for column 'transaction_id' at row 1

如果使用 MariaDB／MySQL，并且安装是从使用 Django 4 的旧版 Paperless-ngx 升级而来，就可能出现该错误；对应的 Paperless-ngx 版本早于 v2.13.0。由于 Django 5 存在不向后兼容的变更，需要重新创建 documents_document.transaction_id 列。一次性运行以下管理命令即可：

$ python3 manage.py convert_mariadb_uuid

特定平台上的部署故障排查

用户维护的 Wiki 页面提供了在特定平台，例如 SELinux 上部署 Paperless-ngx 时可能遇到的问题及处理方法。请参阅 Wiki。

原文：Troubleshooting。作者／维护者：Paperless-ngx 项目贡献者。本文为原文的中文译文；代码保留原文内容。

文章版权归作者所有，未经允许请勿转载。

THE END

技术译文

Paperless-ngx 故障排查