Euonia.Auditing
2026.5.0
dotnet add package Euonia.Auditing --version 2026.5.0
NuGet\Install-Package Euonia.Auditing -Version 2026.5.0
<PackageReference Include="Euonia.Auditing" Version="2026.5.0" />
<PackageVersion Include="Euonia.Auditing" Version="2026.5.0" />
<PackageReference Include="Euonia.Auditing" />
paket add Euonia.Auditing --version 2026.5.0
#r "nuget: Euonia.Auditing, 2026.5.0"
#:package Euonia.Auditing@2026.5.0
#addin nuget:?package=Euonia.Auditing&version=2026.5.0
#tool nuget:?package=Euonia.Auditing&version=2026.5.0
Euonia.Auditing
Euonia 的审计内核:作用域/动作模型、记录契约、异步写入队列、脱敏序列化与 InMemory 存储;持久化由 EF Core / Mongo 适配包提供。
- 目标框架:
net10.0、net11.0 - 根命名空间:
Nerosoft.Euonia.Auditing - NuGet 包:
Euonia.Auditing
安装
dotnet add package Euonia.Auditing
持久化适配另装 Euonia.Auditing.EfCore 或 Euonia.Auditing.Mongo;HTTP 中间件在 Euonia.Hosting。
快速开始
using Nerosoft.Euonia.Auditing;
builder.Services.AddAuditing(options =>
{
options.Enabled = true;
options.ApplicationName = "Orders";
})
.AddInMemoryAuditingStore(); // 生产环境替换为 EF / Mongo 适配
HTTP 管道(审计必须在租户之前):
using Nerosoft.Euonia.Hosting;
app.UseAuditing();
app.UseTenancy();
核心类型
审计内核的核心契约与类型:
| 类型 | 说明 |
|---|---|
IAuditingRecorder |
EnsureScope / CreateScope / SubmitAsync / FlushAsync |
IAuditingScope |
一个执行作用域;BeginAction / CompleteAsync / AbortAsync |
IAuditingAction |
设置参数 / 扩展属性,Complete / Fail |
IAuditingWriter |
写入队列;失败开放 |
IAuditingStore |
持久化契约;同 ScopeId 幂等 |
IAuditingStoreQuery |
查询、按 ScopeId 查找、按时间清理 |
IAuditingStoreRouter |
按记录选择存储(每租户审计库) |
AuditingRecord / AuditingAction |
作用域记录与动作 |
AuditingScopeOptions |
作用域的操作键、幂等键与 HTTP 元数据 |
AuditedAttribute |
标记必须审计的方法或类型 |
AuditingOptions |
全局选项(见「配置项」) |
使用示例
1. EF Core 存储 + 文件暂存
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Nerosoft.Euonia.Auditing;
using Nerosoft.Euonia.Auditing.EfCore;
services.AddAuditing(options =>
{
options.Enabled = true;
options.ApplicationName = "Orders";
options.SuccessDelivery = AuditingDelivery.Batched;
})
.AddFileAuditingSpool(Path.Combine(AppContext.BaseDirectory, "audit-spool"))
.AddAuditingEfCore<AuditingDbContext>(options =>
options.UseSqlServer(configuration.GetConnectionString("Audit")));
2. 标注应用服务
using Nerosoft.Euonia.Auditing;
public sealed class OrderAppService
{
[Audited(ActionName = "创建订单")]
public Task<long> CreateAsync(CreateOrderCommand command, CancellationToken cancellationToken)
{
// 方法体
return Task.FromResult(0L);
}
}
[Audited]由Euonia.Application的AuditingInterceptor拦截;即使全局Enabled为false,标注的方法仍会记录。
3. 手动作用域
using Nerosoft.Euonia.Auditing;
public sealed class ImportJob(IAuditingRecorder recorder)
{
public async Task RunAsync(CancellationToken cancellationToken)
{
var scope = recorder.CreateScope(new AuditingScopeOptions
{
OperationKey = $"job:{Guid.NewGuid():N}",
AutoComplete = false
});
var action = scope.BeginAction("OrderImport", nameof(RunAsync), "导入订单");
try
{
// 业务逻辑
action.Complete(result: null);
await scope.CompleteAsync(cancellationToken);
}
catch (Exception exception)
{
action.Fail(exception);
await scope.AbortAsync(exception, cancellationToken);
throw;
}
}
}
4. 查询失败记录
using Nerosoft.Euonia.Auditing;
public sealed class AuditQueryService(IAuditingStoreQuery store)
{
public Task<IReadOnlyList<AuditingRecord>> QueryFailedAsync(CancellationToken cancellationToken)
=> store.QueryAsync(new AuditingQuery { IsSuccess = false, Take = 100 }, cancellationToken);
}
配置项
AddAuditing 在 IConfiguration 已注册时绑定 Euonia:Auditing;传入的 configure 委托在绑定之后执行,优先级更高。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
Enabled |
bool |
false |
是否启用审计 |
ApplicationName |
string? |
null |
写入记录的应用名称 |
CrossTenantQueryAuthorizer |
Func<AuditingQuery, bool>? |
null |
跨租户查询授权;仅代码配置,null 表示拒绝所有跨租户查询 |
RecordAnonymous |
bool |
false |
是否记录匿名成功调用 |
RecordParameters |
bool |
true |
是否记录动作参数(写入前脱敏) |
RecordStackTrace |
bool |
false |
是否记录异常堆栈 |
RecordResult |
bool |
true |
是否记录返回值(写入前脱敏) |
Mode |
AuditingTriggerMode |
All |
All 记录全部;WritesOnly 跳过读前缀方法 |
MaxDepth |
int |
8 |
脱敏递归深度上限 |
SuccessDelivery |
AuditingDelivery |
Batched |
成功记录投递方式 |
FailureDelivery |
AuditingDelivery |
Immediate |
失败记录投递方式 |
BatchSize |
int |
50 |
批大小(最小按 1 处理) |
BatchInterval |
TimeSpan |
00:00:02 |
批刷写间隔;非正值回退为 1 秒 |
WriteRetryCount |
int |
1 |
写入失败重试次数(不含首次) |
QueueCapacity |
int |
0 |
写入队列容量;0 表示无界 |
{
"Euonia": {
"Auditing": {
"Enabled": true,
"ApplicationName": "Orders",
"Mode": "WritesOnly",
"SuccessDelivery": "Batched",
"FailureDelivery": "Immediate"
}
}
}
Euonia__Auditing__Enabled=true # .NET 原生:双下划线表示层级
EUONIA_AUDITING_ENABLED=true # 仓库 alias:大写单下划线
语义与保证
ScopeId={actorTenantId ?? "-"}:{opKey};HTTP 使用req:{Guid},消息使用msg:{MessageId}。超过 256 字符时截断并追加 SHA-256 前缀,保持唯一性。- 审计失败开放:写入异常只记录日志,不改变业务结果。
- 参数与结果在序列化前经
SensitiveDataMasker脱敏;异常消息也会截断并遮蔽凭据片段。 IsSuccess为null表示未知(未封口动作);IAuditingStore实现必须按ScopeId幂等。- 写入队列满时丢弃当前记录并计入
euonia.auditing.records.dropped;写入器已停止时计入euonia.auditing.records.rejected。 - 注册
IAuditingSpool后,记录先落暂存再入队;落库成功后删除,进程崩溃后启动时重放。 AddAuditing幂等:重复调用不会重复注册IHostedService,但选项配置仍会生效。- 未安装租户能力时租户字段为空,不影响审计可用性。
注意事项 / 限制
AddAuditing不注册IAuditingStore;必须再注册一个IAuditingStore(AddInMemoryAuditingStore、AddAuditingEfCore或AddAuditingMongo),否则记录会被丢弃并输出警告。AddInMemoryAuditingStore是进程内存储,重启即丢失,只适合测试与本地开发;生产环境使用 EF Core / Mongo 适配。UseAuditing()来自Euonia.Hosting,必须位于UseTenancy()之前(外层);否则租户中间件释放后无法回填租户字段。- 写入器、记录器在构造时读取
AuditingOptions;运行期修改选项不会重新配置队列容量、批大小或投递方式,需重启宿主。 AddFileAuditingSpool会在调用方线程执行一次文件写入 I/O;对延迟敏感的路径应关闭 spool 或换低延迟后端。IAuditingStore实现不得依赖调用方的请求作用域;写入器每批创建自己的 DI 作用域,后台写入没有 HTTP 上下文。AddAuditing只有在IServiceCollection中已存在IConfiguration时才绑定配置节;纯手工构造的容器需要自行Configure<AuditingOptions>。CrossTenantQueryAuthorizer无法通过 JSON 配置,只能代码赋值;未设置时跨租户查询一律拒绝。
相关包
Euonia.Auditing.EfCore—— EF Core 存储Euonia.Auditing.Mongo—— MongoDB 存储Euonia.Hosting——UseAuditing()中间件Euonia.Application——[Audited]拦截器Euonia.Tenancy—— 租户字段来源Euonia.Core—— 基础类型
常见问题与故障排查
已启用审计,但存储里没有记录
依次检查:Euonia:Auditing:Enabled 是否为 true;是否注册了 IAuditingStore(AddInMemoryAuditingStore、AddAuditingEfCore 或 AddAuditingMongo);HTTP 请求是否经过 UseAuditing();Mode=WritesOnly 时读方法是否被跳过;匿名调用是否被 RecordAnonymous=false 过滤。若记录已入队,测试或停机前还需 IAuditingRecorder.FlushAsync()。
InMemory 存储的 Records 一直为空
默认 SuccessDelivery=Batched、BatchInterval=2s,写入器在后台按批落库;请求返回时记录可能仍在队列里。测试中先调用 IAuditingRecorder.FlushAsync() 再断言 InMemoryAuditingStore.Records(仓库的 HTTP 管道测试即采用该做法)。
同一 ScopeId 重复保存会不会产生重复行
IAuditingStore 契约要求按 ScopeId 幂等:InMemory 存储按键合并动作,EF Core 存储用 scope_id 唯一索引并在冲突时合并终态与动作。自定义存储必须自行实现同样的幂等语义,否则重放或重试会产生重复行。
接口返回 200,但审计记录是失败或没有异常堆栈
审计失败开放:存储异常只记日志,不影响业务结果,所以 200 不代表审计一定成功。端点内显式调用 AbortAsync 或动作 Fail 时,记录会保持 IsSuccess=false,即使 HTTP 状态是 200;异常堆栈默认不记录,需设置 RecordStackTrace=true。
跨租户查询被拒绝
查询其他租户必须同时设置 AllowCrossTenant=true 和 CrossTenantReason,并由宿主通过 CrossTenantQueryAuthorizer 显式放行;没有租户上下文(后台任务)时也必须声明跨租户与原因。默认 null 授权器拒绝所有跨租户查询。
最佳实践
- 生产环境使用 EF Core / Mongo 存储,并按需叠加
AddFileAuditingSpool;AddInMemoryAuditingStore只用于测试与本地开发。 - 成功记录保持
SuccessDelivery=Batched,失败记录使用FailureDelivery=Immediate;有界QueueCapacity配合euonia.auditing.records.dropped/.rejected指标观察丢弃。 - 管道顺序固定为
UseAuditing()在UseTenancy()之前;合规要求的方法用[Audited]强制记录,不依赖全局开关。 - 测试与停机时调用
FlushAsync()排空队列;环境差异用Euonia__Auditing__Enabled=true或EUONIA_AUDITING_ENABLED=true覆盖。
版本与兼容
- 目标框架:
net10.0、net11.0(Source/common.props)。 - 关键依赖:
Euonia.Core与Microsoft.Extensions.*抽象包;EF Core / Mongo 适配分别由Euonia.Auditing.EfCore、Euonia.Auditing.Mongo提供,包版本由仓库构建属性决定。 - 已知边界:写入器与记录器在构造时读取
AuditingOptions,运行期修改需重启;未注册IAuditingStore时记录会被丢弃;CrossTenantQueryAuthorizer只能代码配置。
许可证
本项目依据仓库根目录的 GNU General Public License v3.0 发布。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Euonia.Core (>= 2026.5.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 11.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 11.0.0)
- Microsoft.Extensions.Options (>= 11.0.0)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 11.0.0)
-
net11.0
- Euonia.Core (>= 2026.5.0)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 11.0.0)
NuGet packages (5)
Showing the top 5 NuGet packages that depend on Euonia.Auditing:
| Package | Downloads |
|---|---|
|
Euonia.Bus
Euonia 消息总线引擎:处理器发现与注册、约定与传输策略分发、Publish/Send/Call API、中间件管道、序列化、Outbox/Inbox 可靠性及 OpenTelemetry 遥测。 / Message bus engine for Euonia: handler discovery and registration, convention and transport-strategy dispatch, publish/send/call APIs, middleware pipelines, serialization, outbox/inbox reliability and OpenTelemetry instrumentation. |
|
|
Euonia.Hosting
Euonia 的 ASP.NET Core 托管基础设施:主机启动引导、异常与请求追踪中间件、JWT/内省认证、授权策略与用户主体访问器。 / ASP.NET Core hosting infrastructure for Euonia: host bootstrap, exception and request-trace middleware, JWT/introspection authentication, authorization policies and user principal accessors. |
|
|
Euonia.Application
Euonia 应用层:用例、应用服务基类、Castle 拦截器,以及用于日志、校验、授权、追踪和工作单元的管道行为。 / Application layer for Euonia: use cases, application service base classes, Castle-based interceptors and message pipeline behaviors for logging, validation, authorization, tracing and unit of work. |
|
|
Euonia.Auditing.EfCore
Euonia 审计的 EF Core 存储适配:独立审计库、幂等落库、动作去重与索引约定。 / EF Core persistence adapter for Euonia auditing: isolated audit database, idempotent upserts, action deduplication and index conventions. |
|
|
Euonia.Auditing.Mongo
Euonia 审计的 MongoDB 存储适配:按作用域幂等、动作键去重与唯一索引。 / MongoDB persistence adapter for Euonia auditing: scope idempotency, action deduplication and unique indexes. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2026.5.0 | 158 | 11/13/2026 |