4.1 · 文档入库（Document Ingestion）

文档入库（中文译文）

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

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

翻译模型：deepseek-chat

原文字符数：13572

项目：Mayan EDMS (mayan-edms)

---

文档入库

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• mayan/apps/cabinets/tests/test_wizard_steps.py
• mayan/apps/cabinets/wizard_steps.py
• mayan/apps/dependencies/dependencies.py
• mayan/apps/metadata/api.py
• mayan/apps/metadata/api_views.py
• mayan/apps/metadata/forms.py
• mayan/apps/metadata/models.py
• mayan/apps/metadata/serializers.py
• mayan/apps/metadata/tests/literals.py
• mayan/apps/metadata/tests/mixins.py
• mayan/apps/metadata/tests/test_forms.py
• mayan/apps/metadata/tests/test_models.py
• mayan/apps/metadata/tests/test_wizard_steps.py
• mayan/apps/metadata/urls.py
• mayan/apps/metadata/wizard_steps.py
• mayan/apps/quotas/tests/test_hooks.py
• mayan/apps/sources/admin.py
• mayan/apps/sources/api_views.py
• mayan/apps/sources/apps.py
• mayan/apps/sources/classes.py
• mayan/apps/sources/dependencies.py
• mayan/apps/sources/forms.py
• mayan/apps/sources/links.py
• mayan/apps/sources/literals.py
• mayan/apps/sources/migrations/0010_auto_20151001_0055.py
• mayan/apps/sources/migrations/0027_auto_20201030_0259.py
• mayan/apps/sources/models.py
• mayan/apps/sources/serializers.py
• mayan/apps/sources/source_backends/sane_scanner_backends.py
• mayan/apps/sources/tasks.py
• mayan/apps/sources/tests/test_api.py
• mayan/apps/sources/tests/test_views.py
• mayan/apps/sources/urls.py
• mayan/apps/sources/wizards.py
• mayan/apps/tags/tests/literals.py
• mayan/apps/tags/tests/test_document_tag_api.py
• mayan/apps/tags/tests/test_indexing.py
• mayan/apps/tags/tests/test_tag_api.py
• mayan/apps/tags/tests/test_tag_document_api.py
• mayan/apps/tags/tests/test_wizard_steps.py
• mayan/apps/tags/wizard_steps.py

文档入库是文件进入 Mayan EDMS 系统并转换为受管文档的过程。该系统通过可配置的源提供多种入库机制，支持带有元数据捕获的多步骤上传向导，并与更广泛的文档生命周期管理功能集成。

有关入库后文档处理（OCR、转换）的信息，请参阅文档处理。有关入库期间应用的文档组织功能，请参阅文档组织。

入库架构总览

文档入库系统围绕 Source 模型和实现不同入库方法的可插拔 SourceBackend 类构建。

graph TB
    subgraph "入库入口点"
        WEB["Web 上传表单"]
        SCANNER["SANE 扫描仪"]
        EMAIL["邮件源"]
        WATCH["监控文件夹"]
        API["REST API"]
    end

    subgraph "源框架"
        SOURCE["Source 模型"]
        BACKEND["SourceBackend 类"]
        WIZARD["DocumentCreateWizard"]
    end

    subgraph "上传处理"
        SHARED["SharedUploadedFile"]
        TASK["task_process_document_upload"]
        CALLBACK["源回调"]
    end

    subgraph "文档创建"
        DOC["Document 模型"]
        DOCFILE["DocumentFile"]
        VERSION["DocumentVersion"]
    end

    subgraph "集成系统"
        META["元数据录入"]
        TAGS["标签分配"]
        CABINETS["文件柜组织"]
        QUOTAS["配额校验"]
    end

    WEB --> SOURCE
    SCANNER --> SOURCE
    EMAIL --> SOURCE
    WATCH --> SOURCE
    API --> SOURCE

    SOURCE --> BACKEND
    SOURCE --> WIZARD

    WIZARD --> SHARED
    BACKEND --> SHARED

    SHARED --> TASK
    TASK --> DOC
    DOC --> DOCFILE
    DOCFILE --> VERSION

    TASK --> CALLBACK

    WIZARD --> META
    WIZARD --> TAGS
    WIZARD --> CABINETS
    TASK --> QUOTAS

