Paperless-ngx 常见问题深度解析：Docker 卷、文件类型、去重机制与消息代理

本文基于 Paperless-ngx 官方 FAQ（docs/faq.md）展开，覆盖文档存储位置、可迁移性、支持的文件类型、重复文档处理、树莓派部署、AI 数据隐私与消息代理选择等高频问题。每个问题都结合仓库源码与配置文件给出实现层面的佐证，读完你可以完全理解这些行为背后的机制，并能据此调整自己的部署。

项目总体开发规划

FAQ 开篇即说明：Paperless-ngx 已被视为基本“功能完备”（feature-complete），是一个社区驱动的项目，开发方向由社区共同决定。新功能可以通过 GitHub Discussions 提交并由社区投票，但这并不保证一定实现；项目始终以 PR、想法等形式向协作开放。

这意味着当你在使用中遇到能力边界时，合理的预期是：核心流程（扫描、索引、归档、检索、工作流）已经稳定，长期投入更多集中在社区共建的功能增强上，而非颠覆性重构。

Docker 部署：文档究竟存在哪里？

FAQ 中最常见的困惑是：使用 Docker 时，文档文件到底在哪？

答案是：默认情况下，你的文档存储在 Docker 卷 paperless_media 中。这个卷由 Docker 自动管理，是持久化存储——只要你不显式删除它，数据就会一直保留。具体物理位置取决于宿主机操作系统；在 Linux 上，它很可能位于：

/var/lib/docker/volumes/paperless_media/_data

两条来自 FAQ 的重要提醒：

1. 不要手动操作这个目录：不要改动权限，不要手动移动文件。这个目录完全由 Docker 和 Paperless-ngx 共同管理。
2. 消费目录的文件会被搬走：从 consumption 目录消费的文件，会在 media 目录中被重新创建（原件归入 originals、归档件归入 archive），并从消费目录本身删除。所以消费完成后在消费目录里“找不到原文件”是正常行为，而非文件丢失。

各 compose 文件中可以看到 media 卷的实际挂载方式，例如 docker/compose/docker-compose.postgres.yml 中同时定义了应用数据卷与 broker 数据卷（redisdata:/data），体现了“数据与镜像分离、随卷持久化”的统一思路。

换系统能带走数据吗？——可迁移性

FAQ 明确回答：可以。文档以纯文件形式存放在 media 目录里，随时可以把文件拖出来用于其他系统。FAQ 给出三点补充，均能在源码中得到印证：

• 原件永不修改：Paperless-ngx 从不改动你的原始文档，它为每份文档保留校验和（checksum），并有一个定时运行的 sanity checker 检查文件是否与校验和一致。其实现位于 src/documents/sanity_checker.py：验证每份文档的文件是否有效、校验和是否正确、元数据是否一致，并报告 media 目录中的孤儿文件（orphaned files）；定时检查的管理命令入口在 src/documents/management/commands/document_sanity_checker.py。
• 默认文件名是内部 ID：默认情况下，Paperless-ngx 用每份文档的内部 ID 作为文件名，这对导出并不友好。可以通过 配置文件名格式（即 PAPERLESS_FILENAME_FORMAT，使用 Jinja 模板语法，如 {{ created_year }}/{{ correspondent }}/{{ title }}）自定义存储路径结构，参见 docs/advanced_usage.md。
• 导出器：exporter（管理命令 document_exporter，源码见 src/documents/management/commands/document_exporter.py）是另一种把文件以合理文件名带出 Paperless-ngx 的便捷方式。

支持哪些文件类型？

FAQ 给出当前的支持范围：

• PDF 文档、PNG、JPEG、TIFF、GIF、WebP 图片：经过 OCR 处理后转换为 PDF 文档；
• 纯文本文档：同样受支持，原文内容直接入库；
• Office 文档（.docx、.doc、odt、.ppt、.pptx、.odp、.xls、.xlsx、.ods）：需要启用可选的 Tika 集成，参见 Tika 配置。

两个关键行为细节：

1. 基于内容而非扩展名识别类型：Paperless-ngx 通过检查文件内容（而非扩展名）来判断文件类型。各解析器实现位于 src/paperless/parsers/，包括 tesseract.py（图片 OCR）、tika.py（Office 文档）等，注册机制见 src/paperless/parsers/registry.py。
2. 消费目录有扩展名白名单：凡通过消费目录进入的文件，如果其扩展名不被任何可用解析器支持，就会被拒绝。这解释了“明明内容是图片，为什么改名成 .bin 后就不消费了”。

图片转 PDF 的实际转换逻辑在 src/documents/converters.py：TIFF 等图片先处理透明通道，再经 img2pdf 生成同名 PDF，并复制原文件的时间戳等 stat 信息。

重复文档会被拒绝吗？

FAQ 的答案是：默认不再拒绝。自 v3 起，内容与现有文档相同的文件仍会被消费，重复项会在 UI 中标记——打开文档后查看 Duplicates 选项卡即可审查共享相同内容的文档。如果你希望恢复“消费时拒绝重复”的旧行为，把 PAPERLESS_CONSUMER_DELETE_DUPLICATES 设为 true 即可。

源码层面，这一行为由消费器 src/documents/consumer.py 中的 pre_check_duplicate 方法实现，逻辑值得细看：

