5.2 · Access Control 与权限（Access Control & Permissions）

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

项目Mayan EDMS 章节5.2 状态全文译文模块系统架构、界面与交互、认证、权限与安全、文档对象与元数据

项目要点页2.5 参考项目项目章节目录Mayan EDMS DeepWiki 原始章节Access Control & Permissions 上一章5.1 下一章6

源码线索

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
mayan/apps/acls/tests/test_api.py

模块标签

系统架构
界面与交互
认证、权限与安全
文档对象与元数据
测试、发布与运维

中文译文

Access Control 与权限（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mayan-edms/Mayan-EDMS/5.2-access-control-and-permissions

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

翻译模型：deepseek-chat

原文字符数：12709

项目：Mayan EDMS (mayan-edms)

---

访问控制与权限

系统架构总览

Mayan EDMS 实现了一个三层权限系统，将基于角色的访问控制（RBAC）与对象级访问控制列表（ACL）相结合。该架构允许通过角色全局授予权限，也可以通过 ACL 针对单个对象授予特定权限。

graph TB
    subgraph "权限框架"
        PN[PermissionNamespace] --> P[Permission]
        P --> SP[StoredPermission]
    end

    subgraph "基于角色的访问控制"
        U[User] --> G[Group]
        G --> R[Role]
        R --> SP
    end

    subgraph "对象级访问控制"
        ACL[AccessControlList] --> R
        ACL --> SP
        ACL --> OBJ[Object]
        OBJ --> CT[ContentType]
    end

    subgraph "权限检查"
        ACLM[AccessControlListManager] --> QF[".restrict_queryset()"]
        ACLM --> CA[".check_access()"]
        QF --> Filter["过滤后的查询集"]
        CA --> Allow["访问授予/拒绝"]
    end

    P --> ACLM
    ACL --> ACLM
    R --> ACLM

来源：mayan/apps/permissions/classes.py:16-155, mayan/apps/acls/managers.py:26-295, mayan/apps/permissions/models.py:23-217

权限系统组件

权限类与命名空间

权限系统围绕组织在 PermissionNamespace 容器中的 Permission 对象构建。每个权限都有一个唯一的标识符，该标识符由命名空间和权限名称组合而成。

graph LR
    NS1[PermissionNamespace<br/>"documents"] --> P1[Permission<br/>"documents.view"]
    NS1 --> P2[Permission<br/>"documents.edit"]
    NS2[PermissionNamespace<br/>"acls"] --> P3[Permission<br/>"acls.view"]
    NS2 --> P4[Permission<br/>"acls.edit"]

    P1 --> SP1[StoredPermission<br/>namespace='documents'<br/>name='view']
    P2 --> SP2[StoredPermission<br/>namespace='documents'<br/>name='edit']

Permission 类提供运行时权限管理，而 StoredPermission 模型则将权限持久化到数据库中，用于角色分配和 ACL 条目。

来源：mayan/apps/permissions/classes.py:49-155, mayan/apps/permissions/models.py:142-217

模型权限注册

ModelPermission 类管理哪些权限适用于哪些 Django 模型，并处理相关模型之间的权限继承。

graph TB
    MP[ModelPermission] --> REG[".register()"]
    MP --> INH[".register_inheritance()"]
    MP --> GFC[".get_for_class()"]

    REG --> M1[Document Model]
    REG --> P1[document_view]
    REG --> P2[document_edit]

    INH --> CM[Child Model]
    INH --> PM[Parent Model]
    INH --> RF[related_field]

    GFC --> PL[Permission List]

来源：mayan/apps/acls/classes.py:17-208

访问控制列表（ACL）

ACL 模型结构

AccessControlList 模型使用 Django 的通用外键机制，在角色、权限和特定对象之间建立关联。

graph LR
    ACL[AccessControlList] --> R[Role]
    ACL --> CT[ContentType]
    ACL --> OID[object_id]
    ACL --> PERMS[permissions<br/>ManyToMany]

    CT --> OBJ[Any Model Instance]
    OID --> OBJ
    PERMS --> SP[StoredPermission]

    R --> G[Groups]
    G --> U[Users]

每个 ACL 条目为特定对象授予角色特定的权限。用户通过其在角色中的组成员身份获得访问权限。

来源：mayan/apps/acls/models.py:22-116

ACL 权限检查逻辑

AccessControlListManager 通过两个主要方法实现核心的权限检查逻辑：

restrict_queryset() - 过滤查询集，仅包含用户可以访问的对象
check_access() - 验证用户是否对某个对象拥有特定权限

flowchart TD
    START[User Request] --> AUTH{User<br/>Authenticated?}
    AUTH -->|No| DENY[Access Denied]
    AUTH -->|Yes| STAFF{Superuser or<br/>Staff?}
    STAFF -->|Yes| ALLOW[Access Granted]
    STAFF -->|No| ROLE{Direct Role<br/>Permission?}
    ROLE -->|Yes| ALLOW
    ROLE -->|No| ACL{Object-Level<br/>ACL Permission?}
    ACL -->|Yes| ALLOW
    ACL -->|No| INH{Inherited<br/>Permission?}
    INH -->|Yes| ALLOW
    INH -->|No| DENY

来源：mayan/apps/acls/managers.py:268-295, mayan/apps/acls/managers.py:233-267

基于角色的访问控制

角色模型与关系

Role 模型作为核心授权单元，包含组（组织单元）和权限。

