企业官网建设流程全解析

• 后端
• 前端
• 企业应用

导读

Paperless-ng 是一个将纸质文档数字化的个人文档管理系统：借助文档扫描仪，它把成堆的纸质档案转变为可搜索的电子归档，并提供分类、自动匹配、全文检索等一系列实用工具。本文以官方使用概览文档（docs/usage_overview.rst）为主体，结合仓库源码（consumer、matching、index、mail 等模块）深入讲解核心术语、五种文档入库方式、OCR 配置、组织与搜索实践，以及官方推荐的全流程工作法——读完即可上手搭建一套"扫描即归档、搜索即所得"的个人文档库。

一、核心概念与术语

Paperless 本质上由两个相互配合的部分组成：

• consumer（消费器）：持续监视指定文件夹，把放入其中的所有文档"消费"进系统——执行 OCR、建立索引并存储到媒体目录。核心实现见 src/documents/consumer.py。
• web server（Web 服务器）：提供一个 UI，供你搜索、查看与管理已扫描文档。

每一份文档都有一组可赋值的字段（对应模型定义见 src/documents/models.py）：

需要说明的是，在仓库当前版本中，"Frontend overview" 一节仍标注为TBD（待补充截图），故本文不展开前端界面细节，而聚焦于可验证的功能流程与配置。

二、把文档送进 Paperless

2.1 入库时的三步处理流程

一旦 Paperless 开始消费文档，会对文档依次执行以下操作：

1. OCR 识别：如果文档没有文本层，则执行 OCR；数字文档通常自带文本，此步会被跳过。
2. 生成 PDF/A 归档副本：Paperless 会从你的文档生成可归档的 PDF/A 文件。若文档来自扫描仪，将嵌入可选中的文本。
3. 自动匹配：在存入数据库之前，Paperless 会对文档执行标签、通信方和文档类型的自动匹配。

从源码看，消费流程由 src/documents/consumer.py 的try_consume_file完成：先做前置检查（文件存在、目录创建、MD5 去重），再按 MIME 类型选取解析器解析文档、生成缩略图、提取文本与日期，接着通过load_classifier()加载分类模型做自动匹配，最后在事务中落库并复制原文件、归档文件与缩略图。

关于归档副本的配置：如果你不希望为数字文档生成归档版本，可通过环境变量配置PAPERLESS_OCR_MODE=skip_noarchive实现。完整的 OCR 配置说明见 docs/configuration.rst。

重要提示：无论你选择何种选项，Paperless 都会始终保存在消费目录或邮件中找到的原始文档，且绝不会覆盖它。归档版本与原版并排存储。

2.2 OCR 模式详解

Paperless 使用OCRmyPDF执行 OCR（见 docs/configuration.rst），并读取环境变量（见 src/paperless/settings.py）。PAPERLESS_OCR_MODE有四种取值：

与 OCR 相关的常用配置还包括：

• PAPERLESS_OCR_LANGUAGE：OCR 语言，取 ISO 639 三位语言代码，默认eng；可组合多语言如deu+eng（注意多语言会显著增加 CPU 耗时；语言名含连字符如chi-sim时须写成chi_sim）。
• PAPERLESS_OCR_CLEAN：是否用unpaper预处理，取值clean（默认）、clean-final、none；clean-final与redo模式不兼容。
• PAPERLESS_OCR_DESKEW：纠正倾斜，默认true；与redo模式不兼容（自动禁用）。
• PAPERLESS_OCR_ROTATE_PAGES/PAPERLESS_OCR_ROTATE_PAGES_THRESHOLD：自动纠正 90°/180°/270° 页面旋转，阈值默认12（15保守、2激进）。
• PAPERLESS_OCR_OUTPUT_TYPE：输出 PDF 类型，默认pdfa，可选pdf、pdfa-1/pdfa-2/pdfa-3。
• PAPERLESS_OCR_PAGES：仅对前 N 页 OCR，默认0（全部页面）。
• PAPERLESS_OCR_IMAGE_DPI：扫描仪输出图片时用于换算 DPI，默认自动按 A4 估算。
• PAPERLESS_OCR_USER_ARGS：以 JSON 字典形式向 OCRmyPDF API 传递额外参数（参数名用下划线而非连字符）。注意：不兼容的参数组合可能导致消费失败，请谨慎使用。

2.3 消费目录（Consumption Directory）

