4.2 · 文档处理（Document Processing）

企业电子文档治理 · 本章是 Mayan EDMS DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Mayan EDMS 章节4.2 状态全文译文模块入库与解析、文档对象与元数据、工作流与编排、配置治理

项目要点页2.5 参考项目项目章节目录Mayan EDMS DeepWiki 原始章节Document Processing 上一章4.1 下一章4.3

源码线索

mayan/apps/converter/__init__.py
mayan/apps/converter/backends/__init__.py
mayan/apps/converter/backends/python.py
mayan/apps/converter/classes.py
mayan/apps/converter/layers.py
mayan/apps/converter/literals.py
mayan/apps/converter/migrations/0017_auto_20200810_0504.py
mayan/apps/converter/migrations/0018_asset.py
mayan/apps/converter/settings.py
mayan/apps/converter/tasks.py

模块标签

入库与解析
文档对象与元数据
工作流与编排
配置治理
系统架构

中文译文

文档处理（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mayan-edms/Mayan-EDMS/4.2-document-processing

翻译时间：2026-05-27T08:44:36.095Z

翻译模型：deepseek-chat

原文字符数：18187

项目：Mayan EDMS (mayan-edms)

---

文档处理

核心转换系统

文档转换系统基于 ConverterBase 类构建，该类提供了一个统一接口，用于将各种文档格式转换为图像以供显示和进一步处理。

转换器架构

转换器系统通过可插拔架构支持多个后端：

graph TB
    subgraph "转换器框架"
        ConverterBase["ConverterBase<br/>mayan.apps.converter.classes"]
        ConverterSettings["setting_graphics_backend<br/>setting_graphics_backend_arguments"]

        ConverterBase --> PythonBackend["Python 后端<br/>backends.python.Python"]
        ConverterBase --> OtherBackends["其他后端<br/>（可插拔）"]
    end

    subgraph "文档处理"
        DocumentFile["DocumentFile"] --> ConverterBase
        ConverterBase --> PageExtraction["页面提取<br/>seek_page()"]
        ConverterBase --> ImageGeneration["图像生成<br/>get_page()"]
        ConverterBase --> PageCount["页数统计<br/>get_page_count()"]
    end

    subgraph "格式支持"
        PDFFiles["PDF 文件<br/>PyPDF2 + pdftoppm"] --> ConverterBase
        OfficeFiles["Office 文件<br/>LibreOffice + soffice()"] --> ConverterBase
        ImageFiles["图像文件<br/>PIL/Pillow"] --> ConverterBase
        MSGFiles["MSG 文件<br/>MsgArchive"] --> ConverterBase
    end

    subgraph "外部工具"
        LibreOffice["LibreOffice<br/>--headless --convert-to pdf"]
        Pdftoppm["pdftoppm<br/>-jpeg -r 300"]
        Pdfinfo["pdfinfo<br/>页数检测"]
    end

    OfficeFiles --> LibreOffice
    PDFFiles --> Pdftoppm
    PDFFiles --> Pdfinfo

来源：mayan/apps/converter/classes.py:74-273, mayan/apps/converter/backends/python.py:64-206, mayan/apps/converter/settings.py:61-72

文档格式转换

系统通过特定的转换路径处理多种文档格式：

格式类型	MIME 类型	转换方法	外部依赖
PDF	`application/pdf`	使用 PyPDF2 + pdftoppm 直接处理	`pdftoppm`, `pdfinfo`
Office 文档	各种 Office/OpenDocument 格式	通过 LibreOffice 转换为 PDF	`libreoffice`
图像	标准图像格式	使用 PIL/Pillow 处理	无（Python 库）
MSG 文件	`application/vnd.ms-outlook`	归档提取 + 内容转换	无

Python 后端实现了核心转换逻辑：