来源：mayan/apps/sources/models.py:28-186, mayan/apps/sources/classes.py:111-236, mayan/apps/sources/wizards.py:22-134

源模型与后端系统

Source 模型作为文档入库的核心抽象，通过可插拔的后端实现具体的入库机制。

源模型

Source 模型 mayan/apps/sources/models.py:28-43 提供以下字段：

字段	用途
label	人类可读的源标识符
enabled	控制源是否接受新文档
backend_path	指向 SourceBackend 类的点分路径
backend_data	后端的 JSON 配置

核心上传方法 handle_file_object_upload mayan/apps/sources/models.py:87-161 处理文件上传：

1. 按需处理压缩文件展开
2. 创建 SharedUploadedFile 进行临时存储
3. 执行文档创建前钩子
4. 启动后台处理任务
5. 传递回调信息用于后处理

源后端类

SourceBackend mayan/apps/sources/classes.py:111-236 提供基类，用于实现不同的入库机制：

graph TB
    subgraph "SourceBackend 基类"
        BASE["SourceBackend"]
        FIELDS["get_fields()"]
        ACTIONS["get_actions()"]
        CLEAN["clean()"]
        CREATE["create()"]
        DELETE["delete()"]
    end

    subgraph "具体后端"
        WEBFORM["SourceBackendWebForm"]
        SANE["SourceBackendSANEScanner"]
        IMAP["SourceBackendIMAPEmail"]
        POP3["SourceBackendPOP3Email"]
        STAGING["SourceBackendStagingFolder"]
        WATCH["SourceBackendWatchFolder"]
    end

    BASE --> WEBFORM
    BASE --> SANE
    BASE --> IMAP
    BASE --> POP3
    BASE --> STAGING
    BASE --> WATCH

    FIELDS --> WEBFORM
    ACTIONS --> SANE
    CLEAN --> IMAP

来源：mayan/apps/sources/models.py:28-186, mayan/apps/sources/classes.py:111-236

文档上传向导系统

交互式上传向导提供多步骤界面，用于创建文档并捕获元数据和进行组织。

向导架构

DocumentCreateWizard mayan/apps/sources/wizards.py:22-134 使用 Django 的 SessionWizardView，并带有动态注册的步骤：

graph LR
    subgraph "向导框架"
        WIZARD["DocumentCreateWizard"]
        REGISTRY["DocumentCreateWizardStep 注册表"]
        CONDITIONS["步骤条件"]
    end

    subgraph "标准步骤"
        STEP0["document_type_selection"]
        STEP1["metadata_entry"]
        STEP2["tag_selection"]
        STEP3["cabinet_selection"]
    end

    subgraph "步骤实现"
        DOCTYPE["DocumentCreateWizardStepDocumentType"]
        METADATA["DocumentCreateWizardStepMetadata"]
        TAGS["DocumentCreateWizardStepTags"]
        CABINETS["DocumentCreateWizardStepCabinets"]
    end

    WIZARD --> REGISTRY
    REGISTRY --> CONDITIONS

    CONDITIONS --> STEP0
    CONDITIONS --> STEP1
    CONDITIONS --> STEP2
    CONDITIONS --> STEP3

    STEP0 --> DOCTYPE
    STEP1 --> METADATA
    STEP2 --> TAGS
    STEP3 --> CABINETS

向导步骤注册

向导步骤通过 DocumentCreateWizardStep 类 mayan/apps/sources/classes.py:12-89 进行注册：

• 元数据步骤 mayan/apps/metadata/wizard_steps.py:11-68 - 基于文档类型收集文档元数据
• 标签步骤 mayan/apps/tags/wizard_steps.py:13-54 - 允许选择标签以组织文档
• 文件柜步骤 mayan/apps/cabinets/wizard_steps.py:13-55 - 启用文件柜分配以实现层级组织

每个步骤实现：

• condition() - 确定是否应显示该步骤
• get_form_kwargs() - 提供表单配置
• done() - 将步骤数据处理为查询参数
• step_post_upload_process() - 在文档创建后应用更改

