审计日志模块（专业版）

您必须拥有 ABP Team 或更高级别的许可证 才能使用此模块。

此模块实现了应用程序的审计日志系统；

• 查看系统的所有审计日志并轻松过滤。
• 查看审计日志详情、执行的操作和变更的实体。
• 查看实体的所有变更并过滤实体变更日志。
• 查看实体变更的详细信息。
• 查看实体的所有变更历史。
• 将审计日志和实体变更导出到 Excel。
• 接收导出完成或失败时的电子邮件通知。
• 此模块还定义了可复用的"日均执行时长"和"错误率"小组件。
• 审计日志的定期清理。

有关模块功能的概述，请参见 模块描述页面。

如何安装

审计日志模块已在 启动模板 中预装。因此，无需手动安装。

包

此模块遵循 模块开发最佳实践指南，由多个 NuGet 和 NPM 包组成。如果您想了解这些包及其之间的关系，请参阅该指南。

您可以访问 审计日志模块包列表页面 查看与此模块相关的包列表。

用户界面

菜单项

审计日志模块将以下项目添加到"主"菜单的"管理"菜单项下：

• 审计日志：列出、查看和过滤审计日志及实体变更。

IAbpAuditLoggingMainMenuNames 类包含了菜单项名称的常量。

页面

审计日志

审计日志选项卡用于列出、查看和过滤系统中的审计日志和实体变更。

列表中的每一行都包含审计日志的基本信息，如 HTTP 状态码、HTTP 方法、执行时间等...

审计日志详情

通过点击每个审计日志行上的放大镜图标，您可以查看审计日志的详细信息：

• 概览：此选项卡包含有关审计日志的详细信息。
• 操作：此选项卡显示在 Web 请求期间执行的操作（控制器操作和应用程序服务方法调用及其参数）列表。
• 变更：此选项卡显示在 Web 请求期间发生变更的实体。

导出到 Excel

您可以通过点击工具栏中的"导出到 Excel"按钮将审计日志导出到 Excel。如果结果集较小（小于可配置的阈值），文件将立即生成并下载。对于较大的结果集，导出将作为后台作业处理，一旦导出完成，您将收到一封包含下载链接的电子邮件。

实体变更

实体变更选项卡用于列出、查看和过滤实体变更日志。

列表中的每一行都包含实体变更日志的基本信息，如时间（变更发生时间）、变更类型等...

变更详情弹窗

通过点击实体变更日志列表中的"变更详情"操作项，您可以查看实体变更日志的详细信息：

完整变更历史弹窗

通过点击实体变更日志列表中的"完整变更历史"操作项，您可以查看实体所有变更的详细信息：

导出到 Excel

您可以通过点击工具栏中的"导出到 Excel"按钮将实体变更导出到 Excel。与审计日志导出类似，对于大型数据集，导出将作为后台作业处理，一旦完成，您将收到电子邮件通知。

审计日志设置

审计日志 设置选项卡用于配置审计日志设置。您可以在系统范围内启用或禁用清理服务。这样，您可以为所有租户和宿主关闭清理服务。如果系统范围的清理服务已启用，您可以为所有租户和宿主配置全局的 过期项删除周期。

当以这种方式从宿主端配置审计日志模块的全局设置时，请确保每个租户和宿主都使用全局值。如果您想设置特定于租户/宿主的值，可以在 设置 -> 审计日志 -> 通用 下进行。这样，您可以为特定的租户或宿主禁用清理服务。它会覆盖全局设置。

要查看审计日志设置，您需要启用该功能。对于宿主端，请导航到 设置 -> 功能管理 -> 管理宿主功能 -> 审计日志 -> 启用审计日志设置管理。对于租户端，您可以使用 租户功能 或 版本功能。

如果您没有从宿主端 设置 -> 审计日志 -> 全局 启用 系统范围的清理服务，即使存在租户特定的设置，它也不会删除过期的审计日志。

数据种子

此模块不预置任何数据。

选项

AbpAuditingOptions

AbpAuditingOptions 可在 UI 层的 模块 的 ConfigureServices 方法中配置。示例：

Configure<AbpAuditingOptions>(options =>
{
    //在此设置选项...
});

要查看 AbpAuditingOptions 的属性，请参阅其 文档。

ExpiredAuditLogDeleterOptions

ExpiredAuditLogDeleterOptions 可在 UI 层的 模块 的 ConfigureServices 方法中配置。示例：

Configure<ExpiredAuditLogDeleterOptions>(options =>
{
    options.Period = (int)TimeSpan.FromSeconds(30).TotalMilliseconds;

    // 此 Cron 表达式仅在后台工作器使用 Hangfire 或 Quartz 时有效。
    // Hangfire 的 Cron 表达式与 Quartz 的 Cron 表达式不同，请参考以下链接：
    // https://www.quartz-scheduler.net/documentation/quartz-3.x/tutorial/crontriggers.html#cron-expressions
    // https://docs.hangfire.io/en/latest/background-methods/performing-recurrent-tasks.html
    options.ExcelFileCleanupOptions.CronExpression = "0 23 * * *"; // Quartz Cron 表达式为 "0 23 * * * ?"
});

Period 并非指 过期项删除周期。它是指运行系统范围清理服务的工作器的周期。默认值为 1 天。

AuditLogExcelFileOptions

AuditLogExcelFileOptions 可在 UI 层的 模块 的 ConfigureServices 方法中配置。示例：