• 用 compute_checksum 计算输入文件的 SHA256，然后在 Document 表中按 checksum（原件）或 archive_checksum（归档件）匹配，两个字段任一命中即视为重复；
• 若存在匹配且配置了 CONSUMER_DELETE_DUPLICATES，会删除输入文件并抛出 ConsumeFileDuplicateError，消费状态标记为失败；
• 一个细节是回收站感知：如果命中的现有文档已在回收站（deleted_at 非空），会改用 DOCUMENT_ALREADY_EXISTS_IN_TRASH 状态并在日志中提示，避免误删你本意是“恢复”的文档；
• 对应的配置解析在 src/paperless/settings/init.py：CONSUMER_DELETE_DUPLICATES = get_bool_from_env("PAPERLESS_CONSUMER_DELETE_DUPLICATES")。

UI 侧的 Duplicates 选项卡数据来自 src/documents/serialisers.py 中的 _get_viewable_duplicates：按相同内容过滤文档、排除版本链（root_document__isnull=True）、按创建时间倒序，并只返回当前用户有权查看的文档（只暴露 id、title、deleted_at 字段）。该行为有专门的权限测试 src/documents/tests/test_permission_filtering_security.py，消费行为则由 src/documents/tests/test_consumer.py 中 override_settings(CONSUMER_DELETE_DUPLICATES=True/False) 的两组用例分别验证开关两种取值。

能在树莓派上运行吗？

FAQ 的回答是肯定的，作者在 Raspberry Pi 3 B 上测试通过。长答案是：部分功能会非常慢，尤其是 OCR。建议在喂给 Paperless-ngx 之前先在树莓派上完成 OCR，这样 Paperless-ngx 可以复用已有文本（直接解析 PDF 内的文本层，无需再跑 Tesseract）。Web 界面本身会更流畅，因为它跑在浏览器里，服务端要做的只是提供数据。

相关部署要点：

• Docker 镜像提供 arm64 版本：按照 Docker Compose 安装说明 操作即可。Docker 的额外开销几乎为零，只是比裸机安装多占一些磁盘空间。
• 裸机安装的坑：部分 Python 依赖没有 ARM/ARM64 预编译包，需要额外安装开发库并现场编译，耗时很长。
• ARMv7（32 位）系统：可能仍可运行，但 Docker 方案可能需要修改 Dockerfile，裸机方案需要额外工具；FAQ 建议直接升级到 arm64。
• 低性能设备调优：可以调整部分设置让 Paperless-ngx 占用更少算力，参见 setup 文档的“较弱的设备”一节。

Unraid 与其他设备

• Unraid：Paperless-ngx 以 community app 的形式提供（由社区成员 Uli Fahrer 制作容器模板），从 Unraid 社区应用目录安装即可。
• 其他设备（FAQ 以“烤面包机”幽默地代指一切非标准硬件）：官方无法逐一支持。如果跑不了 Docker 镜像，docs/setup.md 提供了裸机安装的完整说明，可以自行研究适配。

Paperless-ngx 使用 AI 吗？数据私有吗？

FAQ 对 AI 与隐私的说明可以归纳为三句话，且与源码结构一致：

1. 可选的 AI 功能默认关闭。基于 LLM 的建议、文档聊天、相似文档检索等功能，只有在你显式启用并配置了 LLM 后端之后才会运行。
2. 内置的分类建议不依赖 LLM。标签/来信人建议使用的是本地、非 LLM 的机器学习模型，不会把你的数据发送到任何地方。
3. 启用 LLM 功能后，文档内容会发往你配置的后端——这可以是完全本地的后端（例如 Ollama），也可以是远程服务商，隐私边界完全由你决定。

实现上，AI 能力集中在独立的 src/paperless_ai/ 应用（含 ai_classifier.py、chat.py、vector_store.py 等），LLM 相关配置项（启用开关、后端选择、超时等）定义在 src/paperless/migrations/0005_applicationconfiguration_ai_enabled_and_more.py 对应的 ApplicationConfiguration 模型中，完整的启用步骤见 AI features。

该用哪个消息代理（Message Broker）？

Paperless-ngx 与一个 Redis 兼容的消息代理通信，因此任何实现 Redis 协议的代理都能工作。仓库内置的 Docker Compose 文件默认使用 Valkey（Redis 许可变更后诞生的开源分支）——例如 docker/compose/docker-compose.postgres.yml 中的 broker 服务镜像为 docker.io/valkey/valkey:9-alpine，应用侧通过环境变量 PAPERLESS_REDIS: redis://broker:6379 连接。Redis 本身以及其他线路兼容的代理（如 Microsoft 的 Garnet）同样可以使用。

FAQ 还特别指出存量安装可以原地切换代理实现：把 PAPERLESS_REDIS 指向新实例、沿用同一个数据卷即可，无需重新初始化。

小结

问题	结论	关键依据
Docker 文档位置	paperless_media 卷，Linux 常见路径 /var/lib/docker/volumes/paperless_media/_data	docs/faq.md
数据可迁移性	纯文件存储，原件不改、有校验和与定时 sanity check	src/documents/sanity_checker.py
文件类型	PDF/图片 OCR 转 PDF，文本直接入库，Office 需 Tika	src/paperless/parsers/
重复文档	v3 起默认消费并标记，可用 PAPERLESS_CONSUMER_DELETE_DUPLICATES 恢复拒绝行为	src/documents/consumer.py
树莓派	支持，arm64 镜像推荐，低性能场景先离线 OCR	docs/setup.md
AI 隐私	LLM 功能默认关闭；分类建议为本地模型；LLM 内容去向由你配置的后端决定	src/paperless_ai/
消息代理	任意 Redis 协议兼容实现；Compose 默认 Valkey；可原地切换	docker/compose/docker-compose.postgres.yml

FAQ 的价值在于把“文件在哪、能不能带走、支持什么格式、隐私边界在哪”这些运维与合规层面的核心问题一次讲清；结合上文给出的源码路径，你可以进一步验证每一个行为的真实实现，而不是止步于文档描述。