版本：3.1

更新日志

v3.1.0 — 2026-08-17

本次发布范围：3.1 世代首发全量发布，所有可发布组件统一推送 3.1.0（约 60 个包，独立版本线的 Aegis.Jobs.SqlServer / Aegis.Configuration.ConfigCenter 除外）。世代内所有包版本一致，不存在混用。

新增组件

Aegis.CAP：CAP 分布式事件总线元包（DotNetCore.CAP 10.0.1），FreeSql 事务集成
Aegis.AI.Mcp：Controller 方法同时暴露 REST 与 MCP 双协议
Aegis.Scheduler / .Stub / .DolphinScheduler：调度抽象层与实现
Aegis.Audit.FreeSql：数据库审计存储（原 Aegis.Security.Audit.FreeSql 更名）

重点变更

认证：内置用户认证能力（定时任务/系统间调用/功能测试）；ESS token 校验失败降级 401、DI 重构、构造函数可见性修复
Breaking（FileManager）：移除 IStorageKeyStrategy 抽象层与 tag 参数（13 个方法签名变更），UploadFileAsync 返回 FileUploadResult
Breaking（包结构）：TemplateId / SystemSettings 的 .Abstractions 包消除，抽象类型内聚核心包
版本管控统一：TemplateId / SystemSettings / AuditValue 共 5 包从硬编码 preview 版本纳入统一管控，直接对齐 3.1.0

迁移指引：详见 Release Notes（仓库 docs/release-notes/3.1.md）的 Breaking Changes 与升级指引节。

v3.0.1-preview5 — 2026-08-17（补录）

本次发布范围：认证鉴权组件组 6 包同步升至 3.0.1-preview5 （Aegis.Authorization.ESS / Aegis.Authorization.Jwt / Aegis.Authorization.SSO / Aegis.Authorization.RedisUserManager / Aegis.Core.Authentication / Aegis.Core.Authorization），必须配套升级，否则 restore 会因依赖版本对不齐报 NU1102。

企业安全服务 ESS（Aegis.Authorization.ESS）

Fixed：AuthTokenService 构造函数可见性错误导致 ASP.NET Core 中间件激活失败（运行时无法实例化该服务，请求管道抛 InvalidOperationException），修正构造函数及相关 internal 接口的可见性声明。
Changed：IBlackTokenService / IHttpExecutor / IPublicKeyHolder 可见性声明同步调整，对业务方无感知（仍通过 DI 使用）。

迁移指引（从 3.0.1-preview4 升级）

直接升级 6 个包到 3.0.1-preview5 即可，无配置变更、无代码变更。
验证范围：应用启动后访问任意受保护接口，不再出现 AuthTokenService 激活异常。

关联：PR !98

注：包已于 2026-08-05 推送 Nexus，本条目与 Tag 为补录。

v3.0.1-preview4 — 2026-08-04

本次发布范围：认证鉴权组件组（Aegis.Core.Authentication / Aegis.Core.Authorization / Aegis.Authorization.ESS / Aegis.Authorization.Jwt / Aegis.Authorization.SSO / Aegis.Authorization.RedisUserManager）。六个包版本同步升至 3.0.1-preview4，必须配套升级，否则 restore 会因依赖版本对不齐报 NU1102。

认证核心（Aegis.Core.Authentication）

Added：新增内置用户（Builtin Users）认证能力。业务项目可通过配置声明若干固定 Token 的服务身份（UserType=Service），TokenHandler 在主认证源（ESS/JWT/SSO）之前前置短路识别。
- 适用场景：定时任务（外部调度平台 HTTP 调用）、系统间调用、功能测试——在"认证源不固定 + 调度平台能力不确定"约束下，与两者都解耦的通用方案。
- 配置节：Auth:BuiltinUsers，配置为空时零行为影响（FindByToken 永远返回 null）。
- 模型扩展：CustomUser 新增 UserType 字段（默认 User，零 breaking change；Service 标识服务/机器身份，业务代码可据此区分审计与权限）。
- 接口扩展：新增 IBuiltinUserStore 抽象，默认实现 BuiltinUserStore 启动时一次性构建 token 索引（ConcurrentDictionary），运行时只读查找。
Changed：TokenHandler 构造函数新增 IBuiltinUserStore 依赖，核心层注册默认实现，向后兼容。

鉴权核心（Aegis.Core.Authorization）

无代码变更，仅因共享 AegisAuthPatch 版本联动升至 3.0.1-preview4。

ESS / Jwt / SSO / RedisUserManager

无代码变更，仅因共享 AegisAuthPatch 版本联动升至 3.0.1-preview4，确保组内依赖版本一致。

安全语义（重要）

内置用户 ExpireAt = DateTime.MaxValue（永不过期），不触发框架任何过期逻辑。
内置用户获得全权调用，绕过 ApiAuthorizeAttribute 的细粒度授权。业务代码如需对内置用户做额外授权控制，应在 Controller 内自行校验 CurrentUser.UserType。
Token 明文存储于配置，不可撤销，轮换需改配置重启服务。建议使用高熵随机串（如 svc_ + 32 字节 base64）。

