3 · 核心架构（Core Architecture）

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

项目Mayan EDMS 章节3 状态全文译文模块文档对象与元数据、工作流与编排、界面与交互、系统架构

项目要点页2.5 参考项目项目章节目录Mayan EDMS DeepWiki 原始章节Core Architecture 上一章2.2 下一章3.1

源码线索

mayan/apps/common/api_views.py
mayan/apps/common/apps.py
mayan/apps/common/classes.py
mayan/apps/common/forms.py
mayan/apps/common/links.py
mayan/apps/common/literals.py
mayan/apps/common/serializers.py
mayan/apps/common/settings.py
mayan/apps/common/tests/mixins.py
mayan/apps/common/tests/test_api.py

模块标签

文档对象与元数据
工作流与编排
界面与交互
系统架构
接口与服务契约

中文译文

核心架构（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mayan-edms/Mayan-EDMS/3-core-architecture

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

翻译模型：deepseek-chat

原文字符数：11231

项目：Mayan EDMS (mayan-edms)

---

核心架构

目的与范围

本文档概述了 Mayan EDMS 的基础架构，涵盖了构成系统基础的核心框架、设计模式以及组件之间的关系。本文档重点介绍了基于 Django 的应用框架、自定义的 MayanAppConfig 系统，以及主要子系统如何集成在一起。

有关特定子系统的详细信息，请参阅：

应用框架实现细节：应用框架
文档模型与生命周期：文档管理核心
Web 界面与导航：用户界面系统
API 设计与端点：REST API 架构

系统基础

Mayan EDMS 基于 Django 3.2+ 构建，并进行了大量的自定义和扩展。该系统采用模块化应用架构，每个功能区域都实现为一个 Django 应用，并通过 MayanAppConfig 框架增强了功能。

Django 设置与应用加载

系统的基础在主设置文件中建立，该文件定义了应用栈和核心配置：

graph TB
    Django["Django 框架"] --> Settings["mayan/settings/base.py"]
    Settings --> SmartSettings["SettingNamespaceSingleton"]
    Settings --> InstalledApps["INSTALLED_APPS"]

    InstalledApps --> CoreApps["核心应用<br/>events, appearance, common"]
    InstalledApps --> BaseApps["基础应用<br/>acls, authentication, permissions"]
    InstalledApps --> DocumentApps["文档应用<br/>documents, sources, ocr"]

    SmartSettings --> GlobalConfig["全局配置"]
    CoreApps --> MayanAppConfig["MayanAppConfig"]
    BaseApps --> MayanAppConfig
    DocumentApps --> MayanAppConfig

Django 应用栈概览

来源：mayan/settings/base.py:43-133

应用加载遵循特定顺序，以确保正确的初始化依赖关系。核心基础设施应用（如 events 和 appearance）首先加载，然后是认证和权限系统，最后是文档特定功能。

MayanAppConfig 框架

MayanAppConfig 类扩展了 Django 的 AppConfig，以提供增强的应用生命周期管理、URL 路由和组件注册功能：

graph TB
    DjangoAppConfig["django.apps.AppConfig"] --> MayanAppConfig["MayanAppConfig"]
    MayanAppConfig --> DocumentsApp["DocumentsApp"]
    MayanAppConfig --> CommonApp["CommonApp"]
    MayanAppConfig --> OtherApps["其他应用配置"]

    MayanAppConfig --> URLConfig["configure_urls()"]
    MayanAppConfig --> ReadyMethod["ready()"]

    URLConfig --> URLPatterns["URL 模式注册"]
    URLConfig --> Namespaces["应用命名空间设置"]

    ReadyMethod --> ModelRegistration["模型注册"]
    ReadyMethod --> EventSetup["事件系统设置"]
    ReadyMethod --> PermissionSetup["权限注册"]
    ReadyMethod --> MenuIntegration["菜单集成"]

MayanAppConfig 组件注册流程

来源：mayan/apps/common/apps.py:27-121, mayan/apps/documents/apps.py:209-1216

每个应用的 ready() 方法会执行大量的组件注册，包括模型、事件、权限、菜单链接、仪表盘小部件和导航元素。

核心系统组件

智能设置系统

设置系统提供动态配置管理，支持环境变量和命名空间组织：

graph LR
    Environment["环境变量"] --> SettingNamespace["SettingNamespaceSingleton"]
    YAMLConfig["YAML 配置文件"] --> SettingNamespace
    Defaults["默认值"] --> SettingNamespace

    SettingNamespace --> GlobalSymbols["globals()"]
    SettingNamespace --> DjangoSettings["Django 设置"]

    Apps["应用配置"] --> SettingNamespace
    SettingNamespace --> RuntimeConfig["运行时配置"]

配置管理架构

来源：mayan/settings/base.py:18-28, mayan/apps/common/settings.py:15-97