graph LR
    subgraph "Python 后端转换流程"
        InputFile["文件对象<br/>+ MIME 类型"] --> MimeDetection["MIME 类型<br/>检测"]

        MimeDetection --> PDFPath["PDF 处理<br/>PyPDF2 + pdftoppm"]
        MimeDetection --> OfficePath["Office 处理<br/>soffice() → PDF"]
        MimeDetection --> ImagePath["图像处理<br/>PIL/Pillow"]
        MimeDetection --> MSGPath["MSG 处理<br/>MsgArchive → 内容"]

        PDFPath --> PageExtraction["seek_page(page_number)"]
        OfficePath --> TempPDF["临时 PDF"] --> PageExtraction
        ImagePath --> PageExtraction
        MSGPath --> ExtractedContent["message.txt 或第一个成员"] --> PageExtraction

        PageExtraction --> ImageOutput["get_page()<br/>JPEG/PNG 输出"]
    end

来源：mayan/apps/converter/backends/python.py:64-206, mayan/apps/converter/literals.py:7-51, mayan/apps/converter/classes.py:152-260

OCR 处理系统

OCR 系统使用可配置的 OCR 后端从文档图像中提取文本内容，其中 Tesseract 是主要实现。

OCR 架构

graph TB
    subgraph "OCR 框架"
        OCRBackendBase["OCRBackendBase<br/>mayan.apps.ocr.classes"]
        OCRSettings["setting_ocr_backend<br/>setting_ocr_backend_arguments"]

        OCRBackendBase --> TesseractBackend["Tesseract 后端<br/>backends.tesseract.Tesseract"]
    end

    subgraph "OCR 模型"
        DocumentTypeOCRSettings["DocumentTypeOCRSettings<br/>auto_ocr 配置"]
        DocumentVersionPageOCRContent["DocumentVersionPageOCRContent<br/>提取的文本存储"]
    end

    subgraph "OCR 处理管线"
        DocumentVersionPage["DocumentVersionPage"] --> OCRBackendBase
        OCRBackendBase --> ConverterBase["ConverterBase<br/>图像生成"]
        ConverterBase --> ImagePage["页面图像"]
        ImagePage --> TesseractExecution["tesseract 命令<br/>语言检测"]
        TesseractExecution --> TextContent["提取的文本"]
        TextContent --> DocumentVersionPageOCRContent
    end

    subgraph "OCR 管理"
        SubmitOCR["submit_for_ocr()<br/>Document/DocumentVersion 上的方法"]
        OCRViews["OCR 视图<br/>内容显示、编辑"]
        OCRAPI["OCR API<br/>REST 端点"]
    end

    DocumentTypeOCRSettings --> SubmitOCR
    DocumentVersionPageOCRContent --> OCRViews
    DocumentVersionPageOCRContent --> OCRAPI

来源：mayan/apps/ocr/classes.py:8-31, mayan/apps/ocr/backends/tesseract.py:20-116, mayan/apps/ocr/models.py:17-74

OCR 后端实现

Tesseract 后端提供了主要的 OCR 功能：

graph LR
    subgraph "Tesseract OCR 执行"
        Initialize["initialize()<br/>检测 tesseract 二进制文件<br/>获取可用语言"] --> Execute["execute()<br/>file_object + language"]

        Execute --> Converter["ConverterBase<br/>get_page() → 图像"]
        Converter --> TempFile["TemporaryFile<br/>图像数据"]
        TempFile --> TesseractCmd["tesseract 命令<br/>-l language - -"]

        TesseractCmd --> TextOutput["force_text(stdout)<br/>提取的文本"]
        TesseractCmd --> ErrorHandling["OCRError<br/>语言不可用<br/>执行失败"]
    end

    subgraph "配置"
        TesseractSettings["tesseract_path<br/>timeout<br/>environment<br/>language"]
    end

    TesseractSettings --> Initialize
    TesseractSettings --> Execute

来源：mayan/apps/ocr/backends/tesseract.py:78-116, mayan/apps/ocr/backends/literals.py:1-9

OCR 内容管理

系统通过模型、视图和 API 端点提供全面的 OCR 内容管理：