把文档放进数据库的主要方式，是将其放入消费目录。consumer 在一个无限循环中监视该目录的新增文件，一旦发现便执行 OCR 解析、索引，并存入媒体目录。消费目录位置由PAPERLESS_CONSUMPTION_DIR配置（默认consume/，见 src/paperless/settings.py），相关轮询与容错参数包括PAPERLESS_CONSUMER_POLLING、PAPERLESS_CONSUMER_POLLING_DELAY、PAPERLESS_CONSUMER_POLLING_RETRY_COUNT、PAPERLESS_CONSUMER_DELETE_DUPLICATES、PAPERLESS_CONSUMER_RECURSIVE、PAPERLESS_CONSUMER_IGNORE_PATTERNS（默认忽略.DS_STORE/*、._*、.stfolder/*）与PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS（见 src/paperless/settings.py）。

如何把文件送进该目录由你决定：

• 在本机运行 Paperless，直接拖放文件即可；
• 在服务器上运行、希望扫描仪自动推送文件，则需要搭建某种接收服务，典型方案是 FTP 服务器（如 Proftpd）或 Windows 文件夹共享（Samba）。

完整的扫描仪选型建议（支持 FTP/NFS/SMB/SMTP/API 的各品牌型号）参见 docs/scanners.rst。

2.4 仪表盘上传（Dashboard Upload）

仪表盘（dashboard）提供文件拖放上传区：直接把文件拖入该区域，或通过文件对话框选择文件即可。支持一次选择多个文件。

2.5 移动端上传（Mobile Upload）

• Android 用户可通过paperless_share这类兼容应用，把任意文档"分享"给 Paperless；该方式可与 Office Lens 等手机扫描 App 组合使用。
• 另有Paperless App，除上传外还支持文档浏览与下载功能。
• 手机扫描时建议使用专门扫描 App（普通相机拍照可能对比度不足，影响 OCR 效果），具体机型与软件对比见 docs/scanners.rst。

2.6 IMAP 邮件消费（Email）

如果你经常收到需要归档的邮件文档，可以让 Paperless 直接从邮箱消费附件——这是一个非常灵活强大的功能。配置在**管理后台（admin interface）**中分两步完成：

1. 定义邮箱账户（e-mail accounts）：包括 IMAP 服务器、端口、加密方式（无加密/SSL/STARTTLS）、用户名密码与字符集。模型定义见 src/paperless_mail/models.py。
2. 为账户定义邮件规则（mail rules）：指定文件夹、最大邮件年龄、发件人/主题/正文/附件名过滤器，并可设定消费后动作以及标题、通信方、标签、文档类型的分配方式。模型定义见 src/paperless_mail/models.py。

规则执行流程（见 src/paperless_mail/mail.py）：

1. 连接到邮件服务器；
2. 按规则定义的文件夹、最大年龄和过滤器抓取所有匹配邮件；
3. 检查是否存在可消费的附件（默认仅处理attachment类型的附件，也可选择包含内联附件，此时建议配合文件名过滤器）；
4. 若有，则指示 Paperless 消费附件，并可应用规则中提供的元数据（标题来源：邮件主题或附件文件名；通信方来源：邮件地址、发件人姓名或指定通信方）；
5. 若邮件中消费了文档，则在邮件上执行规则动作。

Paperless 会完全忽略不匹配过滤器的邮件，也只会对已消费文档的邮件执行动作。所有动作都通过不同机制保证同一封邮件不会被重复消费：

• Delete（删除）：立即删除已消费文档的邮件。请谨慎使用。
• Mark as read（标记已读）：把已消费的邮件标记为已读。Paperless 不会消费已读邮件——如果你在 Paperless 看到之前读了邮件，它将被忽略。
• Flag（标记）：给已消费文档的邮件设置"重要"标记。Paperless 不会消费已标记邮件。
• Move to folder（移动到文件夹）：把已消费邮件移出原位，避免再次消费。

谨慎：邮件消费器会对所有已消费文档的邮件执行这些动作。请留意：实际消费过程可能因某些原因失败，导致 paperless 中缺少文档（但邮件动作已经执行）。

提示：配合正确的规则集，你可以完全自动化处理邮件文档——为每个常收到数字文档的通信方建一条规则即可。默认动作"标记已读"非常温和，不会造成任何破坏或数据丢失。

提示：你也可以在邮箱中为 Paperless 建立专用文件夹，用常用邮件客户端把待消费邮件手动或自动移入，再让 Paperless 消费后移到另一个文件夹。

提示：Paperless 按管理后台中定义的顺序处理规则。你可以定义兜底规则并让其最后执行，例如给未匹配的文档打上"Unknown mail document"标签以便进一步检查。

Paperless 默认每 10 分钟检查一次邮件，此间隔可在管理后台的"Scheduled tasks"页面修改。对应定时任务实现见 src/paperless_mail/tasks.py（process_mail_accounts遍历所有账户并汇总新增文档数）。

2.7 通过 REST API 上传

你还可以使用 REST API 提交文档，上传端点为/api/documents/post_document/。以 multipart 表单 POST，其中表单字段document包含要上传的文档；文件名会被清理后存入临时目录，并指示 consumer 从该处消费（实现见 src/documents/views.py）。该端点支持的可选表单字段：

• title：指定消费器使用的标题；
• correspondent：指定通信方 ID；
• document_type：同 correspondent 用法；
• tags：指定标签 ID，可多次指定以添加多个标签。

若消费进程成功启动，端点会立即返回"OK"；由于消费在独立进程中执行，此端点不提供消费过程的额外状态信息。API 的完整端点清单（/api/documents/、/api/correspondents/、/api/document_types/、/api/logs/、/api/tags/）、下载/预览/缩略图/元数据接口及三种认证方式，参见 docs/api.rst。

三、最佳实践：组织你的文档库

Paperless 提供了一批帮助你整理文档集的工具，但如何用好它们取决于你自己。以下思路来自官方文档，可直接套用：

• 文档类型（document type）：按"是什么"分类，例如"Receipt""Invoice""Contract"。如果你以前把收据统一放进一个文件夹，现在可以在 paperless 中定义对应文档类型、把文档赋给它，再按类型过滤，只看全部收据。不必强求每份文档都有类型——偶尔才用一次的类型难以界定也无妨，只要定义的类型确实有助于组织即可。
• 标签（tag）：把标签想成更灵活的文件夹或活页夹。大学相关、汽车、医疗等主题都可建为标签并赋给相关文档，随后按标签过滤查看。与实体文件夹最大的区别在于：一份文档可同时拥有多个标签，而实体文件不可能同时出现在两个文件夹中。
  • 应用示例：某个任务（如办理大学入学手续）需要从各处汇集一批文档，你可以新建一个标签把它们临时归组，既不打乱原有组织结构，任务结束后删掉标签即可"归还原位"。
• 通信方（correspondent）：上述逻辑同样适用。只要觉得有助于组织，就把通信方附到文档上。
• 保存视图（saved views）：整理好文档后，为常访问的集合创建若干保存视图。这相当于桌面上贴了标签的实体活页夹——区别是保存视图是动态的，随你不断加入文档而自动更新。

官方建议可在文档库中使用的标签示例：

• inbox：给尚未人工编辑的新入库文档。
• car：所有与车相关的内容（维修、注册、保险等）。
• todo：仍需处理（回复、在线办理等）的文档。
• bank account x：某账户相关的所有银行对账单。
• mail：任何通过邮件处理能力加入的文档。
• missing_metadata：需要补元数据但暂时没空/不想处理的文档。

值得补充的是：在模型层面，Tag还拥有is_inbox_tag字段（见 src/documents/models.py），被标记为 inbox 的标签会自动赋予所有新消费的文档；StatisticsView也据此统计待处理文档数（见 src/documents/views.py）。

四、搜索

Paperless 提供强大的搜索机制，让你能快速定位想找的文档——比如几个月前买的东西、八年前签的合同。

搜索时，Paperless 会匹配查询词与文档的content、title、correspondent、type 和 tags，并返回按得分排序的结果列表：匹配度越高的文档排在越前面。默认情况下，Paperless 只返回包含搜索栏中全部单词的文档。如需进一步收窄结果，可使用以下高级语法（全部可自由组合）：

匹配逻辑表达式：

shopname AND (product1 OR product2)

匹配特定标签、通信方或类型：

type:invoice tag:unpaid correspondent:university certificate

匹配日期：

created:[2005 to 2009] added:yesterday modified:today

模糊词匹配：

produ*name

提示：模糊词对搜索索引而言较难处理，这类查询可能耗时较长，这也是 Paperless 提供自动补全（autocomplete）与查询纠错（query correction）的原因。

Paperless 使用Whoosh 的默认查询语言实现上述语法。从源码看，全文搜索通过 src/documents/index.py 的DelayedFullTextQuery执行：它用MultifieldParser在content/title/correspondent/tag/type多字段上解析查询，并挂载DateParserPlugin支持日期语法，同时用correct_query提供查询纠错；自动补全由 src/documents/index.py 的autocomplete基于索引中高频词条（Tf/Idf 打分）实现。搜索索引的字段模式（Schema）见 src/documents/index.py，包含内容、标题、ASN、通信方、标签、类型及 created/modified/added 三个日期字段。API 侧的全文搜索查询参数与__search_hit__结果结构（score/highlights/rank）见 docs/api.rst。

五、推荐工作流（The Recommended Workflow）

当你熟悉 Paperless 并准备把所有文档纳入管理后，官方推荐如下工作流。它同时兼顾"部分文档必须保留纸质原件"的现实，同时确保这些文档也能享受数字化的一切便利。

5.1 工作流总览

Paperless 推荐工作流图

5.2 在 Paperless 中的前期准备

• 创建一个inbox 标签，让所有新文档自动带上它；
• 创建一个TODO 标签。

5.3 纸质文档的处理

在办公桌上放一个物理收件箱（physical inbox）：每当收到需要归档的文档就放入其中。定期对收件箱中的文档执行以下操作：

1. 逐份判断是否必须保留纸质原件——这适用于合同、证书等重要文件；
2. 如需保留，在扫描前手写一个递增流水号（从 1 开始递增），这就是档案编号ASN；
3. 扫描文档；
4. 有 ASN 的文档，放入唯一一本按 ASN 排序的活页夹中，不要用其他任何方式排序；
5. 没有 ASN 的文档，直接丢掉。恭喜，你成功瘦身了！

随着时间推移，实体活页夹会装满：满后，在夹脊标注 ASN 区间（例如"Documents 1 to 343"），存入地下室或别处，再启用新活页夹。

这套流程的核心思想是：你永远不必在实体活页夹里翻找文档。需要某份纸质原件时：

1. 在 Paperless 中搜索该文档；
2. 从扫描件上找到它的 ASN；
3. 按 ASN 直接取出对应活页夹中的原件——因为它们按编号排序，取用非常容易。

5.4 在 Paperless 中处理文档

扫描入库后，在系统中按下述步骤整理：

1. 若文档有 ASN，为该文档赋 ASN；
2. 为文档指定通信方（雇主、银行等）——非必须，但有助于日后查找；
3. 为文档指定文档类型（发票、银行对账单等）——非必须，但同样有助于查找；
4. 为文档指定合适的标题（所购物品名称、信件主题等）；
5. 核对日期是否正确——Paperless 会尝试从文档内容读取日期，但 OCR 不佳或文档上出现多个日期时可能出错；
6. 从文档上移除 inbox 标签。

提示：你可以为通信方和标签设置手工匹配规则（如 "Any"/"All"/"Literal"/"Regular expression"/"Fuzzy match" 等算法），Paperless 会自动赋值；消费若干文档后，你甚至可以让 Paperless 通过Auto算法（基于神经网络的自动匹配）自己学习何时赋标签与通信方。各匹配算法的具体行为与实现见 docs/advanced_usage.rst 与 src/documents/matching.py。

5.5 任务管理（Task Management）

部分文档需要你进一步采取行动。根据你使用 Paperless 的频率，有两种不同的处理方式：

• 如果你定期扫描并处理文档：给所有待办文档打上TODO 标签，并在仪表盘创建一个显示该标签下所有文档的保存视图，随时跟进；
• 如果你不经常扫描、只把 Paperless 当作归档工具：在物理收件箱旁放一个实体 TODO 盒子，把待办文档放进去；完成相关任务后，再把文档移回收件箱。

结语

从概念术语、五种入库渠道（消费目录、仪表盘上传、移动端、IMAP 邮件、REST API）、OCR 模式配置，到标签/类型/通信方的组织策略、Whoosh 高级搜索语法，再到"ASN 编号 + 物理活页夹 + inbox/todo 标签"的推荐工作流，本文完整覆盖了 Paperless-ng 日常使用的核心路径。相关实现细节与配置均可继续在仓库中深入研读：src/documents/consumer.py、src/documents/matching.py、src/documents/index.py、src/paperless_mail/mail.py、docs/configuration.rst 与 docs/api.rst。

• 后端
• 前端
• 企业应用