agentic_huge_data_base / wiki
页面 Paperless-ngx · 3.3 权限系统·DeepWiki 中文全文译文
DeepWiki 中文译文 / Paperless-ngx / 3.3

3.3 · 权限系统（Permissions System）

文档归档与消费管道 · 聚焦本章的模块关系、源码依据与实现要点。

项目Paperless-ngx 章节3.3 状态全文译文 模块检索、召回与索引、接口与服务契约、文档对象与元数据、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Paperless-ngx DeepWiki 原始章节Permissions System 上一章3.2 下一章4
源码线索
  • src/documents/admin.py
  • src/documents/apps.py
  • src/documents/consumer.py
  • src/documents/filters.py
  • src/documents/index.py
  • src/documents/models.py
  • src/documents/serialisers.py
  • src/documents/signals/handlers.py
  • src/documents/tests/test_api_documents.py
  • src/documents/tests/test_api_search.py
模块标签
  • 检索、召回与索引
  • 接口与服务契约
  • 文档对象与元数据
  • 测试、发布与运维
  • 系统架构

章节正文

权限系统

原始 DeepWiki 页面https://deepwiki.com/paperless-ngx/paperless-ngx/3.3-permissions-system

权限系统

相关源文件

本章引用的主要源码文件：

  • src-ui/src/app/components/admin/settings/settings.component.html
  • src-ui/src/app/components/admin/settings/settings.component.spec.ts
  • src-ui/src/app/components/admin/settings/settings.component.ts
  • src-ui/src/app/components/common/permissions-select/permissions-select.component.spec.ts
  • src-ui/src/app/data/ui-settings.ts
  • src-ui/src/app/services/permissions.service.spec.ts
  • src-ui/src/app/services/permissions.service.ts
  • src/documents/filters.py
  • src/documents/management/commands/document_fuzzy_match.py
  • src/documents/permissions.py
  • src/documents/serialisers.py
  • src/documents/tests/test_api_custom_fields.py
  • src/documents/tests/test_api_documents.py
  • src/documents/tests/test_api_filter_by_custom_fields.py
  • src/documents/tests/test_api_uisettings.py
  • src/documents/tests/test_management_fuzzy.py
  • src/documents/views.py
  • src/paperless/auth.py
  • src/paperless/migrations/0009_alter_applicationconfiguration_options.py
  • src/paperless/urls.py

Paperless-ngx 的权限系统控制对文档和其他对象的访问。它结合了基于所有者的访问控制、全局 Django 权限以及通过 django-guardian 管理的对象级权限。

概述

Paperless-ngx 实现了一个多层权限系统，与 REST API 和全文检索引擎无缝集成。

Paperless-ngx · 概述 · 图 1
Paperless-ngx · 概述 · 图 1

来源：src/documents/permissions.py:28-52, src/documents/filters.py:137-138, src-ui/src/app/services/permissions.service.ts:13-15

后端实现

对象所有权与全局权限

Paperless-ngx 中的大多数模型都继承自 ModelWithOwner（例如 Document、Tag、Correspondent），该基类提供了 owner 字段。

  • 超级用户：绕过所有权限检查，可以访问所有对象 src/documents/permissions.py:179-180。
  • 所有权：PaperlessObjectPermissions 类（扩展自 DjangoObjectPermissions）允许在 request.user == obj.owner 时进行访问 src/documents/permissions.py:44-51。
  • 员工用户：某些视图（如系统监控）要求用户具有 is_staff 属性或特定的全局权限，例如 paperless.view_system_monitoring src/documents/permissions.py:54-56, src/documents/permissions.py:68-76。
对象级权限（Guardian）

Paperless-ngx 使用 django-guardian 向特定用户或用户组授予对单个对象的访问权限。

  • view_<model>：允许查看对象。
  • change_<model>：允许编辑对象。
  • delete_<model>：允许删除对象。
过滤与混入类

为确保用户只能看到其有权查看的内容，Paperless-ngx 在其 ViewSet 中使用了自定义过滤器和混入类：

组件作用文件引用
ObjectOwnedOrGrantedPermissionsFilter过滤查询集，仅包含用户拥有或通过 Guardian 授予权限的对象。src/documents/filters.py:137-138
PaperlessObjectPermissionsREST 框架权限类，检查所有权或对象级权限。src/documents/permissions.py:28-32
SetPermissionsMixin通过 API 更新权限时，校验用户/用户组 ID。src/documents/serialisers.py:170-171
BulkPermissionMixin处理同时对多个对象设置权限。src/documents/views.py:171-171

来源：src/documents/permissions.py:28-52, src/documents/filters.py:137-138, src/documents/serialisers.py:170-186

API 数据流

当客户端请求或更新对象时，OwnedObjectSerializer 负责管理权限元数据。

Paperless-ngx · API 数据流 · 图 2
Paperless-ngx · API 数据流 · 图 2

来源：src/documents/serialisers.py:232-366, src/documents/permissions.py:93-164, src/documents/filters.py:137-138

前端：PermissionsService

Angular 前端使用 PermissionsService 来条件性地显示 UI 元素并执行客户端限制。

主要功能
  • 全局检查：isAdmin() 检查用户是否为超级用户 src-ui/src/app/services/permissions.service.ts:51-53。
  • 操作检查：currentUserCan(type, action) 检查用户是否具有全局权限（例如 PermissionType.Document + PermissionAction.Add）src-ui/src/app/services/permissions.service.ts:55-61。
  • 对象级检查：currentUserHasObjectPermissions(action, object) 检查用户是否为所有者，或者是否在对象的 permissions 数组中具有所需权限 src-ui/src/app/services/permissions.service.ts:74-90。
UI 集成

IfPermissionsDirective 和 IfOwnerDirective 在模板中用于隐藏按钮或字段：

<!-- 来自设置组件的示例 -->
@if (canViewSystemStatus) {
  <button ...>系统状态</button>
}
@if (permissionsService.isAdmin()) {
  <a href="admin/">打开 Django 管理后台</a>
}

来源：src-ui/src/app/services/permissions.service.ts:13-100, src-ui/src/app/components/admin/settings/settings.component.html:10-35

搜索中的权限逻辑

搜索结果在返回给用户之前，会在数据库层面进行限制。_permitted_document_ids(user) 函数会生成一个子查询，包含用户有权查看的文档 ID。

  • 超级用户：获取所有未删除的文档 ID src/documents/permissions.py:179-180。
  • 普通用户：结果包含 owner == user 的文档，或者 UserObjectPermission 或 GroupObjectPermission 中存在 view_document 条目的文档 src/documents/permissions.py:182-209。

来源：src/documents/permissions.py:166-210, src/documents/filters.py:242-259