2.3 · 仪表盘与设置（Dashboard and Settings）

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

项目Paperless-ngx 章节2.3 状态全文译文模块系统架构、界面与交互、配置治理、接口与服务契约

项目要点页2.5 参考项目项目章节目录Paperless-ngx DeepWiki 原始章节Dashboard and Settings 上一章2.2 下一章3

源码线索

.dockerignore
src-ui/src/app/app-routing.module.ts
src-ui/src/app/app.component.html
src-ui/src/app/app.component.ts
src-ui/src/app/components/dashboard/dashboard.component.html
src-ui/src/app/components/dashboard/dashboard.component.ts
src-ui/src/app/components/dashboard/widgets/welcome-widget/welcome-widget.component.html
src-ui/src/app/components/dashboard/widgets/welcome-widget/welcome-widget.component.ts
src-ui/src/environments/environment.prod.ts
src-ui/src/environments/environment.ts

模块标签

系统架构
界面与交互
配置治理
接口与服务契约
文档对象与元数据

章节正文

仪表盘与设置

原始 DeepWiki 页面https://deepwiki.com/paperless-ngx/paperless-ngx/2.3-dashboard-and-settings

仪表盘与设置

仪表盘总览

仪表盘是应用的着陆页面，设计为响应式小部件网格。它提供系统活动的概览，并通过已保存视图快速访问文档。

仪表盘架构

仪表盘由 DashboardComponent 管理，该组件作为各种专用小部件的容器。

Paperless-ngx · 仪表盘架构 · 图 1

来源：src-ui/src/app/components/dashboard/dashboard.component.ts:26-44, src-ui/src/app/components/dashboard/dashboard.component.html:1-67

仪表盘小部件

小部件	组件	用途	数据源
欢迎	`WelcomeWidgetComponent`	新用户引导。	`SettingsService.offerTour()`
上传	`UploadFileWidgetComponent`	手动文件上传及处理状态。	`UploadDocumentsService` 和 `WebsocketStatusService`
已保存视图	`SavedViewWidgetComponent`	显示文档的过滤列表。	`DocumentService.listFiltered()`
统计信息	`StatisticsWidgetComponent`	高级文档计数。	后端统计 API

来源：src-ui/src/app/components/dashboard/dashboard.component.html:32-64, src-ui/src/app/components/dashboard/widgets/upload-file-widget/upload-file-widget.component.ts:39-43

拖放实现

用户可以在仪表盘上重新排序 SavedViewWidgetComponent 实例。这是通过 Angular CDK 的 DragDropModule 实现的。当发生拖放操作时，DashboardComponent.onDrop() 函数会更新本地数组，并通过 SettingsService.updateDashboardViewsSort() 持久化新顺序。

来源：src-ui/src/app/components/dashboard/dashboard.component.ts:83-100, src-ui/src/app/components/dashboard/dashboard.component.html:7-11

上传与消费状态

UploadFileWidgetComponent 负责处理上传的发起和实时处理状态的显示。

实时状态流程

该小部件订阅 WebsocketStatusService，以接收来自 Django 后端关于文档消费的更新。

Paperless-ngx · 实时状态流程 · 图 2

来源：src-ui/src/app/components/dashboard/widgets/upload-file-widget/upload-file-widget.component.ts:46-48, src-ui/src/app/components/dashboard/widgets/upload-file-widget/upload-file-widget.component.html:46-66

设置与配置

设置组件（SettingsComponent）允许用户自定义其 UI 体验。设置会按用户持久化存储在数据库中。

主要设置类别

通用： 语言、日期格式和主题（深色模式）。
外观： 窄侧边栏开关和主题颜色。
全局搜索： 高级搜索与仅数据库搜索。
已保存视图： 管理现有视图。

来源：src-ui/src/app/components/admin/settings/settings.component.html:41-158

UI 设置的实现

SettingsService 管理这些配置的状态。它使用 SETTINGS_KEYS 将 UI 组件映射到后端偏好设置。例如，darkModeEnabled 会与 SETTINGS_KEYS.DARK_MODE_ENABLED 进行比对。

来源：src-ui/src/app/data/ui-settings.ts:1-50, src-ui/src/app/services/settings.service.ts:1-100

管理页面

Paperless-ngx 包含用于监控系统的管理界面，与 Django 管理后台不同。

任务管理

TasksComponent 提供用于监控 Celery 任务的 UI。它将任务分类为"需要关注"、"进行中"和"已完成"。

数据源： TasksService 从 /api/tasks/ 端点获取数据。
操作： 用户可以关闭已完成的任务或重试失败的任务。
过滤： 支持按 PaperlessTaskType（例如 ConsumeFile、TrainClassifier、SanityCheck）进行过滤。

来源：src-ui/src/app/components/admin/tasks/tasks.component.ts:36-102, src-ui/src/app/services/tasks.service.ts:69-86

日志与系统状态

日志： LogsComponent 允许通过 LogService 直接在浏览器中查看后端日志（例如 paperless.log、mail.log）。
系统状态： 设置中的"系统状态"模态框会检查数据库、Redis 和 Celery 工作进程的健康状况。

来源：src-ui/src/app/components/admin/logs/logs.component.ts:1-50, src-ui/src/app/components/admin/settings/settings.component.html:10-29

权限与用户管理

权限系统使用 django-guardian 实现对象级访问控制。

权限类型

前端使用 PermissionType 枚举来控制 UI 元素的显示：

Document：访问查看/编辑文档的权限。
SavedView：访问仪表盘视图的权限。
PaperlessTask：访问任务管理页面的权限。
UISettings：访问设置页面的权限。

来源：src-ui/src/app/services/permissions.service.ts:10-35

代码实现

后端的 PaperlessObjectPermissions 类会覆盖标准的 Django 权限，以检查 owner 字段。如果文档有所有者，则只有该用户（或超级用户）可以访问它，除非授予了特定的对象级权限。

class PaperlessObjectPermissions(DjangoObjectPermissions):
    def has_object_permission(self, request, view, obj):
        if hasattr(obj, "owner") and obj.owner is not None:
            if request.user == obj.owner:
                return True
            else:
                return super().has_object_permission(request, view, obj)
        else:
            return True # 无所有者

来源：src/documents/permissions.py:28-51

UI 集成

在整个仪表盘和设置模板中，使用 IfPermissionsDirective（*pngxIfPermissions）根据当前用户的作用域有条件地渲染组件。

来源：src-ui/src/app/components/dashboard/dashboard.component.html:36, src-ui/src/app/components/dashboard/widgets/upload-file-widget/upload-file-widget.component.html:1