企业官网建设流程全解析

Paperless-ngx v3 怎么处理重复文档：查看 Duplicates 标签页或配置消费时拒绝重复

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

从 v3 开始，Paperless-ngx 的默认行为变了：消费一个与已有文档内容完全相同（checksum 一致）的文件时，系统不再拒绝，而是照常入库，并在日志中记录一条警告；对应的上传任务条目也会标记出检测到重复，并直接链接到已有的文档。这意味着同一个文件被多次放入消费目录后，数据库里会出现多份内容相同的文档。本文介绍两种处理方式：使用默认的"消费后审查"，通过文档详情页的Duplicates标签页找出并清理重复；或者把PAPERLESS_CONSUMER_DELETE_DUPLICATES设为true，恢复 v3 之前"消费时直接拒绝重复"的行为。

两种做法都适用于 Docker 或非 Docker 安装，区别只在于环境变量写在哪里，下面会分别说明。

v3 的默认行为：重复文档照常入库

先明确 v3 的判断依据和默认结果，这决定了后续该用哪种处理方式：

• 判断标准是文件内容的checksum是否与已有文档完全相同，而不是文件名或扩展名；
• 默认（PAPERLESS_CONSUMER_DELETE_DUPLICATES为false）下，重复文件仍然会被消费，日志中会有一条警告，任务条目中会标记出重复并链接到已有文档；
• 该行为在 v3 中是有意变更的，v2 默认是拒绝重复，升级指南在 docs/migration-v3.md 的 "Duplicate Handling Changes" 一节有说明。

如果你的工作流允许"先收进来、事后清理"，用下面的默认路径即可。

方式一：通过 Duplicates 标签页审查并清理重复（默认路径）

这是 v3 默认推荐的做法，不需要改任何配置。操作步骤：

1. 正常消费文档（Web UI 上传、消费目录、邮件规则等任意入口均可）。
2. 消费后如果日志里出现重复警告，或上传任务条目提示检测到重复，任务条目中会直接链接到内容相同的已有文档，可以点开确认。
3. 打开任意一份相关文档的详情页，切换到Duplicates标签页。
4. 该标签页会列出所有与该文档共享相同内容的其他文档，包括已移入回收站的那份（用 badge 标出），每一项都可以点击跳转。
5. 根据列表决定保留哪份，把多余的文档删掉即可。

这个路径的验证方式很直接：Duplicates 标签页列出的就是与当前文档内容完全相同的文档集合，清理后列表收敛到只剩你想保留的那份（回收站中的副本会带 badge 显示）。

局限在于：默认路径下重复文档已经入库，占用了数据库和存储，需要人工逐份确认清理；如果你希望重复文件根本进不了系统，用方式二。

方式二：配置消费时拒绝重复（PAPERLESS_CONSUMER_DELETE_DUPLICATES）

如果你想要 v3 之前的行为——重复文件不入库、在消费环节就被拦下——把PAPERLESS_CONSUMER_DELETE_DUPLICATES设为true。该配置项的官方说明（见 docs/configuration.md）是：

自 version 3.0 起，Paperless-ngx 默认允许消费重复文档，_除非_启用此设置。启用后，Paperless 会检查系统中是否已存在相同 hash 的文档，若存在，则把重复文件从消费目录中删除而不消费它。

默认值为false。

在哪里配置

取决于你的运行方式（见 docs/configuration.md 开头）：

• Docker 部署：paperless.conf不生效。把变量加到docker-compose.env中（项目提供的示例文件在 docker/compose/docker-compose.env）：

PAPERLESS_CONSUMER_DELETE_DUPLICATES=true

• 非 Docker 部署：写入 paperless 配置文件。系统按以下顺序查找并使用第一个找到的文件：

  1. 环境变量PAPERLESS_CONFIGURATION_PATH指定的路径；
  2. /path/to/paperless/paperless.conf；
  3. /etc/paperless.conf；
  4. /usr/local/etc/paperless.conf。

  在文件中加入同一行PAPERLESS_CONSUMER_DELETE_DUPLICATES=true即可。

修改环境变量后需要重启容器/服务让消费进程读到新值。

如何验证生效

启用后的行为变化是：重复文件被消费前检查 hash，若与已有文档相同，该文件会从消费目录中被删除、不会入库，对应的任务失败，失败信息为 "document already exists"。所以验证方式是：

1. 消费一份文档，确认它正常入库；
2. 把同一文件（内容逐字节相同）再次放入消费目录；
3. 消费目录中该文件消失，且任务列表中出现一条失败任务，信息为 "document already exists"——这就是配置生效的预期现象。注意这是"任务失败"而非"消费成功但被跳过"，属于该配置的既定行为。

两种方式的边界与注意事项

• 两种机制都只针对checksum 完全相同的文件。同一份文档的新版本（内容有改动）不会被识别为重复，两者都会正常入库。
• 方式二下重复文件是"删除"操作：文件从消费目录移走且不可从 Paperless 恢复，配置前确认你的来源流程允许文件被删。
• v3 升级时任务历史会被清空（见 docs/migration-v3.md 的 "Task History Cleared on Upgrade"），升级前产生的旧任务条目不会再出现，任务面板里的重复标记只反映升级后的新任务。
• 关于"重复文档是否会被拒绝"的问答在 docs/faq.md 中也有相同结论，默认不拒绝、可用上述配置恢复拒绝行为。

按此选择：能接受事后的，用 Duplicates 标签页逐份审查清理；不能让重复进入系统的，在消费配置中启用PAPERLESS_CONSUMER_DELETE_DUPLICATES=true，并以"重复文件消失 + 任务报 document already exists"作为配置生效的判断依据。

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