来源：mayan/apps/sources/wizards.py:22-134, mayan/apps/sources/classes.py:12-89, mayan/apps/metadata/wizard_steps.py:11-68

文档处理管线

后台处理管线将上传的文件转换为带有相关元数据和组织的受管文档。

上传任务处理

task_process_document_upload mayan/apps/sources/tasks.py:58-104 处理核心文档创建：

graph TD
    START["task_process_document_upload"] --> LOAD["加载模型"]
    LOAD --> OPEN["打开 SharedUploadedFile"]
    OPEN --> HANDLE["source.handle_file_object_upload()"]
    HANDLE --> CLEANUP["删除 SharedUploadedFile"]

    subgraph "文件处理"
        HANDLE --> EXPAND["检查展开标志"]
        EXPAND --> ARCHIVE["Archive.open()"]
        ARCHIVE --> MEMBERS["提取成员"]
        MEMBERS --> RECURSIVE["递归处理"]

        EXPAND --> SINGLE["单文件处理"]
        SINGLE --> SHARED["创建 SharedUploadedFile"]
    end

    subgraph "文档创建"
        SHARED --> HOOKS["Document.execute_pre_create_hooks()"]
        HOOKS --> TASK_DOC["task_document_upload.apply_async()"]
        TASK_DOC --> CALLBACK["Source.callback_post_task_document_upload()"]
    end

    CALLBACK --> RECENT["添加到最近文档"]
    CALLBACK --> TRANSFORM["复制转换"]
    CALLBACK --> BACKEND_CB["后端回调"]

文档上传任务

task_document_upload mayan/apps/documents/tasks.py（在源回调中引用）创建实际的 Document、DocumentFile 和 DocumentVersion 对象，然后触发源回调。

上传后处理

源回调 callback_post_task_document_upload mayan/apps/sources/models.py:44-65：

1. 将文档添加到用户的最近文档中
2. 将源中的任何转换复制到文档页面
3. 调用后端特定的回调以进行额外处理

来源：mayan/apps/sources/tasks.py:58-104, mayan/apps/sources/models.py:44-65

与文档管理系统的集成

文档入库与多个核心 Mayan EDMS 系统集成，以实现丰富的文档创建工作流。

元数据集成

元数据向导步骤 mayan/apps/metadata/wizard_steps.py:58-65 在上传期间处理元数据：

1. 使用 decode_metadata_from_query_string 从向导查询字符串解码元数据
2. 使用 save_metadata_list 将元数据保存到文档
3. 根据文档类型要求校验元数据

标签与文件柜集成

标签和文件柜分配通过上传后处理进行：

• 标签：标签向导步骤 mayan/apps/tags/wizard_steps.py:45-51 将选定的标签附加到文档
• 文件柜：文件柜向导步骤 mayan/apps/cabinets/wizard_steps.py:47-52 将文档添加到选定的文件柜

配额校验

文档创建通过创建前钩子 mayan/apps/quotas/tests/test_hooks.py:44-108 进行配额限制校验：

• 文档数量配额防止超出文档限制
• 文档大小配额强制执行存储约束
• 配额违规会引发 QuotaExceeded 异常

访问控制

源操作需要适当的权限：

操作	权限
文档创建	permission_document_create
文件上传	permission_document_file_new
源管理	permission_sources_*

来源：mayan/apps/metadata/wizard_steps.py:58-65, mayan/apps/tags/wizard_steps.py:45-51, mayan/apps/cabinets/wizard_steps.py:47-52, mayan/apps/quotas/tests/test_hooks.py:44-108

REST 接口集成

源系统通过 APISourceActionDetailView mayan/apps/sources/api_views.py:15-98 提供 REST API 端点，用于程序化文档入库：

• GET /api/sources/{id}/actions/{action}/ - 检索操作参数
• POST /api/sources/{id}/actions/{action}/ - 执行源操作（例如上传）

源操作支持文件上传和自定义参数，从而能够与外部系统和自动化工作流集成。

来源：mayan/apps/sources/api_views.py:15-98, mayan/apps/sources/serializers.py:49-64