文档管理核心

文档管理系统围绕几个关键模型层级展开：

graph TB
    DocumentType["DocumentType"] --> Document["Document"]
    Document --> DocumentFile["DocumentFile"]
    Document --> DocumentVersion["DocumentVersion"]

    DocumentFile --> DocumentFilePage["DocumentFilePage"]
    DocumentVersion --> DocumentVersionPage["DocumentVersionPage"]

    Document --> TrashedDocument["TrashedDocument<br/>(代理模型)"]
    Document --> FavoriteDocument["FavoriteDocument"]
    Document --> RecentlyAccessedDocument["RecentlyAccessedDocument"]

    Manager["自定义管理器"] --> ValidDocumentManager["ValidDocumentManager"]
    Manager --> TrashCanManager["TrashCanManager"]
    Manager --> DocumentTypeManager["DocumentTypeManager"]

核心文档模型关系

来源：mayan/apps/documents/managers.py:20-322, mayan/apps/documents/apps.py:221-252

任务处理与后台作业

系统使用 Celery 进行异步任务处理，后端支持 Redis 或 RabbitMQ：

graph LR
    UserActions["用户操作"] --> Tasks["Celery 任务"]
    APIRequests["API 请求"] --> Tasks

    Tasks --> DocumentUpload["task_document_upload"]
    Tasks --> FileProcessing["task_document_file_page_count_update"]
    Tasks --> VersionExport["task_document_version_export"]
    Tasks --> DocumentDeletion["task_trashed_document_delete"]

    Tasks --> CeleryWorkers["Celery 工作进程"]
    CeleryWorkers --> RedisBackend["Redis 后端"]
    CeleryWorkers --> RabbitMQ["RabbitMQ 消息代理"]

异步任务处理架构

来源：mayan/apps/documents/tasks.py:19-333, mayan/settings/base.py:285-301

请求处理流程

系统通过 Django 的 URL 路由（带有自定义扩展）处理 Web 界面和 API 请求：

graph TB
    HTTPRequest["HTTP 请求"] --> URLRouter["Django URL 路由器"]
    URLRouter --> AppURLs["应用 URL 模式"]

    AppURLs --> WebViews["Web 视图<br/>documents/views/"]
    AppURLs --> APIViews["API 视图<br/>api_views/"]

    WebViews --> Permissions["权限检查"]
    APIViews --> Permissions

    Permissions --> Models["模型访问"]
    Models --> Database["数据库层"]

    WebViews --> Templates["Django 模板"]
    APIViews --> Serializers["DRF 序列化器"]

    Templates --> HTTPResponse["HTTP 响应"]
    Serializers --> HTTPResponse

请求处理与响应流程

来源：mayan/apps/documents/urls.py:95-689, mayan/apps/documents/views/document_views.py:36-211

导航与菜单系统

用户界面提供了一个动态导航系统，包含上下文感知菜单：

组件	用途	关键类
菜单系统	层级导航结构	`menu_main`, `menu_setup`, `menu_tools`
链接注册表	基于权限的动态链接生成	`Link`, `SourceColumn`
AJAX 导航	部分页面更新	`AjaxRedirect` 中间件
仪表盘小部件	可定制的仪表盘组件	`DashboardWidget` 子类

来源：mayan/apps/common/apps.py:146-153, mayan/apps/documents/apps.py:750-1216

集成模式

模型注册与事件

系统使用集中式注册模式来处理横切关注点：

graph TB
    ModelRegistration["模型注册"] --> EventRegistry["EventModelRegistry"]
    ModelRegistration --> PermissionRegistry["ModelPermission"]
    ModelRegistration --> SearchRegistry["搜索模型注册表"]
    ModelRegistration --> CopyRegistry["ModelCopy 注册表"]

    EventRegistry --> EventTypes["事件类型映射"]
    PermissionRegistry --> ACLSystem["ACL 权限系统"]
    SearchRegistry --> DynamicSearch["动态搜索后端"]
    CopyRegistry --> ObjectCopy["对象复制功能"]

    AppReady["App.ready()"] --> ModelRegistration

横切组件注册模式

来源：mayan/apps/documents/apps.py:290-518, mayan/apps/common/classes.py:14-342

数据库与查询优化

系统通过管理器自定义和预取策略实现查询优化：

管理器类型	用途	关键特性
`ValidDocumentManager`	过滤非回收站文档	自动回收站过滤
`ModelQueryFields`	查询优化	预取和 select_related 提示
`TrashCanManager`	回收站文档访问	已删除项目的独立查询集

来源：mayan/apps/documents/managers.py:189-322, mayan/apps/documents/apps.py:519-554

该架构为文档管理提供了一个可扩展的基础，具有清晰的关注点分离、广泛的定制能力以及强大的集成模式，能够支持企业文档管理所需的复杂工作流。