5 · 系统特性（System Features）

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

项目Mayan EDMS 章节5 状态全文译文模块文档对象与元数据、工作流与编排、测试、发布与运维、检索、召回与索引

项目要点页2.5 参考项目项目章节目录Mayan EDMS DeepWiki 原始章节System Features 上一章4.4 下一章5.1

源码线索

docs/releases/4.1.9.txt
mayan/apps/acls/api_views.py
mayan/apps/acls/apps.py
mayan/apps/acls/classes.py
mayan/apps/acls/icons.py
mayan/apps/acls/links.py
mayan/apps/acls/managers.py
mayan/apps/acls/models.py
mayan/apps/acls/serializers.py
mayan/apps/acls/tests/mixins.py

模块标签

文档对象与元数据
工作流与编排
测试、发布与运维
检索、召回与索引
认证、权限与安全

中文译文

系统特性（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mayan-edms/Mayan-EDMS/5-system-features

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

翻译模型：deepseek-chat

原文字符数：16905

项目：Mayan EDMS (mayan-edms)

---

系统功能

动态搜索系统

Mayan EDMS 提供了一套可插拔的搜索架构，通过统一的接口支持多种搜索后端。该系统通过模型注册机制，支持对文档、元数据及相关对象的全文搜索。

搜索后端架构

搜索系统围绕 SearchBackend 类构建，为不同的搜索实现提供了通用接口：

graph TB
    subgraph "搜索接口层"
        SearchView["SearchView"]
        AdvancedSearchView["AdvancedSearchView"]
        APISearchView["APISearchView"]
        ResultsView["ResultsView"]
    end

    subgraph "搜索后端层"
        SearchBackend["SearchBackend"]
        WhooshBackend["WhooshSearchBackend"]
        DjangoBackend["DjangoSearchBackend"]
        ElasticBackend["ElasticSearchBackend"]
    end

    subgraph "搜索模型注册表"
        SearchModel["SearchModel"]
        SearchField["SearchField"]
        ModelRegistry["SearchModel._registry"]
    end

    subgraph "数据层"
        Documents["Document"]
        Metadata["DocumentMetadata"]
        Tags["Tag"]
        OCRContent["DocumentVersionPageOCRContent"]
    end

    SearchView --> SearchBackend
    AdvancedSearchView --> SearchBackend
    APISearchView --> SearchBackend
    ResultsView --> SearchBackend

    SearchBackend --> WhooshBackend
    SearchBackend --> DjangoBackend
    SearchBackend --> ElasticBackend

    SearchBackend --> SearchModel
    SearchModel --> SearchField
    SearchModel --> ModelRegistry

    WhooshBackend --> Documents
    DjangoBackend --> Documents
    ElasticBackend --> Documents

    Documents --> Metadata
    Documents --> Tags
    Documents --> OCRContent

来源： mayan/apps/dynamic_search/classes.py:38-509，mayan/apps/dynamic_search/views.py:32-179，mayan/apps/dynamic_search/api_views.py:13-103

搜索模型注册

SearchModel 类通过注册字段和定义搜索行为，使任何 Django 模型都可以被搜索：

组件	用途	关键方法
`SearchModel`	定义可搜索的模型和字段	`add_model_field()`，`get_search_fields()`
`SearchField`	表示单个可搜索字段	`get_model_field()`，`get_help_text()`
`SearchBackend`	提供统一的搜索接口	`search()`，`index_instance()`，`deindex_instance()`

graph LR
    subgraph "模型注册流程"
        Model["Django Model"] --> Register["SearchModel Registration"]
        Register --> Fields["SearchField Definition"]
        Fields --> Index["Backend Indexing"]
        Index --> Search["Search Interface"]
    end

    subgraph "搜索执行流程"
        Query["Search Query"] --> Backend["SearchBackend.search()"]
        Backend --> Decode["decode_query()"]
        Decode --> Execute["_search()"]
        Execute --> Filter["ACL Filtering"]
        Filter --> Results["Filtered Results"]
    end

    Model --> Query
    Results --> Search

来源： mayan/apps/dynamic_search/classes.py:564-862，mayan/apps/dynamic_search/classes.py:510-563