迁移指引（从 3.0.1-preview3 升级）

直接升级六个包到 3.0.1-preview4，无需改 appsettings.json，无需改业务代码。
启用内置用户（可选）：在 appsettings.json 的 Auth:BuiltinUsers:Users 下配置 { ClientId, Token, UserId, UserName }。
回滚方式：降级六个包到 3.0.1-preview3。

配置示例

{
  "Auth": {
    "EnableAuthentication": true,
    "BuiltinUsers": {
      "Users": [
        {
          "ClientId": "scheduler-dolphin",
          "Token": "svc_aB3xK9mP2qR7sT4vU1wY0zA5bC8dE2f",
          "UserId": "scheduler",
          "UserName": "海豚调度平台"
        }
      ]
    }
  }
}

关联：PR !94

v3.0.1-preview3 — 2026-08-03

本次发布范围：认证鉴权组件组（Aegis.Authorization.ESS / Aegis.Core.Authentication / Aegis.Core.Authorization）。三个包版本同步升至 3.0.1-preview3，必须配套升级，否则 restore 会因依赖版本对不齐报 NU1102。

企业安全服务 ESS（Aegis.Authorization.ESS）

Fixed：token 过期 / 损坏 / 签名错误时不再抛 CustomException 到应用层，改为返回 false，最终由 TokenHandler / ClientTokenHandler 统一返回 401。原行为下，标记 AllowAnonymous 的接口也会因带过期 token 直接抛异常而非把 UserInfo 置空。
Fixed：黑名单在线校验硬编码 dev 环境 URL（http://auth-dev.uiccloud.com/...），现改为读取 EssOption.ServerTokenEndpoint 配置项；未配置时记 Warning 跳过，不再误打 dev 环境。
Fixed：AccessTokenUtils 内部存储由 ThreadLocal<string> 改为 AsyncLocal<string>，修复 ASP.NET Core 异步管道（多次 await 切线程）下 token 上下文丢失的问题。
Changed：EssOption 新增 4 个配置项，默认值与原 ConfigInit 构造函数严格一致，无配置变更：
- AuthParamName（默认 "Authorization"）
- IsBlackListEnable（默认 false）
- IsAuthValidatorEnable（默认 false）
- ServerTokenEndpoint（默认 null，启用黑名单校验时必填）
Removed：删除内部 static 类 ConfigInit / Logger / HttpUtils，相关职责改为 DI 注入（IPublicKeyHolder / IBlackTokenService / IHttpExecutor，均为 internal 接口，不暴露给外部）。

认证核心（Aegis.Core.Authentication）

Fixed：TokenHandler 补全 "请求携带 token 但 CheckToken 返回 null" 的 401 分支。原行为下该场景会放行 user=null 进入后续管道，鉴权层无法区分"未带 token"和"token 无效"。
- 与 ApiAuthorizeAttribute 的 200 + TokenExpired(402) 语义互补：JWT 本身过期/损坏走 401（前端只能跳登录）；JWT 合法但 user 会话过期走 200+402（前端可静默刷新）。

鉴权核心（Aegis.Core.Authorization）

无代码变更，仅因共享 AegisAuthPatch 版本联动升至 3.0.1-preview3，确保 ESS 包的依赖约束可解析。

迁移指引（从 3.0.1-preview2 升级）

直接升级三个包到 3.0.1-preview3，无需改 appsettings.json，无需改业务代码。
验证范围：token 过期场景返回 401（而非 500）；AllowAnonymous 端点带过期 token 正常通过且 UserInfo 为 null。
回滚方式：降级三个包到 3.0.1-preview2。
已知行为差异：若业务侧此前写了 try { ... } catch (CustomException) { 处理 token 错误 } 来兜 ESS 异常，新版本下该 catch 永远不会触发，需改为统一的 401 响应处理。

关联：PR !93

v3.0.1 — 2026-06-15

本次发布范围：仅文件管理组件（Aegis.FileManager / S3 / Nas）。其他组件（Core、Audit、Config 等）保持各自 preview 状态，将在后续版本统一发布。本次版本汇总自 v3.0.0 之后所有 FileManager 相关的累积变更。

文件管理（Aegis.FileManager）

Breaking：移除 IStorageKeyStrategy 抽象层及全部内置策略（PassthroughKeyStrategy / HashPrefixKeyStrategy / DatePrefixKeyStrategy）、StorageKeyStrategyType 枚举、DateKeyGranularity 枚举
Breaking：IFileManager 接口所有方法移除 string? tag 参数（共 13 个方法签名变更）
Breaking：UploadFileAsync 返回类型由 bool 改为 FileUploadResult（preview1 引入）
新增 FileUploadResult 模型类，包含 Success、ObjectKey、FileName、GroupName
StorageKey 的生成职责完全交还给业务侧，框架对 fileName 原样使用作为 StorageKey

S3 对象存储（Aegis.FileManager.S3）