组件	用途	关键类/方法
内容存储	按页面存储提取的文本	`DocumentVersionPageOCRContent`
类型设置	按文档类型配置自动 OCR	`DocumentTypeOCRSettings`
提交	触发 OCR 处理	`submit_for_ocr()` 方法
内容访问	查看和编辑 OCR 结果	OCR 视图和 API 端点
内容删除	移除 OCR 数据	`delete_content_for()` 管理器方法

来源：mayan/apps/ocr/models.py:17-74, mayan/apps/ocr/views.py:38-270, mayan/apps/ocr/api_views.py:23-124

文档解析系统

文档解析系统使用特定格式的解析器从文档中提取原始文本内容，主要针对 PDF 文件。

解析器框架

graph TB
    subgraph "解析器框架"
        ParserBase["Parser<br/>基类，带注册表"]
        ParserRegistry["Parser._registry<br/>mimetype → parser_classes 映射"]

        ParserBase --> PopplerParser["PopplerParser<br/>PDF 文本提取"]
        ParserBase --> OfficePopplerParser["OfficePopplerParser<br/>Office → PDF → 文本"]
    end

    subgraph "文档处理"
        DocumentFile["DocumentFile"] --> ParserBase
        ParserBase --> DocumentFilePageContent["DocumentFilePageContent<br/>提取的文本存储"]
    end

    subgraph "外部工具"
        PdfToText["pdftotext<br/>poppler-utils"]
        ConverterBase["ConverterBase<br/>office 文件转换"]
    end

    PopplerParser --> PdfToText
    OfficePopplerParser --> ConverterBase
    ConverterBase --> PdfToText

    subgraph "MIME 类型注册"
        PDFTypes["application/pdf"] --> PopplerParser
        OfficeTypes["Office MIME 类型<br/>CONVERTER_OFFICE_FILE_MIMETYPES"] --> OfficePopplerParser
    end

来源：mayan/apps/document_parsing/parsers.py:20-184, mayan/apps/converter/literals.py:7-51

PDF 文本提取

PopplerParser 使用 pdftotext 工具提取文本内容：

graph LR
    subgraph "PDF 文本提取过程"
        PDFFile["PDF 文件"] --> TempFile["NamedTemporaryFile<br/>复制文件内容"]
        TempFile --> PdfToTextCmd["pdftotext -f page -l page<br/>temp_file -"]

        PdfToTextCmd --> SubProcess["subprocess.Popen<br/>捕获 stdout/stderr"]
        SubProcess --> TextOutput["force_text(output)<br/>处理特殊字符"]
        SubProcess --> ErrorCheck["return_code != 0<br/>抛出 ParserError"]

        TextOutput --> ContentStorage["DocumentFilePageContent<br/>update_or_create()"]
    end

    subgraph "配置"
        PdfToTextPath["setting_pdftotext_path<br/>可执行文件位置"]
    end

    PdfToTextPath --> PdfToTextCmd

来源：mayan/apps/document_parsing/parsers.py:112-163

文件元数据提取

文件元数据系统使用 ExifTool 等外部工具从文档文件中提取技术元数据。

元数据驱动架构

graph TB
    subgraph "元数据框架"
        FileMetadataDriver["FileMetadataDriver<br/>基类"]
        DriverSettings["setting_drivers_arguments<br/>驱动配置"]

        FileMetadataDriver --> EXIFToolDriver["EXIFToolDriver<br/>通用元数据提取"]
    end

    subgraph "处理管线"
        DocumentFile["DocumentFile"] --> FileMetadataDriver
        FileMetadataDriver --> TempDirectory["TemporaryDirectory<br/>文件提取"]
        TempDirectory --> ExifToolCmd["exiftool -j<br/>JSON 输出"]
        ExifToolCmd --> MetadataResult["JSON 元数据<br/>文件属性"]
    end

    subgraph "外部工具"
        ExifTool["exiftool 二进制文件<br/>综合元数据工具"]
    end

    ExifToolCmd --> ExifTool

    subgraph "MIME 支持"
        AllMimeTypes["*（所有 MIME 类型）<br/>通用支持"] --> EXIFToolDriver
    end