搜索后端实现

Mayan EDMS 支持多种搜索后端，它们具有不同的性能特征：

Whoosh 后端：使用 Python Whoosh 库的基于文件的全文搜索
Django 后端：使用 Django ORM 查询的基于数据库的搜索
ElasticSearch 后端：使用 ElasticSearch 的分布式搜索

WhooshSearchBackend 提供了最先进的搜索能力：

graph TB
    subgraph "Whoosh 后端组件"
        Schema["get_search_model_schema()"]
        Index["get_or_create_index()"]
        Writer["BufferedWriter"]
        Searcher["index.searcher()"]
    end

    subgraph "索引操作"
        IndexInstance["index_instance()"]
        IndexInstances["index_instances()"]
        DeindexInstance["deindex_instance()"]
    end

    subgraph "搜索操作"
        SearchMethod["_search()"]
        QueryParser["qparser.QueryParser"]
        WhooshQuery["whoosh_query"]
        Results["search_results"]
    end

    Schema --> Index
    Index --> Writer
    Index --> Searcher

    IndexInstance --> Writer
    IndexInstances --> Writer
    DeindexInstance --> Writer

    SearchMethod --> QueryParser
    QueryParser --> WhooshQuery
    Searcher --> Results

来源： mayan/apps/dynamic_search/backends/whoosh.py:28-292，mayan/apps/dynamic_search/backends/django.py:15-194

访问控制列表（ACL）系统

ACL 系统通过向特定对象的角色授予权限（而非系统范围的权限），提供了细粒度的访问控制。

ACL 架构

graph TB
    subgraph "ACL 核心组件"
        ACL["AccessControlList"]
        Role["Role"]
        Permission["StoredPermission"]
        ContentObject["content_object (GenericForeignKey)"]
    end

    subgraph "ACL 管理器操作"
        ACLManager["AccessControlListManager"]
        RestrictQueryset["restrict_queryset()"]
        CheckAccess["check_access()"]
        GetACLFilters["_get_acl_filters()"]
    end

    subgraph "权限继承"
        ModelPermission["ModelPermission"]
        RegisterInheritance["register_inheritance()"]
        GetInheritances["get_inheritances()"]
    end

    ACL --> Role
    ACL --> Permission
    ACL --> ContentObject

    ACLManager --> RestrictQueryset
    ACLManager --> CheckAccess
    RestrictQueryset --> GetACLFilters

    ModelPermission --> RegisterInheritance
    RegisterInheritance --> GetInheritances
    GetACLFilters --> GetInheritances

来源： mayan/apps/acls/models.py:22-121，mayan/apps/acls/managers.py:26-383，mayan/apps/acls/classes.py:17-208

ACL 权限过滤

AccessControlListManager 实现了复杂的权限过滤，能够处理继承关系和关联对象的权限：

过滤类型	实现方式	用途
直接对象	`content_type` + `object_id` 查询	直接授予对象的权限
关联字段	外键遍历	通过关联对象获得的权限
通用外键	`ct_fk_combination` 注解	内容类型 + 对象 ID 组合
继承	递归字段遍历	父对象权限继承

graph LR
    subgraph "权限检查流程"
        User["User Request"] --> Check["AccessControlList.objects.check_access()"]
        Check --> DirectPerms["Direct Permission Check"]
        Check --> RolePerms["Role Permission Check"]
        DirectPerms --> ACLQuery["ACL Query Filtering"]
        RolePerms --> ACLQuery
        ACLQuery --> Result["Access Granted/Denied"]
    end

    subgraph "查询集过滤"
        Queryset["Model Queryset"] --> Restrict["restrict_queryset()"]
        Restrict --> Filters["_get_acl_filters()"]
        Filters --> Cases["Filter Cases 1-7"]
        Cases --> FilteredSet["Filtered Queryset"]
    end

来源： mayan/apps/acls/managers.py:31-231，mayan/apps/acls/managers.py:268-295

权限管理

权限系统提供了一种声明式的方法，使用命名空间和角色在应用程序中定义和管理权限。

权限类层次结构