删除 S3FileManagerBuilder（连同 UseCustomStorageKeyStrategy<T>() 方法）
S3Options 移除 StorageKeyStrategy 和 StorageKeyStrategyConfig 配置项
S3FileManager 构造函数移除策略参数
SignatureVersion 配置化（默认 V4，避免 us-east-1 region 默认降级 SigV2 导致 Ceph/OSS 后端拒绝）
Presigned URL 的 scheme 跟随 Endpoint 配置（http 端点生成 http URL）
Endpoint 配置原样使用，不再自动清理（保留路径前缀以支持反向代理转发）
支持自部署 S3 兼容服务（MinIO、Ceph、阿里云 OSS、UMeta、APISIX 反向代理）

NAS 本地存储（Aegis.FileManager.Nas）

删除 ResolveStrategy 工厂方法
NasOptions 移除 StorageKeyStrategy 和 StorageKeyStrategyConfig 配置项
NasFileManager 构造函数移除策略参数
适配 FileUploadResult 返回值

文档

导航重构：「文件系统」从「文档与文件」中拆为二级子分类，包含「文件管理（入口）/ S3 / NAS」三个文档
抽象层文档重写：从接口参考改为业务侧教学入口，聚焦医疗 EMR 场景
新增 EMR 病历场景完整示例：5 段式 ObjectKey 范式（{2位哈希}/{yyyymm}/{patientId}/{date}_{docNum}.{ext}）+ EmrKeyBuilder 工具类 + 业务调用代码
文档版本号同步至 3.0.1

设计动机

StorageKey 的生成属于业务领域关注点。Aegis 文件系统主要服务医疗行业，医疗行业内部不同业务（病历文书、检验报告、影像、CA 签名、归档等）对文件 Key 的需求各不相同，结构化抽象无法覆盖，反而成为诱导踩坑的陷阱代码（HashPrefix 哈希源错——业务要按患者ID 哈希而非文件名； DatePrefix 时间源错——业务要按业务归属月份而非上传时刻）。删除抽象后，业务侧自行拼装 Key，框架原样使用，职责清晰。

迁移指引（从 v3.0.0 升级）

业务侧封装静态工具类（如 EmrKeyBuilder）按业务规则拼装完整 Key
框架对 IFileManager 的 fileName 参数原样使用作为 StorageKey（含 / 或 \ 的路径完整保留）
上传时拼好的 Key 传入，将 FileUploadResult.ObjectKey 持久化到业务表（如 medical_record.s3_key）
后续读取、删除、列举直接用同一 Key（行为完全对称）
删除 appsettings.json 中 S3Storage.StorageKeyStrategy 和 S3Storage.StorageKeyStrategyConfig 配置项（不再使用）
删除代码中 .UseCustomStorageKeyStrategy<T>() 链式调用（如使用过）
调用 IFileManager 各方法时移除 tag: 命名参数
参考完整示例：文件管理 — 核心概念：业务自拼 Key 中的 EMR 病历案例

v3.0.1-preview1 — 2026-06-03

文件管理组件（Aegis.FileManager）

IFileManager.UploadFileAsync 返回类型由 bool 改为 FileUploadResult（Breaking Change）
新增 FileUploadResult 模型类，包含 Success、ObjectKey、FileName、GroupName

S3 文件存储（Aegis.FileManager.S3）

新增 ObjectKey 管理策略：PassthroughKeyStrategy（默认）、HashPrefixKeyStrategy（哈希前缀打散）、DatePrefixKeyStrategy（日期前缀，可选日/周/月/年粒度）
新增 IObjectKeyStrategy 扩展接口，支持自定义策略
新增约定规则：fileName 含 / 时视为完整 ObjectKey，否则由策略生成
新增 S3Options.KeyStrategy 配置项
Aegis.FileManager.S3 首次发布至 Nexus（补齐 PackageId 和版本号）

NAS 文件存储（Aegis.FileManager.Nas）

适配 FileUploadResult 返回值

v3.0.0 — 2026-05-12

全量发布所有可发布组件至公司 Nexus 私服
运行时升级：.NET 6 → .NET 8
认证鉴权拆分为 Aegis.Core.Authentication + Aegis.Core.Authorization，新增 Aegis.Authorization.ESS
新增 Aegis.Net.SignalR、Aegis.Security.Audit、Aegis.Security.Encryption、Aegis.Prometheus、Aegis.Trace.OpenTelemetry、Aegis.DocumentConverter、Aegis.Component
RedisSource 整合 RedisClient（后者将在 3.1 移除）
BrokerClient 支持自动 X-Request-Id 头与 WebService 调用
命名修正（Breaking）：CustomeUser → CustomUser、FaliedResult → FailedResult

v3.1.0 — 2026-08-17​

v3.0.1-preview5 — 2026-08-17（补录）​

v3.0.1-preview4 — 2026-08-04​

v3.0.1-preview3 — 2026-08-03​

v3.0.1 — 2026-06-15​

v3.0.1-preview1 — 2026-06-03​

v3.0.0 — 2026-05-12​