1 · Paperless-ngx 介绍（Introduction to Paperless-ngx）

Paperless-ngx 介绍

Paperless-ngx 简介

本文档概述了 Paperless-ngx 系统及其架构和关键组件。它是理解系统设计方式以及不同部分如何相互交互的起点。

Paperless-ngx 是一个文档管理系统，可将实体文档转换为可搜索的在线存档。它使用 OCR（光学字符识别）从文档中提取文本，自动对文档进行分类，并通过 Web 界面使其可搜索。

系统用途与范围

Paperless-ngx 通过提供以下功能帮助用户减少实体纸张：

• 从多个来源进行文档扫描和入库。
• 通过 OCR 处理从图像和 PDF 中提取文本。
• 可搜索的文档存档，支持自动标签。
• 使用标签、通信方和文档类型进行文档组织。
• 使用机器学习进行自动分类。
• 多用户权限系统和工作流自动化。

来源：README.md:18-22、docs/usage.md:7-10

高层架构

Paperless-ngx 采用分层架构，分离关注点并促进模块化。前端是一个 Angular 应用 src-ui/package.json:2-3，后端由 Django 驱动 pyproject.toml:27。

组件关系图

此图通过将系统组件映射到其对应的代码标识符和文件，在概念性的“自然语言空间”和“代码实体空间”之间架起桥梁。

Paperless-ngx · 组件关系图 · 图 1

来源：src-ui/package.json:1-3、pyproject.toml:20-27、docs/configuration.md:27-61、docs/usage.md:14-20

层级描述

• 前端层：基于 Angular 的单页应用 src-ui/package.json:2。详情请参见架构总览。
• 后端层：Django REST Framework API，处理数据操作和业务逻辑 pyproject.toml:40。详情请参见架构总览。
• 处理层：处理文档处理、OCR 和分类的组件。详情请参见文档处理管线。
• 存储层：用于持久化数据的数据库和文件系统。支持 SQLite、PostgreSQL 和 MariaDB docs/configuration.md:58-61。

文档管理核心

Paperless-ngx 的核心用途是文档管理，多个关键系统协同工作。

代码到系统的映射

下图将特定的代码类和管理命令映射到它们在文档生命周期中的功能角色。

Paperless-ngx · 代码到系统的映射 · 图 2

来源：docs/usage.md:120-133、docs/administration.md:512-520、pyproject.toml:61-76

文档处理管线

文档处理管线负责将原始文件转换为受管理的文档。

1. 消费：监控 PAPERLESS_CONSUMPTION_DIR 或通过 API 接收 docs/configuration.md:214-226。
2. OCR：使用 OCRmyPDF 提取文本 pyproject.toml:61。
3. 分类：使用 Any（任意）、All（全部）、Exact（精确）、Regular Expression（正则表达式）、Fuzzy（模糊）或 Auto（自动）等算法自动分配元数据 docs/usage.md:131-133。
4. 工作流：执行触发器和操作（例如，在消费时分配标签）docs/usage.md:107-108。

详情请参见文档处理管线。

核心数据模型

Paperless-ngx 中的主要数据实体包括：

来源：docs/usage.md:22-53

部署与配置

Paperless-ngx 主要通过 Docker 部署。系统使用语义化版本字符串（例如 2.20.15）进行版本管理 src/paperless/version.py:3-5。

• Docker：使用 s6-overlay 进行进程管理 Dockerfile:29-33。
• 环境：通过环境变量（如 PAPERLESS_REDIS 和 PAPERLESS_DBENGINE）进行配置 docs/configuration.md:27-58。
• 安装：提供交互式脚本以便快速设置 docs/setup.md:9-12。

详情请参见入门与安装和配置与部署。

后续步骤

• 如需深入了解技术栈，请参见架构总览。
• 如需设置开发或生产环境，请参见入门与安装。

来源：Dockerfile:1-33、docs/setup.md:1-20、docs/changelog.md:3-5