graph TB
    subgraph "权限定义"
        PermissionNamespace["PermissionNamespace"]
        Permission["Permission"]
        StoredPermission["StoredPermission"]
    end

    subgraph "权限分配"
        Role["Role"]
        Group["Group"]
        User["User"]
    end

    subgraph "权限检查"
        ModelPermission["ModelPermission"]
        PermissionCheck["Permission.check_user_permissions()"]
        UserHasThis["StoredPermission.user_has_this()"]
    end

    PermissionNamespace --> Permission
    Permission --> StoredPermission

    Role --> Group
    Group --> User
    Role --> StoredPermission

    ModelPermission --> PermissionCheck
    PermissionCheck --> UserHasThis
    UserHasThis --> Role

来源： mayan/apps/permissions/classes.py:16-155，mayan/apps/permissions/models.py:23-217

权限注册与检查

ModelPermission 类管理模型的权限注册，并提供继承机制：

# 权限注册示例
ModelPermission.register(
    model=Document,
    permissions=(permission_document_view, permission_document_edit)
)

# 权限继承设置
ModelPermission.register_inheritance(
    model=DocumentFile,
    related='document'
)

方法	用途	使用场景
`register()`	为模型注册权限	将权限链接到模型类
`register_inheritance()`	设置权限继承	子对象从父对象继承
`get_for_class()`	获取模型权限	检索适用的权限
`check_user_permissions()`	验证用户访问权限	权限检查逻辑

来源： mayan/apps/acls/classes.py:126-187，mayan/apps/permissions/classes.py:65-74

高级功能集成

异步搜索索引

搜索系统使用 Celery 任务进行后台索引，以保持性能：

graph LR
    subgraph "索引管理任务"
        IndexInstance["task_index_instance"]
        IndexInstances["task_index_instances"]
        DeindexInstance["task_deindex_instance"]
        ReindexBackend["task_reindex_backend"]
    end

    subgraph "信号处理器"
        PostSave["post_save signal"]
        PreDelete["pre_delete signal"]
        M2MChanged["m2m_changed signal"]
    end

    subgraph "后端操作"
        SearchBackend["SearchBackend"]
        WhooshIndex["Whoosh Index"]
        Lock["LockingBackend"]
    end

    PostSave --> IndexInstance
    PreDelete --> DeindexInstance
    M2MChanged --> IndexInstance

    IndexInstance --> SearchBackend
    IndexInstances --> SearchBackend
    DeindexInstance --> SearchBackend

    SearchBackend --> Lock
    SearchBackend --> WhooshIndex

来源： mayan/apps/dynamic_search/tasks.py:22-166，mayan/apps/dynamic_search/classes.py:86-146

多后端搜索支持

系统通过配置支持同时运行多个搜索后端：

后端	使用场景	配置方式
`WhooshSearchBackend`	全文搜索，开发环境	基于文件的索引
`DjangoSearchBackend`	简单查询，小数据集	仅数据库查询
`ElasticSearchBackend`	大规模，分布式	外部 ElasticSearch 集群

REST 接口集成

所有主要功能都通过一致的权限检查暴露 REST API 端点：

graph TB
    subgraph "搜索 API 端点"
        APISearchView["APISearchView"]
        APIAdvancedSearchView["APIAdvancedSearchView"]
        APISearchModelList["APISearchModelList"]
    end

    subgraph "ACL API 端点"
        APIACLListView["APIACLListView"]
        APIACLDetailView["APIACLDetailView"]
        APIACLPermissionAddView["APIACLPermissionAddView"]
    end

    subgraph "权限集成"
        ObjectPermissions["mayan_object_permissions"]
        ExternalPermissions["mayan_external_object_permissions"]
        PermissionCheck["Permission Checking"]
    end

    APISearchView --> ObjectPermissions
    APIACLListView --> ExternalPermissions
    ObjectPermissions --> PermissionCheck
    ExternalPermissions --> PermissionCheck

来源： mayan/apps/dynamic_search/api_views.py:13-103，mayan/apps/acls/api_views.py:16-165，mayan/apps/permissions/api_views.py:21-158