Paperless-ng 常见问题排查指南

Paperless-ng 是一款优秀的文档管理系统，但在实际使用过程中可能会遇到各种问题。本文将从技术角度深入分析常见问题的成因和解决方案，帮助用户快速定位和解决问题。## 消费目录文件未被处理### 问题现象文件放入消费目录后未被 Paperless-ng 处理。### 排查步骤1. **检查消费目录配置**- Docker 部署：确认 `docker-compose....

申芹琴

518人浏览 · 2025-06-08 09:02:04

申芹琴 · 2025-06-08 09:02:04 发布

Paperless-ng 常见问题排查指南

【免费下载链接】paperless-ng A supercharged version of paperless: scan, index and archive all your physical documents 项目地址: https://gitcode.com/gh_mirrors/pa/paperless-ng

前言

Paperless-ng 是一款优秀的文档管理系统，但在实际使用过程中可能会遇到各种问题。本文将从技术角度深入分析常见问题的成因和解决方案，帮助用户快速定位和解决问题。

消费目录文件未被处理

问题现象

文件放入消费目录后未被 Paperless-ng 处理。

排查步骤

检查消费目录配置
- Docker 部署：确认 docker-compose.yml 中消费目录配置正确
- 非 Docker 部署：检查 CONSUMPTION_DIR 环境变量设置
检查 Redis 服务
- Paperless-ng 使用 Redis 进行异步任务处理
- 确保 Redis 服务正常运行
检查任务处理器
- Docker 部署会自动启动任务处理器
- 手动启动命令：python3 manage.py qcluster
检查错误日志
- 查看 Paperless-ng 输出日志
- 在管理界面检查是否有失败任务

消费服务无法检测新文件

问题现象

消费服务仅在启动时处理文件，后续新增文件不被识别。

解决方案

启用文件系统轮询机制：

设置 PAPERLESS_CONSUMER_POLLING 配置项
这会禁用 inotify 监听，改为定期扫描消费目录

自动重定向到 /admin 问题

问题现象

访问 Paperless-ng 总是跳转到 /admin 页面。

解决方案

清除浏览器缓存和历史记录，此问题通常由旧版 Paperless 的永久重定向导致。

文件权限问题

常见错误

Operation not permitted 或 Permission denied 错误。

解决方案

NFS 共享问题
- 确保容器可以对挂载目录执行 chown
- 检查 NFS 共享配置
用户映射问题
- 检查 USERMAP_UID 和 USERMAP_GID 设置
- 确保与主机系统用户/组 ID 匹配

自动分类器问题

错误信息

No training data available

原因分析

未使用自动匹配算法：可忽略此错误
使用自动匹配算法：
- 分类器会排除带有"收件箱"标签的文档
- 确保存在不带收件箱标签的文档供学习

依赖版本警告

警告示例

UserWarning: Trying to unpickle estimator...

解决方案

通常可忽略，训练数据更新后警告会消失
如需解决：
- 删除 data/classification_model.pickle 文件
- 让 Paperless-ng 重新生成训练数据

Office 文档转换超时

问题现象

504 Gateway Timeout 错误。

解决方案

增加 Gotenberg 超时时间：

gotenberg:
    environment:
        DEFAULT_WAIT_TIMEOUT: 30

搜索索引问题

错误信息

OSError: [Errno 19] No such device

原因

搜索索引使用内存映射文件，某些文件系统(特别是网络共享)不支持此功能。

解决方案

将数据目录存储在支持内存映射文件的本地文件系统上。

Web 界面卡在"Loading..."

可能原因及解决方案

静态文件缺失
- 检查 <paperless-root>/static/frontend/<lang-code>/ 目录
- 确保执行了 collectstatic 命令
- 前端未编译时需要手动编译或使用发布包
文件发送错误
- 日志中出现 OSError: [Errno 22] Invalid argument
- 解决方案：设置 SENDFILE=0