来源：mayan/apps/file_metadata/drivers/exiftool.py:18-74, mayan/apps/file_metadata/literals.py:1-14

处理管线集成

文档处理组件在由文档生命周期事件触发的协调管线中协同工作：

graph TB
    subgraph "文档处理管线"
        DocumentCreation["文档创建<br/>DocumentFile 创建"] --> ProcessingTrigger["处理触发器<br/>信号处理器"]

        ProcessingTrigger --> ConverterProcessing["转换器处理<br/>页面提取<br/>图像生成"]
        ProcessingTrigger --> MetadataExtraction["元数据提取<br/>文件属性"]
        ProcessingTrigger --> ContentParsing["内容解析<br/>文本提取"]

        ConverterProcessing --> OCRProcessing["OCR 处理<br/>如果 auto_ocr 启用"]

        OCRProcessing --> ContentIndexing["内容索引<br/>搜索集成"]
        ContentParsing --> ContentIndexing
        MetadataExtraction --> ContentIndexing
    end

    subgraph "配置控制"
        DocumentTypeSettings["DocumentTypeOCRSettings<br/>auto_ocr 标志"]
        BackendSettings["后端设置<br/>graphics_backend<br/>ocr_backend"]
        ExternalTools["外部工具路径<br/>libreoffice_path<br/>tesseract_path<br/>pdftotext_path"]
    end

    DocumentTypeSettings --> OCRProcessing
    BackendSettings --> ConverterProcessing
    BackendSettings --> OCRProcessing
    ExternalTools --> ConverterProcessing
    ExternalTools --> OCRProcessing
    ExternalTools --> ContentParsing

来源：mayan/apps/converter/settings.py:61-72, mayan/apps/ocr/settings.py:15-28, mayan/apps/ocr/apps.py:57-211

任务队列集成

文档处理操作使用 Celery 任务异步执行，以处理资源密集型操作：

graph LR
    subgraph "异步处理"
        SubmitOCR["submit_for_ocr()<br/>排队 OCR 任务"] --> CeleryQueue["Celery 任务队列"]
        ImageGeneration["图像生成<br/>task_content_object_image_generate"] --> CeleryQueue
        MetadataProcessing["元数据处理<br/>task_process_document_file"] --> CeleryQueue

        CeleryQueue --> Workers["Celery 工作进程<br/>后台处理"]
        Workers --> ProcessingComplete["处理完成<br/>内容可用"]
    end

    subgraph "锁管理"
        LockManager["LockingBackend<br/>防止并发处理"] --> Workers
    end

    subgraph "错误处理"
        MaxRetries["max_retries 配置"] --> Workers
        RetryBackoff["retry_backoff 策略"] --> Workers
        LockError["LockError 处理"] --> Workers
    end

来源：mayan/apps/converter/tasks.py:17-65, mayan/apps/file_metadata/tasks.py:17-49, mayan/apps/ocr/methods.py

配置与设置

文档处理系统提供了丰富的配置选项，用于自定义后端行为和外部工具集成：

设置类别	关键设置	用途
图形后端	`CONVERTER_GRAPHICS_BACKEND`<br/>`CONVERTER_GRAPHICS_BACKEND_ARGUMENTS`	图像转换引擎和参数
OCR 后端	`OCR_BACKEND`<br/>`OCR_BACKEND_ARGUMENTS`	文本提取引擎和配置
外部工具	`libreoffice_path`<br/>`tesseract_path`<br/>`pdftotext_path`	工具可执行文件位置
处理限制	`pillow_maximum_image_pixels`<br/>`tesseract_timeout`	资源和时间约束
自动处理	`OCR_AUTO_OCR`<br/>`auto_ocr` 按文档类型	自动处理触发器

来源：mayan/apps/converter/settings.py:20-96, mayan/apps/ocr/settings.py:10-29, mayan/apps/converter/literals.py:85-93