Configure<AuditLogExcelFileOptions>(options =>
{
    options.FileRetentionHours = 24; // 清理前保留文件的时间（默认：24 小时）
    options.DownloadBaseUrl = "https://yourdomain.com"; // 电子邮件中下载链接的基础 URL
    options.ExcelFileCleanupOptions.Period = (int)TimeSpan.FromHours(24).TotalMilliseconds; // 清理工作器的运行间隔（默认：24 小时）

    // 此 Cron 表达式仅在后台工作器使用 Hangfire 或 Quartz 时有效。
    // Hangfire 的 Cron 表达式与 Quartz 的 Cron 表达式不同，请参考以下链接：
    // https://www.quartz-scheduler.net/documentation/quartz-3.x/tutorial/crontriggers.html#cron-expressions
    // https://docs.hangfire.io/en/latest/background-methods/performing-recurrent-tasks.html
    options.ExcelFileCleanupOptions.CronExpression = "0 23 * * *"; // Quartz Cron 表达式为 "0 23 * * * ?"
});

注意：FileRetentionHours 值决定了文件何时有资格被删除，但实际的删除取决于清理工作器的运行时间。如果在保留期过期后工作器尚未运行，文件将仍然可访问。因此，FileRetentionHours 表示预期的最小保留时间，但实际保留时间可能更长，具体取决于工作器的执行计划。

这些设置控制 Excel 导出文件的存储位置、在自动清理前保留多长时间，以及在电子邮件下载链接中使用的基础 URL。

要使用此功能，您必须使用有效的 BLOB 存储提供程序。

内部结构

领域层

聚合

此模块遵循 实体最佳实践与约定 指南。

AuditLog

审计日志是与安全相关的按时间顺序记录、一组记录和/或记录的目的地和来源，提供在任何时间影响特定操作、程序或事件的活动序列的书面证据。

• AuditLog (聚合根)：代表系统中的审计日志。
  • EntityChange (集合)：审计日志中发生变更的实体。
  • AuditLogAction (集合)：审计日志中执行的操作。

仓储

此模块遵循 仓储最佳实践与约定 指南。

为此模块定义了以下自定义仓储：

• IAuditLogRepository

应用层

应用服务

• AuditLogsAppService (实现 IAuditLogsAppService)：实现审计日志管理 UI 的用例。

电子邮件模板

该模块提供用于通知的电子邮件模板：

• AuditLogExportCompleted：当审计日志导出成功完成时发送，包含下载链接。
• AuditLogExportFailed：当审计日志导出失败时发送，包含错误详情。
• EntityChangeExportCompleted：当实体变更导出成功完成时发送，包含下载链接。
• EntityChangeExportFailed：当实体变更导出失败时发送，包含错误详情。

数据库提供程序

通用

表 / 集合前缀与架构

默认情况下，所有表/集合都使用 Abp 前缀。如果需要更改表前缀或设置架构名称（如果您的数据库提供程序支持），请在 AbpAuditLoggingDbProperties 类上设置静态属性。

连接字符串

此模块使用 AbpAuditLogging 作为连接字符串名称。如果您没有定义具有此名称的连接字符串，它将回退到 Default 连接字符串。

有关详细信息，请参阅 连接字符串 文档。

Entity Framework Core

表

• AbpAuditLogs
  • AbpAuditLogActions
  • AbpEntityChanges
    • AbpEntityPropertyChanges

MongoDB

集合

• AbpAuditLogs

权限

有关为此模块定义的所有权限，请参见 AbpAuditLoggingPermissions 类的成员。

Angular UI

安装

为了将应用程序配置为使用审计日志模块，您首先需要从 @volo/abp.ng.audit-logging/config 导入 provideAuditLoggingConfig 到根配置中。然后，您需要将其附加到 appConfig 数组。

// app.config.ts
import { provideAuditLoggingConfig } from '@volo/abp.ng.audit-logging/config';

export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    provideAuditLoggingConfig(),
  ],
};

审计日志模块应在您的路由数组中导入并懒加载。它有一个用于配置的静态 createRoutes 方法。可用选项如下。可以从 @volo/abp.ng.audit-logging 导入。

// app.routes.ts
export const APP_ROUTES: Routes = [
  // ...
  {
    path: 'audit-logs',
    loadChildren: () => import('@volo/abp.ng.audit-logging').then(c => c.createRoutes(/* 此处传入选项 */)),
  },
];

如果您是通过启动模板生成的项目，则无需执行任何操作，因为它已配置好这两个文件。

选项

您可以通过向 createRoutes 静态方法传递以下选项来修改模块页面的外观和行为：

• entityActionContributors: 更改网格操作。详情请参阅 Angular 实体操作扩展。
• toolbarActionContributors: 更改页面工具栏。详情请参阅 Angular 页面工具栏扩展。
• entityPropContributors: 更改表格列。详情请参阅 Angular 数据表格列扩展。

服务 / 模型

审计日志模块的服务和模型通过 ABP CLI 的 generate-proxy 命令生成。如果您需要该模块的代理，可以在 Angular 项目目录中运行以下命令：

abp generate-proxy --module auditLogging

可替换组件

eAuditLoggingComponents 枚举提供了所有可替换组件的键。可以从 @volo/abp.ng.audit-logging 导入。

详情请查看 组件替换文档。

远程端点 URL

审计日志模块的远程端点 URL 可以在环境文件中配置。

export const environment = {
  // 其他配置
  apis: {
    default: {
      url: '此处填写默认 url',
    },
    AbpAuditLogging: {
      url: '此处填写审计日志远程 url'
    }
    // 其他 api 配置
  },
};

上面显示的审计日志模块远程 URL 配置是可选的。如果您没有设置 URL，将使用 default.url 作为备用。

分布式事件

此模块未定义任何额外的分布式事件。请参阅 标准分布式事件。