graph TB
    subgraph "系统级权限"
        R[Role] --> SP[StoredPermission]
        R --> G[Group]
        G --> U[User]
    end

    subgraph "对象级权限"
        R --> ACL[AccessControlList]
        ACL --> OBJ[Object]
        ACL --> SP2[StoredPermission]
    end

    subgraph "权限授予方法"
        R --> GM[".grant()"]
        R --> RM[".revoke()"]
        R --> GAM[".groups_add()"]
        R --> GRM[".groups_remove()"]
    end

角色可以通过两种方式授予权限：

系统级：直接为角色分配权限，影响所有对象
对象特定：通过针对单个对象的 ACL 条目

来源：mayan/apps/permissions/models.py:23-140

权限继承

ACL 系统支持权限继承，子对象可以通过外键关系从父对象继承权限。

graph TB
    DOC[Document] --> DF[DocumentFile]
    DOC --> DV[DocumentVersion]
    DV --> DP[DocumentPage]

    subgraph "ACL 继承"
        ACLDOC[ACL for Document] --> INHERITS[".register_inheritance()"]
        INHERITS --> ACLDF[Inherited by DocumentFile]
        INHERITS --> ACLDV[Inherited by DocumentVersion]
        ACLDV --> ACLPAGE[Inherited by DocumentPage]
    end

    subgraph "权限解析"
        USER[User Permission Check] --> DIRECT[Direct ACL]
        USER --> PARENT[Parent ACL]
        USER --> GRANDPARENT[Grandparent ACL]
    end

来源：mayan/apps/acls/classes.py:193-203, mayan/apps/acls/managers.py:296-357

Web 界面与管理

角色管理视图

角色管理界面提供对角色的增删改查操作，以及角色与组和权限的关联管理。

graph LR
    subgraph "角色视图"
        RLV[RoleListView] --> RCV[RoleCreateView]
        RCV --> REV[RoleEditView]
        REV --> RDV[RoleDeleteView]
    end

    subgraph "角色关联视图"
        RGAV[RoleGroupAddRemoveView] --> GAU[Groups Management]
        RPAV[RolePermissionAddRemoveView] --> PAU[Permissions Management]
    end

    subgraph "URL 模式"
        RLV --> URL1["/roles/"]
        RCV --> URL2["/roles/create/"]
        RGAV --> URL3["/roles/{id}/groups/"]
        RPAV --> URL4["/roles/{id}/permissions/"]
    end

来源：mayan/apps/permissions/views.py:50-211, mayan/apps/permissions/urls.py:16-52

ACL 管理视图

ACL 界面允许创建和管理对象特定的访问控制条目。

graph LR
    subgraph "ACL 视图"
        ACLCV[ACLCreateView] --> ACLLV[ACLListView]
        ACLLV --> ACLDV[ACLDeleteView]
        ACLLV --> ACLPV[ACLPermissionAddRemoveView]
    end

    subgraph "URL 结构"
        ACLCV --> URL1["/apps/{app}/{model}/objects/{id}/acls/create/"]
        ACLLV --> URL2["/apps/{app}/{model}/objects/{id}/acls/"]
        ACLPV --> URL3["/acls/{acl_id}/permissions/"]
    end

    subgraph "外部对象集成"
        EOV[ExternalObjectViewMixin] --> CTVM[ContentTypeViewMixin]
        CTVM --> GETOBJ["get_external_object()"]
    end

来源：mayan/apps/acls/views.py:30-278, mayan/apps/acls/urls.py:13-34

REST 接口集成

API 视图结构

权限和 ACL 系统提供了全面的 REST API，用于程序化访问管理。

graph TB
    subgraph "权限 API"
        PALV[APIPermissionList] --> GET1["/api/permissions/"]
        RAPI[Role API Views] --> CRUD1["CRUD Operations"]
    end

    subgraph "ACL API"
        ACLAPI[ACL API Views] --> EXTOBJ[ExternalContentTypeObjectAPIViewMixin]
        EXTOBJ --> APIURL["/api/objects/{app}/{model}/{id}/acls/"]
    end

    subgraph "序列化器"
        RSER[RoleSerializer] --> PSER[PermissionSerializer]
        ACLSER[ACLSerializer] --> CTSER[ContentTypeSerializer]
    end

    subgraph "权限检查"
        APIURL --> PERMS["mayan_external_object_permissions"]
        PERMS --> ACLVIEW["permission_acl_view"]
        PERMS --> ACLEDIT["permission_acl_edit"]
    end

来源：mayan/apps/permissions/api_views.py:21-178, mayan/apps/acls/api_views.py:16-169, mayan/apps/acls/urls.py:36-64

与文档系统的集成

文档权限模型

文档系统广泛使用 ACL 框架来控制对文档、文档类型、文件和版本的访问。

graph TB
    subgraph "文档模型"
        DT[DocumentType] --> DOC[Document]
        DOC --> DF[DocumentFile]
        DF --> DV[DocumentVersion]
        DV --> DP[DocumentPage]
    end

    subgraph "权限注册"
        MP[ModelPermission.register] --> DTPERMS[DocumentType Permissions]
        MP --> DOCPERMS[Document Permissions]
        MP --> DFPERMS[DocumentFile Permissions]
    end

    subgraph "继承链"
        DTACL[DocumentType ACL] --> DOCACL[Document ACL]
        DOCACL --> DFACL[DocumentFile ACL]
        DFACL --> DVACL[DocumentVersion ACL]
    end

    subgraph "访问模式"
        USER[User Request] --> ACLCHECK[ACL Check]
        ACLCHECK --> FILTER[Queryset Filtering]
        FILTER --> RESULT[Accessible Objects]
    end

系统使用 register_inheritance() 确保在文档类型或文档级别授予的权限会自动应用于包含的文件、版本和页面。

来源：mayan/apps/acls/classes.py:126-187, mayan/apps/acls/managers.py:31-231