# Aegis 框架文档

> Aegis 是 DezhenTech 的 .NET 分布式系统与 Web API 开发框架。本文件是全部使用手册与开发规范的 AI 入口索引（llmstxt.org 约定），随站点每次发布自动重建。当前对应 Aegis 3.1。

AI 助手使用说明：
- 使用前先确认项目 Aegis 包大版本（csproj / Directory.Packages.props）与本索引一致，不一致时改用「版本」分组中的对应入口
- 本文件结构：「版本」→「按任务找文档」速查 → 按目录分组的全量索引；每条目附一句话描述与章节目录，可不抓取先判断相关性
- 按索引按需抓取单篇原文，/md/ 路径均为 Markdown 直链；单篇手册多在 20KB 以内，可整篇读入
- 离线全量文档：https://doc.dezhentech.com/llms-full.txt（约 1MB，请按需检索，不要整篇读入）
- 业务项目接入：将本文件 URL 写入项目的 AGENTS.md / CLAUDE.md / .cursorrules
- 人类可读的接入说明（含各 AI 工具配置方式表）：https://doc.dezhentech.com/llms

## 版本

- 3.1（本索引，最新）
- 2.2.0（旧版文档，仅 HTML 无 md 镜像）：http://doc.dezhentech.com/2.2.0/home

## 按任务找文档

- 新建 Aegis 项目 / 接入框架：[快速开始](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B.md)、[Startup](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Startup.md)、[配置](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E9%85%8D%E7%BD%AE.md)、[初始系统验证清单](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%88%9D%E5%A7%8B%E7%B3%BB%E7%BB%9F%E9%AA%8C%E8%AF%81%E6%B8%85%E5%8D%95.md)
- 实现业务接口（分层怎么写）：[Controller](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Controller.md)、[Services 与 Contract](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Services%E4%B8%8EContract.md)、[Dto 数据传输层](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Dto%E6%95%B0%E6%8D%AE%E4%BC%A0%E8%BE%93%E5%B1%82.md)、[Repository 层](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Repository%E5%B1%82.md)、[事务与工作单元](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E4%BA%8B%E5%8A%A1.md)
- 入参校验与统一响应：[请求参数验证](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E8%AF%B7%E6%B1%82%E5%8F%82%E6%95%B0%E9%AA%8C%E8%AF%81.md)、[请求参数验证](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/FluentValidation%E9%AA%8C%E8%AF%81%E5%99%A8.md)、[Controller](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Controller.md)
- 前端对接（分页 / 长整型精度）：[分页与列表数据](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%88%86%E9%A1%B5%E4%B8%8E%E5%88%97%E8%A1%A8%E6%95%B0%E6%8D%AE.md)、[ID生成器](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/ID%E7%94%9F%E6%88%90%E5%99%A8.md)、[Dto 数据传输层](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Dto%E6%95%B0%E6%8D%AE%E4%BC%A0%E8%BE%93%E5%B1%82.md)
- 认证与鉴权：[认证和鉴权体系](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E8%AE%A4%E8%AF%81%E5%92%8C%E9%89%B4%E6%9D%83%E4%BD%93%E7%B3%BB.md)、[JWT 认证（Aegis.Authorization.Jwt）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%AE%A4%E8%AF%81%E4%B8%8E%E9%89%B4%E6%9D%83/Aegis.Authorization.Jwt.md)
- 排查问题 / 观测：[日志](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E6%97%A5%E5%BF%97.md)、[请求日志](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E8%AF%B7%E6%B1%82%E6%97%A5%E5%BF%97.md)、[OpenTelemetry 链路追踪](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/OpenTelemetry.md)、[问题反馈](https://doc.dezhentech.com/md/%E9%97%AE%E9%A2%98%E5%8F%8D%E9%A6%88.md)
- 部署上线：[Linux 应用部署](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/Linux%E9%83%A8%E7%BD%B2.md)、[Windows 应用部署](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/windows-app-deploy.md)、[IIS 应用程序池配置](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/IIS%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F%E6%B1%A0%E9%85%8D%E7%BD%AE.md)、[NuGet 包源设置](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/NUGET%E4%B8%8ENUGET%E6%BA%90%E8%AE%BE%E7%BD%AE.md)

组件手册按包名（标题即 PackageId）在「组件」各分组检索。

## 站点概览

- [首页](https://doc.dezhentech.com/md/index.md): Aegis 3.x 业务项目使用文档首页，默认基线为 .NET 8 + Aegis 3.x；章节：快速上手是什么样、按你的来意选路、框架能力全景、业务项目的分层、环境与版本基线、建议阅读顺序
- [更新日志](https://doc.dezhentech.com/md/Changelog.md): 本次发布范围 ：3.1.4 预览线全部转正式版，版本号统一去掉预览后缀（NuGet 版本比较 3.1.4 高于所有 3.1.4-previewN ，业务方从任意预览版或 3.1.0/3.1.3 直接升级，无版本冲突）。各组自预览线以来的功能…
- [问题反馈](https://doc.dezhentech.com/md/%E9%97%AE%E9%A2%98%E5%8F%8D%E9%A6%88.md): 在遇到Aegis框架相关问题、有相关功能需求时请访问Aegis-Demo的Gitee链接提Issue。框架相关Issues反馈链接
- [Aegis 3.2 Roadmap](https://doc.dezhentech.com/md/Roadmap.md): 3.1 世代完成了组件自动装配、审计日志重设计、EventBus 重设计、启动诊断，历史欠账基本清零（实际交付见 docs/release-notes/3.1.md ）。3.2 在这个底子上做三件事：；章节：运行时基线、主题、明确不进 3.2、推进节奏、已知预定项
- [LLMs.txt（AI 助手接入）](https://doc.dezhentech.com/md/llms.md): 说明文档站的 AI 友好端点（llms.txt / llms-full.txt / md 镜像）与各 AI 工具的接入配置方式；章节：什么是 LLMs.txt、可用资源、在 AI 工具中使用、业务项目接入模板、注意事项

## 基础文档

- [快速开始](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B.md): 用 .NET 8 + Aegis 3.x 在业务项目中快速跑通宿主、数据库、Swagger 和日志的最短路径；章节：准备工作、改入口、加 Component.deps.json、配 appsettings.json、放 NLog.config （日志只配这一次）、建数据库源
- [初始系统验证清单](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%88%9D%E5%A7%8B%E7%B3%BB%E7%BB%9F%E9%AA%8C%E8%AF%81%E6%B8%85%E5%8D%95.md): 检查一个 .NET 8 + Aegis 3.x 业务项目是否已经完成宿主、数据库、Swagger 和日志的最小闭环；章节：宿主与启动、数据库闭环、日志、Swagger、API 输出、最后看这 4 件事
- [层次介绍](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%B1%82%E6%AC%A1%E4%BB%8B%E7%BB%8D.md): 说明业务项目接入 Aegis 时常见的 WebApi、Contract、Services、Dto、Repository 分层，以及它们各自负责什么；章节：一个请求是怎么流过这五层的、五层各自放什么、每层展开说两句、看一个活例子、接下来按层深入、什么时候看这页最合适
- [Startup](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Startup.md): 说明 Aegis 中 ICustomStartup 的职责，以及哪些东西适合放在 Startup 里处理；章节：哪些东西通常放在这里、一个最小 Startup 长什么样、ConfigureServices 里通常做什么、Configure 里通常做什么、ConfigureInitializer 是什么…、多个 Startup 谁先执行
- [配置](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E9%85%8D%E7%BD%AE.md): 说明 Aegis 中本地配置和配置中心各自解决什么问题，以及项目里通常怎么读取配置；章节：先把边界分清、大多数项目起步只用本地配置、什么时候再接配置中心、appsettings.json 里通常放什么、Component.deps.json 和 ap…、接配置中心时，一般怎么配
- [日志](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E6%97%A5%E5%BF%97.md): 说明 Aegis 项目里日志怎么接、日志写到哪里，以及第一版通常怎么验证它已经生效；章节：先记住这三个角色、最小接入方式、日志级别怎么选、记录异常时别偷懒、日志里为什么会带 RequestId、怎么判断日志已经接好了
- [程序集扫描与启动治理](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E7%A8%8B%E5%BA%8F%E9%9B%86%E6%89%AB%E6%8F%8F.md): 说明 Aegis 启动时扫哪些程序集、Aegis:AssemblyScan 怎么配、启动横幅和版本冲突告警怎么看；章节：组件概览、什么时候要用它、默认扫描面：四路候选、配置项说明、启动横幅怎么看、版本冲突告警
- [Services 与 Contract](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Services%E4%B8%8EContract.md): 说明 Contract 和 Services 各自负责什么、BusinessServices 组件的装配机制，以及 ServiceResult 与 PagedResult 的用法；章节：BusinessServices 开了之后发生什…、最小落地四步、ServiceResult 怎么用、PagedResult 怎么用、项目变大后怎么拆、这一层最容易写错的地方
- [Dto 数据传输层](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Dto%E6%95%B0%E6%8D%AE%E4%BC%A0%E8%BE%93%E5%B1%82.md): 说明业务项目里 Request 和 Dto 怎么放怎么写、验证是怎么生效的、Entity 到 Dto 怎么转换；章节：这一层放什么、Request 怎么写、验证是怎么生效的、Dto 怎么写、long 出前端：精度丢失要当心、Entity 到 Dto 怎么转
- [Controller](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Controller.md): 说明 Aegis 业务项目中 Controller 的职责、入参组织方式、统一响应类型与 ApiControllerBase 的全部返回方法；章节：一个常见写法、返回什么：三种响应类型、Code 与 MessageType 怎么取、返回方法速查、需要特殊响应时怎么扩展、入参怎么放
- [Swagger](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Swagger.md): 说明 Aegis 3.x 业务项目中 Swagger 的最小接入方式和验证步骤；章节：最小接入方式、两个最常见的场景、需要认证时怎么调、什么时候再补 ExtensionXmlComme…、常见问题、继续看哪里
- [入门](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%85%A5%E9%97%A8.md): 面向新业务项目的 Aegis 3.x 入门页，说明阅读顺序、项目分层和基线范围；章节：先明确文档边界、一个业务项目通常会有哪些层、可以怎样理解 HIS 示例、当前基线只覆盖到哪里、推荐阅读顺序、读完这页之后，下一步做什么
- [对象映射（Mapster）](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%AF%B9%E8%B1%A1%E6%98%A0%E5%B0%84.md): 说明 Mapster 在 Aegis 中的装配方式、Adapt 直接映射、DtoPaged 分页映射与 IRegister 自定义配置；章节：解决什么问题、如何引入、Adapt 直接映射、DtoPaged 分页映射、自定义映射配置、使用建议
- [多级缓存](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%A4%9A%E7%BA%A7%E7%BC%93%E5%AD%98.md): 这页对应 3.x 里基于 Aegis.Caching.Redis 的多级缓存能力。它的核心思路是把本地内存缓存作为 L1 ，把 Redis 作为 L2 ，把数据库或真实业务方法作为 L3 ，并通过缓存拦截器把读写删除动作统一接起来；章节：先记住多级缓存的边界、什么时候适合用它、整体结构、最小可运行路径、这组注解分别负责什么、常见参数怎么理解
- [分页与列表数据](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%88%86%E9%A1%B5%E4%B8%8E%E5%88%97%E8%A1%A8%E6%95%B0%E6%8D%AE.md): 说明分页请求参数怎么传入、Repository 层 ToPagedListAsync 的用法、Service 层 DtoPaged 转换与 PagedResult 结构；章节：分页参数从哪来、Repository 层分页、Service 层分页转换、最佳实践、边界与限制、配套阅读
- [加密工具](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Encryption.md): 3.0.0 页面说明 - 3.0.0 说明：当前页已重写为 3.x 的加密工具主题页。 - 当前组件入口： Aegis.Security.Encryption；章节：快速开始、常见能力选型、最常见的使用方式、边界与限制、常见问题、继续阅读
- [请求参数验证](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/FluentValidation%E9%AA%8C%E8%AF%81%E5%99%A8.md): API 接口收到请求参数后，需要在进入业务逻辑之前校验入参合法性（不能为空、长度限制、格式校验等）。Aegis 集成了 FluentValidation，提供了自动验证机制——写好验证器，框架会在请求进入 Controller 之前自动执行…；章节：解决什么问题、如何引入、工作原理、标准写法、验证失败的响应格式、常用验证规则
- [请求参数验证](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E8%AF%B7%E6%B1%82%E5%8F%82%E6%95%B0%E9%AA%8C%E8%AF%81.md): 说明请求参数验证的生效机制、验证器写法、常用规则与失败响应格式；章节：解决什么问题、如何引入、工作原理、标准写法、验证失败的响应格式、常用验证规则
- [请求日志](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E8%AF%B7%E6%B1%82%E6%97%A5%E5%BF%97.md): 框架内置了 RequestLogFilter （ IAsyncActionFilter ），可以自动记录每个 Controller Action 的请求和响应日志，包括请求参数、响应内容、耗时、客户端 IP 等。接入方不需要手动写日志代码；章节：解决什么问题、全局开启、按需为单个接口开启、记录了什么、默认行为、配置参考
- [认证和鉴权体系](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E8%AE%A4%E8%AF%81%E5%92%8C%E9%89%B4%E6%9D%83%E4%BD%93%E7%B3%BB.md): 这页不是某一个组件的详细说明，而是 Aegis 3.x 中认证与鉴权能力的总入口。如果你正在判断“我该接哪一组组件”“组件之间是什么关系”“先看哪篇文档最合适”，先看这里会更省时间；章节：先理解这组能力怎么分层、组件关系一图看懂、我该选哪种方案、推荐接入顺序、接入后怎么判断是否生效、建议阅读路径
- [上下文](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E4%B8%8A%E4%B8%8B%E6%96%87.md): 这页对应的是 3.x 里的运行时请求上下文能力，核心组件是 上下文（Aegis.Context）；章节：先理解边界、最常见的读取方式、什么时候适合用、什么时候不适合用、推荐阅读顺序
- [事件总线](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E4%BA%8B%E4%BB%B6%E6%80%BB%E7%BA%BF.md): 3.1.4 页面说明 - EventBus 已在 3.1.4 完成重设计（breaking）：按类型路由、Key 分区保序、命令定向投递。 - 本页是选型路由页，接入细节看组件页：事件总线（Aegis.EventBus）；章节：先做选型、推荐接入路径、一个事件可以有多个消费者、使用时的几个关键点、常见问题、EventBus vs CAP 选型对比
- [事务与工作单元](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E4%BA%8B%E5%8A%A1.md): 说明事务边界放在哪一层、手动 UnitOfWork 与 UnitOfWorkManager 两种方式、事务内使用哪个 Orm 以及最佳实践；章节：方式一：手动 UnitOfWork（当前开箱即用…、方式二：UnitOfWorkManager（Fr…、传统 DbTransaction、最佳实践、边界与限制、配套阅读
- [文档处理](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Pdf%26Ofd.md): 这页对应 3.x 里的文档处理与文件服务体系。标准入口是 文档处理（Aegis.Documents），如果还涉及文件上传、下载和落盘，再配合 文件管理（Aegis.FileManager） 或 NAS 文件存储（Aegis.FileMana…；章节：先看整体分工、最小接入方式、最常用的几条业务链路、文件管理怎么接进来、运行环境怎么准备、接入后怎么验收
- [延迟任务队列](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/%E5%BB%B6%E8%BF%9F%E4%BB%BB%E5%8A%A1%E9%98%9F%E5%88%97.md): 3.0.0 页面说明 - 3.0.0 说明：当前页已重写为 3.x 的任务调度主题页。 - 推荐阅读顺序：先看当前页选型，再进入对应组件页；章节：先做选型、推荐接入路径、最常见的任务写法、怎么取消任务、任务状态怎么理解、什么时候要单独建 Job 类
- [自定义组件注入](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Lifetime.md): Ageis 提供以 Attribute 方式来快速依赖注入；章节：基本依赖注入
- [Component.deps.json 组件清单](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Component.deps.json%E7%BB%84%E4%BB%B6%E6%B8%85%E5%8D%95.md): Component.deps.json 怎么写、怎么读：三键集合语义、依赖自动装配、框架排序规则、按环境排除、启动横幅与三类启动失败；章节：这是一份什么文件、三个键怎么写：按阶段并集、依赖自动装配：服务阶段闭包、装配顺序：框架怎么排、按环境排除组件、启动横幅怎么读
- [HTTP请求组件](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/HTTP%E8%AF%B7%E6%B1%82%E7%BB%84%E4%BB%B6.md): 这页只讨论 Broker 的 HTTP / REST 调用方式，不再混入 WebService 说明。如果你当前要对接的是普通 HTTP 接口、内部 Web API 或第三方 REST 服务，这页就是直接可用的接入手册；章节：什么时候该用这一页、最小可运行路径、URL 是怎么拼出来的、常见 HTTP 调用方式、参数绑定该怎么写、契约层可以共享哪些内容
- [ID生成器](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/ID%E7%94%9F%E6%88%90%E5%99%A8.md): 这页是 ID 生成能力的选型入口。当前体系分成两个独立组件：；章节：雪花 ID 快速接入、模板Id快速接入、常见问题、推荐阅读顺序
- [OpenTelemetry 链路追踪](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/OpenTelemetry.md): 这页对应 3.x 里的链路追踪接入方式，核心组件是 OpenTelemetry 链路追踪（Aegis.Trace.OpenTelemetry）；章节：先看 OpenTelemetry 在框架里的职责、最小接入方式、配置项怎么理解、默认追踪哪些内容、输出方式怎么选、接入后怎么验收
- [Polly 容错与重试](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Polly.md): 这页对应 3.x 里的容错与重试使用方式。 Polly 在当前文档里按“开发指南”维护，而不是按核心组件维护，因为它更像调用侧按需引入的策略库，而不是通过 Component.deps.json 统一装配的框架组件；章节：先记住 Polly 的边界、最小引入方式、什么时候最适合用 Polly、先做一个判断：不是所有接口都应该重试、常用策略怎么选、最常见的代码起步方式
- [Prometheus 指标监控](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Prometheus.md): 这页对应 3.x 里的指标监控接入方式，核心组件是 Prometheus 指标监控（Aegis.Prometheus）；章节：先看 Prometheus 在框架里的职责、最小接入方式、默认会带出哪些指标、最常见的使用方式、接入后怎么验收、常见问题
- [Redis](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Redis.md): 这页对应 3.x 里的 Redis 使用方式，核心组件是 Redis 缓存（Aegis.Caching.Redis）。其他和 Redis 相关的能力，如 Redis 会话、Redis ID 容器、Redis 事件总线，都是建立在这层基础能力…；章节：先记住 Redis 的边界、最小接入方式、四种最常见的模式怎么配、常见配置项怎么理解、RedisSource 最常见的几类操作、脚本管理怎么接
- [Repository 层](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/Repository%E5%B1%82.md): 说明 Repository 层的职责、DbSource 与仓储的注册机制、Entity 写法与事务参与方式；章节：目录结构、DbSource：给数据库一个泛型标识、Entity 怎么写、Repository 怎么写、事务：仓储怎么参与、最佳实践
- [SignalR 实时通信](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/SignalR.md): 3.0.0 页面说明 - 3.0.0 说明：当前页已恢复详细示例，避免正文信息丢失。 - 当前包名统一为 Aegis.Net.SignalR ；如遇到历史命名差异，请以本页和组件页为准。 - 组件入口： Aegis.Net.SignalR；章节：如何引入、使用方法
- [WebService调用](https://doc.dezhentech.com/md/%E5%9F%BA%E7%A1%80%E6%96%87%E6%A1%A3/WebService%E8%B0%83%E7%94%A8.md): 这页只讨论 Broker 的 WebService 调用方式，也就是 .svc 、 .asmx 这类 SOAP 服务的接入。如果你当前面对的是医院存量系统、遗留平台接口，或者对方提供的是 ServiceContract 风格契约，这页就是直…；章节：什么时候该用这一页、先分清两类服务、最小可运行路径、WCF 契约到底要怎么建、WCF .svc 怎么写、ASMX .asmx 怎么写

## 组件

- [组件总览](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/index.md): <style { .comp-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 12px; margin-bot…；章节：应用与基础设施、认证与鉴权、数据与状态、通信与集成、调度与可观测、文档与文件

## 组件 · 应用与基础设施

- [基础设施（Aegis.Core.Infrastructure）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%BA%94%E7%94%A8%E4%B8%8E%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD/Aegis.Core.Infrastructure.md): Aegis.Core.Infrastructure 是 Aegis 应用启动与基础设施装配的底座。它负责把 AegisApplication.Run(args) 、 Component.deps.json 、组件注册、中间件串联、请求上下文…；章节：组件概览、它主要负责什么、最小可运行路径、启动时自动做了哪些事、项目级扩展应该写在哪里、组件怎么消费扫描结果
- [跨域支持](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%BA%94%E7%94%A8%E4%B8%8E%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD/Aegis.Core.Cors.md): 前后端分离场景下，浏览器会执行同源策略限制跨域请求。 Aegis.Core.Cors 负责在 Aegis 应用中自动注册 CORS 策略和中间件，让前端可以正常调用 API；章节：解决什么问题、如何引入、默认行为、配置项说明、前端依赖的响应头、AllowCredentials 与通配符源的限…
- [配置（Aegis.Configuration）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%BA%94%E7%94%A8%E4%B8%8E%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD/Aegis.Configuration.md): 当你需要在 Aegis 3.x 中统一读取 appsettings.json 、自定义 JSON 配置、类型化配置对象，并让业务代码和组件都通过 ConfigManager 访问配置时，可以使用 Aegis.Configuration 。它…；章节：组件概览、如何引入、快速使用、具体使用详情、如何扩展、常见问题指南
- [日志（Aegis.Core.Logs）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%BA%94%E7%94%A8%E4%B8%8E%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD/Aegis.Core.Logs.md): Aegis.Core.Logs 是 Aegis 的日志集成组件。它负责把日志能力接入到 DI 体系里，并基于 ILogger + NLog 提供统一记录方式。当前组件还会把请求链路里的 RequestId 自动写入日志布局，方便跨接口、跨服…；章节：组件概览、最小可运行路径、组件实际做了什么、什么时候最适合配合 Aegis.Core.Log…、使用日志时最重要的几条规则、常见日志级别怎么选
- [上下文（Aegis.Context）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%BA%94%E7%94%A8%E4%B8%8E%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD/Aegis.Context.md): 业务代码经常需要访问当前请求的元信息（请求标识、客户端 IP、业务请求头等），但服务层无法直接访问 HttpContext ，手动传递又很繁琐；章节：解决什么问题、如何引入、ActionContext 的字段、使用方式、边界与限制
- [应用服务（Aegis.Services）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%BA%94%E7%94%A8%E4%B8%8E%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD/Aegis.Services.md): Aegis.Services 负责业务服务契约、服务自动注入、分页结果和服务结果约定。它对应 Component.deps.json 里的 BusinessServices 组件项，是 Aegis 业务层最核心的基础组件之一；章节：组件概览、什么时候要用它、最小可运行路径、自动注入是怎么生效的、工程结构建议怎么落、Contract 和 Services 该怎么分
- [元OS 配置中心（Aegis.UMeta.ConfigCenter）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%BA%94%E7%94%A8%E4%B8%8E%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD/Aegis.UMeta.ConfigCenter.md): Aegis.UMeta.ConfigCenter 把元OS 配置中心（uos-config-center）上的配置项挂进 IConfiguration ，业务代码继续用 IConfiguration["键"] 、 IOptionsMonit…；章节：组件概览、什么时候要用它、最小可运行路径、配置项说明（UosConfigCenter 节）、读一份配置的顺序与断网行为、热更新行为
- [自定义组件注入](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%BA%94%E7%94%A8%E4%B8%8E%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD/Aegis.Component.md): Aegis 框架通过 Component.deps.json 驱动组件的自动发现和注册。接入方不需要手动在 Startup.cs 中逐个调用 services.AddXxx() ，只需要在配置文件中声明需要的组件名，框架启动时自动装配，装配…；章节：解决什么问题、如何引入、使用示例、扩展点、边界与限制
- [Polly 容错扩展](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%BA%94%E7%94%A8%E4%B8%8E%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD/Aegis.Extensions.Polly.md): Aegis.Extensions.Polly 是调用侧按需引入的容错扩展包，用来辅助处理远程调用中的超时、重试、熔断和降级。它不需要 Component.deps.json ，不需要服务注册，在调用代码或 HttpClient 注册处显式挂…；章节：解决什么问题、如何引入、先做一个判断：不是所有接口都应该重试、常用策略怎么选、使用示例、使用降级时要明确的事
- [Swagger 文档扩展（Aegis.Extensions.Swagger）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%BA%94%E7%94%A8%E4%B8%8E%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD/Aegis.Extensions.Swagger.md): Aegis.Extensions.Swagger 用来给 Web API 提供 OpenAPI 文档、Swagger UI 调试入口和认证头说明。它不是单纯的服务注册组件，而是同时覆盖了服务注册和中间件接入，写进 Load 清单一份就能两阶…；章节：组件概览、什么时候要用它、最小可运行路径、这组配置分别控制什么、配置时最容易忽略的两个占位符、如何把 DTO、扩展类库的注释也带进 Swagg…

## 组件 · 认证与鉴权

- [基础认证（Aegis.Core.Authentication）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%AE%A4%E8%AF%81%E4%B8%8E%E9%89%B4%E6%9D%83/Aegis.Core.Authentication.md): Aegis 的认证体系分两层：本组件提供认证管线和当前用户上下文，具体的登录逻辑（SSO/JWT/ESS）由子组件补齐。只接入 Aegis.Core.Authentication 还不能登录，必须再选一个具体实现组件。业务要给当前用户带业务…；章节：组件概览、如何引入、快速接入、核心能力、认证链路、API 参考
- [基础授权（Aegis.Core.Authorization）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%AE%A4%E8%AF%81%E4%B8%8E%E9%89%B4%E6%9D%83/Aegis.Core.Authorization.md): Aegis 的授权体系分两层：本组件提供 ApiAuthorize 拦截器和权限缓存，具体的权限来源（如 ESS）由子组件补齐。基础授权依赖基础认证先建立当前用户上下文，因此不能单独使用；章节：组件概览、如何引入、快速接入、核心能力、授权拦截链路、API 参考
- [自定义认证鉴权实现指南](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%AE%A4%E8%AF%81%E4%B8%8E%E9%89%B4%E6%9D%83/%E8%87%AA%E5%AE%9A%E4%B9%89%E8%AE%A4%E8%AF%81%E9%89%B4%E6%9D%83%E5%AE%9E%E7%8E%B0%E6%8C%87%E5%8D%97.md): 当 SSO 、 JWT 、 ESS 三种内置实现都不适合你的场景时，可以通过实现 Aegis 暴露的几个接口，搭一套自己的认证鉴权链路。本指南按「从零接到端到端跑通」的顺序，说明每个扩展点的职责、实现要点和组合方式；章节：什么时候需要自己实现、三个核心扩展点的关系、自定义认证： IAuthenticationMa…、自定义会话存储： IUserManager、自定义权限来源： IAuthorizationM…、完整组合：端到端接入
- [ESS 认证鉴权（Aegis.Authorization.ESS）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%AE%A4%E8%AF%81%E4%B8%8E%E9%89%B4%E6%9D%83/Aegis.Authorization.ESS.md): 当你的系统需要对接 ESS 平台，既要完成用户认证，又要按 ESS 返回的资源权限控制接口访问，或者还需要用客凭访问其他服务时，可以接入 Aegis.Authorization.ESS 。这是当前认证与鉴权组里功能最完整、依赖关系也最复杂的…；章节：组件概览、如何引入、快速使用、具体使用详情、如何扩展、常见问题指南
- [JWT 认证（Aegis.Authorization.Jwt）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%AE%A4%E8%AF%81%E4%B8%8E%E9%89%B4%E6%9D%83/Aegis.Authorization.Jwt.md): 当你不想依赖外部认证中心，而是希望在应用内生成 Bearer Token、通过登录接口发放 Token 并在后续请求里复用时，可以接入 Aegis.Authorization.Jwt 。下面说明当前版本下它的实际接法、能力边界和已知约束；章节：组件概览、如何引入、快速使用、具体使用详情、如何扩展、常见问题指南
- [Redis 用户会话（Aegis.Authorization.RedisUserManager）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%AE%A4%E8%AF%81%E4%B8%8E%E9%89%B4%E6%9D%83/Aegis.Authorization.RedisUserManager.md): 当你的认证方案需要把登录态和用户会话放到 Redis，而不是仅保存在单机内存里时，可以接入 Aegis.Authorization.RedisUserManager 。它不是独立的认证方案，而是用来替换基础认证默认 IUserManager…；章节：组件概览、如何引入、快速使用、具体使用详情、如何扩展、常见问题指南
- [SSO 认证（Aegis.Authorization.SSO）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%AE%A4%E8%AF%81%E4%B8%8E%E9%89%B4%E6%9D%83/Aegis.Authorization.SSO.md): 当你的系统需要对接中心化 SSO 服务，通过远端用户中心校验 Token、补全用户信息，并把用户上下文写入 Aegis 请求链路时，可以接入 Aegis.Authorization.SSO 。本文重点说明它在 3.x 下的定位、配置和与基础…；章节：组件概览、如何引入、快速使用、具体使用详情、如何扩展、常见问题指南

## 组件 · 数据与状态

- [库表校验（Aegis.Core.FreeSql.SchemaValidation）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%95%B0%E6%8D%AE%E4%B8%8E%E7%8A%B6%E6%80%81/Aegis.Core.FreeSql.SchemaValidation.md): 库表校验把实体属性声明的类型和数据库列的真实类型逐一比对，结果展示在 /diag 诊断页面上，按需触发。它抓的是一类安静的事故：实体用 string 接了库里实际是 timestamp 的列，查询不报错、数据也返回，但 FreeSql 每读…；章节：组件概览、什么时候要用它、最小可运行路径、/diag 页面上的三处出口、实体归属声明 [DbSource]、判定语义
- [字段自动赋值（Aegis.Core.FreeSql.AuditValue）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%95%B0%E6%8D%AE%E4%B8%8E%E7%8A%B6%E6%80%81/Aegis.Core.FreeSql.AuditValue.md): 当系统使用 FreeSql 持久化，实体上存在一组公共审计字段（创建时间 / 创建人 / 更新时间 / 更新人 / 租户标识等），希望在 Insert / Update 时由框架统一填充，避免在业务代码里逐处赋值时，可以使用 Aegis.C…；章节：组件概览、如何引入、快速使用、具体使用详情、常见问题
- [FreeSql 数据访问（Aegis.Core.FreeSql）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%95%B0%E6%8D%AE%E4%B8%8E%E7%8A%B6%E6%80%81/Aegis.Core.FreeSql.md): Aegis.Core.FreeSql 负责数据库连接初始化、 IFreeSql 实例注册和仓储自动扫描。它封装了 FreeSql ORM 的启动配置，让项目不需要手动构建 FreeSqlBuilder ；章节：解决什么问题、版本一致性、如何引入、配置项、注册 API 说明、实体层约定
- [ID 生成器（Aegis.IdGenerator）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%95%B0%E6%8D%AE%E4%B8%8E%E7%8A%B6%E6%80%81/Aegis.IdGenerator.md): Aegis.IdGenerator 是 Aegis 的雪花 ID 生成组件。它生成全局唯一的 long ，WorkerId 支持静态配置与 Redis / PostgreSQL 租约动态分配，并对时钟回拨做分级保护；章节：组件概览、什么时候用雪花 ID、最小可运行路径（静态模式）、配置项说明（SnowflakeOptions，节…、WorkerId 三种分配模式、租约模式接入（Redis / PostgreSQ…
- [Redis 缓存（Aegis.Caching.Redis）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%95%B0%E6%8D%AE%E4%B8%8E%E7%8A%B6%E6%80%81/Aegis.Caching.Redis.md): Aegis.Caching.Redis 是 Aegis 中与 Redis 交互的基础能力包。它负责提供 RedisSourceBase 、脚本管理和多级缓存所依赖的底座能力。它不通过 Component.deps.json 自动装配，而是由…；章节：组件概览、什么时候要用它、先记住它和其他 Redis 相关组件的关系、最小可运行路径、这组配置分别控制什么、最常见的三种配置场景

## 组件 · 通信与集成

- [分布式事件总线（Aegis.CAP）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E9%80%9A%E4%BF%A1%E4%B8%8E%E9%9B%86%E6%88%90/Aegis.CAP.md): 当你需要跨服务通信、消息不丢失、或把消息发布和业务操作绑在同一个数据库事务里时，可以使用 Aegis.CAP 。它基于 DotNetCore.CAP，提供本地消息表（Outbox Pattern）、消息重试和 FreeSql 事务集成；章节：组件概览、什么时候要用它、最小接入方式、命名规范、发布消息、订阅消息
- [实时通信（Aegis.Net.SignalR）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E9%80%9A%E4%BF%A1%E4%B8%8E%E9%9B%86%E6%88%90/Aegis.Net.SignalR.md): 当你需要在 Aegis Web API 中提供 Hub、服务端主动推送、跨节点实时广播能力时，可以接入 Aegis.Net.SignalR 。本文按 Aegis 3.x / .NET 8 口径说明当前组件的真实接入方式，读完后你应该能完成组…；章节：组件概览、如何引入、快速使用、具体使用详情、如何扩展、常见问题指南
- [事件总线（Aegis.EventBus）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E9%80%9A%E4%BF%A1%E4%B8%8E%E9%9B%86%E6%88%90/Aegis.EventBus.md): Aegis.EventBus 是进程内事件总线：同一个应用里，一段业务代码发布事件，若干个消费者在后台异步消费。两条通道：事件（ PublishAsync ，0..N 个消费者各自消费）和命令（ SendAsync ，恰好 1 个处理方）。…；章节：组件概览、行为边界（接入前先读）、什么时候要用它、最小可运行路径、发布 API：IMessageSender 的五…、消费 API 与消息模型
- [远程调用客户端（Aegis.Net.Broker）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E9%80%9A%E4%BF%A1%E4%B8%8E%E9%9B%86%E6%88%90/Aegis.Net.Broker.md): 当你需要通过“契约接口 + 特性”来描述远程服务，并把方法调用自动转成 HTTP 或 SOAP 请求时，可以使用 Aegis.Net.Broker 。它适合跨服务调用、第三方接口封装，以及把零散 HTTP 请求收敛成稳定契约的场景；章节：组件概览、如何引入、快速使用、使用路线、该先看哪一页、具体使用详情
- [RocketMQ 客户端（Aegis.RocketMQ.Client）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E9%80%9A%E4%BF%A1%E4%B8%8E%E9%9B%86%E6%88%90/Aegis.RocketMQ.Client.md): Aegis.RocketMQ.Client 提供 RocketMQ 的底层客户端接入能力，包括连接管理、生产者和消费者。它和 事件总线（Aegis.EventBus） 不是同一层：前者是直接 MQ 客户端，后者是统一消息抽象；章节：组件概览、什么时候要用它、最小接入方式、配置项怎么理解、生产者怎么用、消费者怎么用

## 组件 · 调度与可观测

- [任务调度（Aegis.Jobs）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%B0%83%E5%BA%A6%E4%B8%8E%E5%8F%AF%E8%A7%82%E6%B5%8B/Aegis.Jobs.md): Aegis.Jobs 是 Aegis 的延时任务（延时队列）基础组件。业务代码用一行表达式提交延时任务： AegisJob.Schedule(() = SendEmail(id), TimeSpan.FromMinutes(5)) ，到点后…；章节：组件概览、什么时候要用它、先记住它和存储扩展的关系、最小可运行路径、调度方式：8 个重载、怎么取消任务
- [外部调度平台接入（Aegis.Scheduler）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%B0%83%E5%BA%A6%E4%B8%8E%E5%8F%AF%E8%A7%82%E6%B5%8B/Aegis.Scheduler.md): Aegis.Scheduler 是 Aegis 对接外部工作流调度平台的能力，用于在代码里以编程方式管理定时任务（创建、触发、查询、删除）；章节：组成结构、何时使用、引入与配置、Token 获取与过期处理、核心接口 ISchedulerClient、任务类型选择指引
- [延时任务迁移指南（Aegis.Jobs.Migration）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%B0%83%E5%BA%A6%E4%B8%8E%E5%8F%AF%E8%A7%82%E6%B5%8B/Aegis.Jobs.Migration.md): 从旧版 Aegis.Jobs（preview / 试用版，本地定时器 + KV 归属表架构）升级到 3.1.1-preview1（存储唯一真值 + 秒级扫描架构）时，业务代码零改动，需要动手的是数据库结构和几项必须知晓的行为变化。本页给出完…；章节：业务代码：零改动、行为变化：代码不用改，但必须逐条确认、配置：清理 3 个失效键、数据库迁移、破坏性变更：只影响高级用法、上线检查清单
- [诊断组件（Aegis.Diagnostics）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%B0%83%E5%BA%A6%E4%B8%8E%E5%8F%AF%E8%A7%82%E6%B5%8B/Aegis.Diagnostics.md): <style { .doc-img { width: 80%; } }</style；章节：组件概览、添加诊断组件、配置项说明（Aegis:Diagnostics）、用 /diag 排查问题、业务组件往页面上加内容：五个接口、常见问题
- [OpenTelemetry 链路追踪（Aegis.Trace.OpenTelemetry）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%B0%83%E5%BA%A6%E4%B8%8E%E5%8F%AF%E8%A7%82%E6%B5%8B/Aegis.Trace.OpenTelemetry.md): Aegis.Trace.OpenTelemetry 负责把当前服务接入 OpenTelemetry tracing，并将链路输出到 OTLP 端点或控制台。它当前聚焦的是追踪链路，而不是 Prometheus 指标暴露；章节：组件概览、什么时候要用它、最小可运行路径、配置项怎么理解、组件默认采集什么、导出方式怎么判断
- [Postgres 任务存储扩展（Aegis.Jobs.Postgres）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%B0%83%E5%BA%A6%E4%B8%8E%E5%8F%AF%E8%A7%82%E6%B5%8B/Aegis.Jobs.Postgres.md): Aegis.Jobs.Postgres 是 Aegis.Jobs 的 PostgreSQL / KingbaseES 持久化扩展。任务数据写入数据库，数据库是唯一真值：每个实例的扫描服务每隔一秒从库里领取到期任务，领取即互斥（ FOR UP…；章节：组件概览、什么时候要用它、最小可运行路径、它是怎么跑起来的、故障接管：任务什么时候会被别的实例抢走、执行期续租
- [Prometheus 指标监控（Aegis.Prometheus）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%B0%83%E5%BA%A6%E4%B8%8E%E5%8F%AF%E8%A7%82%E6%B5%8B/Aegis.Prometheus.md): Aegis.Prometheus 负责暴露 /metrics 采集端点，并自动接入基础 HTTP 指标。它更偏指标暴露组件，不负责链路追踪；如果你还要看调用链，再配合 OpenTelemetry 链路追踪；章节：组件概览、什么时候要用它、最小可运行路径、组件默认做了什么、最常见的接入方式、接入后怎么确认生效
- [SqlServer 任务存储扩展（Aegis.Jobs.SqlServer）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%B0%83%E5%BA%A6%E4%B8%8E%E5%8F%AF%E8%A7%82%E6%B5%8B/Aegis.Jobs.SqlServer.md): Aegis.Jobs.SqlServer 是 Aegis.Jobs 的 SQL Server 存储扩展包。它用于把任务数据落到 SQL Server，但当前 3.x 更推荐优先使用 Aegis.Jobs.Postgres 作为标准持久化方案…；章节：组件概览、什么时候要用它、最小可运行路径、这条链路要注意什么、接入后怎么确认已经生效、常见问题
- [UMeta 结构化日志与 OpenTelemetry](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E8%B0%83%E5%BA%A6%E4%B8%8E%E5%8F%AF%E8%A7%82%E6%B5%8B/Aegis.UMeta.Logging.md): Aegis.UMeta.Logging 将 Aegis 应用的日志接入 UMetaOS OpenTelemetry SDK，实现：；章节：解决什么问题、如何引入、使用示例、扩展点、边界与限制

## 组件 · 文档与文件

- [本地文件存储（Aegis.FileManager.Local）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.FileManager.Local.md): Local 是 Aegis.FileManager 基础包内置的本地文件系统存储实现，把文件读写落到进程可直写的磁盘目录。纯 System.IO 实现，零网络依赖，不计算 MD5；章节：组件概览、什么时候要用它、显式 Provider，不是隐式兜底、最小可运行路径、配置项说明（LocalOptions）、行为细则
- [文档处理（Aegis.Documents）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.Documents.md): Aegis.Documents 是文档处理体系的根组件。标准接入时，优先直接启用它；HTML 转 PDF、Word 转 PDF、OFD 转换、OpenXml 编辑和 Razor 模板渲染都会一起装配好；章节：组件概览、什么时候要用它、最小可运行路径、这个组件会带出哪些接口、常见接入顺序、运行环境怎么判断
- [文件管理（Aegis.FileManager）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.FileManager.md): 本页是 Aegis 文件系统的概念入口。具体接入步骤见子页面： - 本地文件存储 - S3 对象存储 - NAS 本地存储 - WebDAV 文件存储；章节：组件概览、框架定位、核心概念：业务自拼 Key、核心接口、核心模型、怎么选存储后端
- [LibreOffice 文档转换（Aegis.Documents.Conversion.LibreOffice）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.Documents.Conversion.LibreOffice.md): Aegis.Documents.Conversion.LibreOffice 负责 Word 转 PDF。 Word - OFD 也是先经过这层转换，所以这页主要回答的是 Word 文档如何进入整个文档输出链路；章节：组件概览、什么时候重点看这页、标准接法、最小使用示例、运行模式怎么理解、关键配置怎么理解
- [NAS 本地存储（Aegis.FileManager.Nas）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.FileManager.Nas.md): Aegis.FileManager.Nas 是 Aegis.FileManager 的一个实际存储实现，把文件读写落到 NAS 或共享目录；章节：组件概览、什么时候要用它、最小可运行路径、配置项说明（NasOptions）、groupName 的职责、业务接入指引
- [OFD 文档转换（Aegis.Documents.Conversion.Ofd）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.Documents.Conversion.Ofd.md): Aegis.Documents.Conversion.Ofd 负责 PDF - OFD ，同时也是 HTML - OFD 和 Word - OFD 的最后一跳；章节：组件概览、什么时候重点看这页、三条常见转换路径、最小使用示例、渲染参数怎么理解、接入后怎么确认生效
- [OpenXml 文档编辑（Aegis.Documents.Editing.OpenXml）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.Documents.Editing.OpenXml.md): Aegis.Documents.Editing.OpenXml 负责编辑 Word 文档本身。它更适合做模板填充、表格增删和批量编辑，而不是直接生成 PDF；章节：组件概览、什么时候重点看这页、最小使用示例、最常见的组合用法、接入后怎么确认生效、常见问题
- [Playwright 文档转换（Aegis.Documents.Conversion.Playwright）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.Documents.Conversion.Playwright.md): Aegis.Documents.Conversion.Playwright 负责 HTML 转 PDF。 HTML - OFD 也建立在这层能力之上，所以这页实际上对应的是整条浏览器渲染链路；章节：组件概览、什么时候重点看这页、标准接法、最小使用示例、常见场景、关键配置怎么理解
- [Razor 文档渲染（Aegis.Documents.Rendering.Razor）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.Documents.Rendering.Razor.md): Aegis.Documents.Rendering.Razor 负责把 Razor 模板渲染成 HTML。它自己不直接输出 PDF 或 OFD，而是通常和 IHtmlToPdfConverter 、 IHtmlToOfdConverter …；章节：组件概览、什么时候重点看这页、标准接法、最小使用示例、推荐目录结构、模板和静态资源怎么写
- [S3 对象存储（Aegis.FileManager.S3）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.FileManager.S3.md): Aegis.FileManager.S3 是 Aegis.FileManager 的 S3 协议兼容存储实现，支持 AWS S3、MinIO、Ceph、阿里云 OSS、UMeta 等所有兼容 S3 协议的对象存储服务；章节：组件概览、什么时候要用它、最小可运行路径、配置项说明（S3Options）、groupName 的职责、IFileManager 接口方法与 S3 AP…
- [WebDAV 文件存储（Aegis.FileManager.WebDav）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%96%87%E6%A1%A3%E4%B8%8E%E6%96%87%E4%BB%B6/Aegis.FileManager.WebDav.md): Aegis.FileManager.WebDav 是 Aegis.FileManager 的 WebDAV 协议存储实现，对接 nginx 等 WebDAV 静态资源站。零第三方依赖：纯 HttpClient 发请求， System.Xml…；章节：组件概览、什么时候要用它、最小可运行路径、配置项说明（WebDavOptions）、groupName 的职责、nginx 服务端配置要求

## 组件 · 安全与工具

- [加密工具（Aegis.Security.Encryption）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%AE%89%E5%85%A8%E4%B8%8E%E5%B7%A5%E5%85%B7/Aegis.Security.Encryption.md): Aegis.Security.Encryption 是一组纯代码调用型加密工具包。它主要通过扩展方法提供对称加密、非对称加密、签名和摘要能力，不依赖组件声明，也不要求额外中间件；章节：组件概览、什么时候要用它、最小可运行路径、这组能力怎么选、最常见的使用方式、边界与限制
- [审计日志（Aegis.Security.AuditLog）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%AE%89%E5%85%A8%E4%B8%8E%E5%B7%A5%E5%85%B7/Aegis.Security.AuditLog.md): 记录"谁在什么时候对什么对象做了什么"。两个包一组： Aegis.Security.AuditLog 是核心， Aegis.Security.AuditLog.FreeSql 负责存进数据库；第三个包 Aegis.Security.Audi…；章节：什么时候要用它、五步接入、定义实体和动作、常见用法、报文附件（接口输入输出留痕）、查询
- [审计日志查询页（Aegis.Security.AuditLog.UI）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%AE%89%E5%85%A8%E4%B8%8E%E5%B7%A5%E5%85%B7/Aegis.Security.AuditLog.UI.md): 审计日志的内置综合查询页。装上这个包、在组件清单里声明一行，浏览器打开 /auditlog-ui 就能查审计：按领域、子域、动作、时间、操作人、关键词、级别、操作对象任意组合筛选，批量操作折叠成一条汇总行，点开看明细。页面和配套端点打包在组…；章节：组件概览、什么时候要用它、最小可运行路径、页面能做什么、配套端点、接入后怎么确认生效
- [数据脱敏（Aegis.Security.DataMasking）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%AE%89%E5%85%A8%E4%B8%8E%E5%B7%A5%E5%85%B7/Aegis.Security.DataMasking.md): 接口返回 JSON 时，把 DTO 上标注了 [Mask] 的 string 字段按规则打码成 。规则放在独立的 maskrules.json 里，改规则文件即时生效，不用重启应用。只在输出侧打码：前端把 138 5678 提交回来，框架会…；章节：组件概览、什么时候要用它、最小可运行路径、配置项说明、工作机制、自定义扩展
- [条码生成工具（Aegis.Toolkit.Barcode）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%AE%89%E5%85%A8%E4%B8%8E%E5%B7%A5%E5%85%B7/Aegis.Toolkit.Barcode.md): Aegis.Toolkit.Barcode 用来生成二维码和一维条形码，输出黑白 PNG。编码基于 ZXing.Net，PNG 编码只依赖 .NET 基类库。纯静态类调用，不需要 DI 注册，也不需要 Component.deps.json…；章节：组件概览、什么时候要用它、最小可运行路径、Service 封装：Base64 与文件流两套…、两个入口怎么选、配置项说明
- [状态机工具（Aegis.Toolkit.StateMachine）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E5%AE%89%E5%85%A8%E4%B8%8E%E5%B7%A5%E5%85%B7/Aegis.Toolkit.StateMachine.md): Aegis.Toolkit.StateMachine 用来把复杂状态流转从业务代码里拆出来。它提供状态上下文、状态验证器、状态处理器和状态机基类，适合把“哪些状态能转、进入某状态要做什么、退出某状态要做什么”统一收口；章节：组件概览、什么时候要用它、最小可运行路径、这组类型分别负责什么、状态机实际执行流程、边界与限制

## 组件 · AI与智能集成

- [MCP 协议集成（Aegis.AI.Mcp）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/AI%E4%B8%8E%E6%99%BA%E8%83%BD%E9%9B%86%E6%88%90/Aegis.AI.Mcp.md): 当你希望同一份 Controller 方法既对外提供 REST API、又能让 LLM 通过 MCP 协议（Model Context Protocol）直接调用为 Tool 时，接入 Aegis.AI.Mcp 。本文按 Aegis 3.x…；章节：组件概览、什么时候要用它、最小可运行路径、配置项说明、进阶能力、自定义扩展

## 组件 · 框架组件

- [第三方集成（Aegis.Integration）](https://doc.dezhentech.com/md/%E7%BB%84%E4%BB%B6/%E6%A1%86%E6%9E%B6%E7%BB%84%E4%BB%B6/Aegis.Integration.md): 医疗行业做产品绕不开一件事：每家医院的第三方接口都不一样，同一家厂商在不同医院还各有变种。 Aegis.Integration 把这件事拆成两半： 框架只决定"由哪个适配器实现"（绑定与路由），不规定"出入参怎么转换"（字段映射、协议选择全…；章节：组件概览、什么时候要用它、如何使用、如何绑定、弹性与故障处理、工程实现：Connector 包、厂商包与医院交…

## 工具包

- [状态机](https://doc.dezhentech.com/md/%E5%B7%A5%E5%85%B7%E5%8C%85/StateMachine.md): 3.0.0 页面说明 - 3.0.0 说明：当前页已重写为 3.x 的状态机主题页。 - 当前组件入口： Aegis.Toolkit.StateMachine；章节：推荐接入路径、应该怎么理解这几层、最容易踩坑的地方、常见问题、继续阅读

## 扩展

- [扩展总览](https://doc.dezhentech.com/md/%E6%89%A9%E5%B1%95/index.md): <style { .comp-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 12px; margin-bot…；章节：业务组件

## 扩展 · 业务组件

- [模板Id生成（Aegis.TemplateIdGenerator）](https://doc.dezhentech.com/md/%E6%89%A9%E5%B1%95/%E4%B8%9A%E5%8A%A1%E7%BB%84%E4%BB%B6/Aegis.TemplateIdGenerator.md): Aegis.TemplateIdGenerator 用于按照业务模板生成门诊号、住院号、检验单号、床位号等模板Id。业务代码统一依赖 ITemplateIdGenerator ，默认实现适合单进程运行；章节：如何引入、组件概览、什么时候要用它、最小可运行路径、核心概念、生成、确认与归还
- [系统参数（Aegis.SystemSettings）](https://doc.dezhentech.com/md/%E6%89%A9%E5%B1%95/%E4%B8%9A%E5%8A%A1%E7%BB%84%E4%BB%B6/Aegis.SystemSettings.md): Aegis.SystemSettings 将宿主配置中的业务参数按系统、院区和分组组织起来。已知字段使用 IOptionsMonitor<T 读取配置类，运行时才能确定的分组和参数名使用 ISystemSettings 读取；两种方式都支持…；章节：如何引入、组件概览、什么时候要用它、最小可运行路径、院区参数覆盖、按运行时坐标读取
- [HTTP 系统参数（Aegis.SystemSettings.Http）](https://doc.dezhentech.com/md/%E6%89%A9%E5%B1%95/%E4%B8%9A%E5%8A%A1%E7%BB%84%E4%BB%B6/Aegis.SystemSettings.Http.md): Aegis.SystemSettings.Http 让应用通过 HTTP 定期获取管理后台已发布的系统参数。业务通过配置类读取当前值，参数发布后自动更新；网络暂时不可用时，继续使用最近一次有效配置；章节：如何引入、组件概览、最小可运行路径、跨系统读取、配置项说明、启动、更新与故障恢复
- [Redis 模板Id（Aegis.TemplateIdGenerator.Redis）](https://doc.dezhentech.com/md/%E6%89%A9%E5%B1%95/%E4%B8%9A%E5%8A%A1%E7%BB%84%E4%BB%B6/Aegis.TemplateIdGenerator.Redis.md): <style { .doc-img { width: 50%; } }</style；章节：如何引入、组件概览、什么时候要用它、最小可运行路径、与默认实现的差异、生成、确认与归还
- [Redis 系统参数（Aegis.SystemSettings.Redis）](https://doc.dezhentech.com/md/%E6%89%A9%E5%B1%95/%E4%B8%9A%E5%8A%A1%E7%BB%84%E4%BB%B6/Aegis.SystemSettings.Redis.md): <style { .doc-img { width: 50%; } }</style；章节：如何引入、组件概览、什么时候要用它、最小可运行路径、参数发布后如何生效、管理后台与业务宿主的职责

## 部署

- [部署总览](https://doc.dezhentech.com/md/%E9%83%A8%E7%BD%B2/index.md): 当前部署文档按两条主线组织：；章节：推荐阅读顺序、怎么选文档
- [K8s 资源评估与压测定值方案](https://doc.dezhentech.com/md/%E9%83%A8%E7%BD%B2/k8s%E8%B5%84%E6%BA%90%E8%AF%84%E4%BC%B0%E4%B8%8E%E5%8E%8B%E6%B5%8B%E5%AE%9A%E5%80%BC.md): 服务从裸机/IIS 迁到 Kubernetes，第一个要回答的问题就是：request/limit 开多少、副本数算几个。这份文档给出一套可执行的完整流程——从本地压测拿到单 pod 容量曲线，到类生产环境校准，到定值上线，再到上线后用真实…；章节：三条原则、框架资源画像：什么在吃资源、总体流程：四个阶段、阶段一：本地单 pod 容量曲线、阶段二：类生产校准、阶段三：定值与上线

## 其他

- [如何从 2.2.0 升级到 3.0.0](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/v2%E7%89%88%E6%9C%AC%E5%8D%87%E7%BA%A7.md): 这页对应的是 Aegis 2.2.0 - 3.0.0 / 3.x 的升级指南。 它不只是讲 .NET 6 - .NET 8 ，还包括组件包、命名空间、启动方式和组件装配方式的整体迁移；章节：升级前先看、升级前准备、必改项、建议改项、按场景补的调整项、推荐升级顺序
- [文档版本切换](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/%E6%96%87%E6%A1%A3%E7%89%88%E6%9C%AC%E5%88%87%E6%8D%A2.md): 如果要使用之前版本的 Aegis，请查看对应的 Aegis 文档版本；章节：文档版本列表
- [文档组件 Docker 环境](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/deploy-docker.md): 如何在 Docker 容器中准备 Aegis 3.0.0 文档处理体系的运行环境，重点覆盖 Aegis.Documents 与其运行时依赖；章节：目录、部署方式选择、方式一：构建自定义基础镜像（推荐）、方式二：单文件完整 Dockerfile、依赖说明、环境变量配置
- [文档组件环境准备](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/environment-setup.md): Aegis.Documents 体系的运行环境准备，主要覆盖 Aegis.Documents 、 Aegis.Documents.Conversion.LibreOffice 、 Aegis.Documents.Conversion.Pla…；章节：功能与依赖对照表、在线环境配置、离线环境配置、Docker 环境、常见问题
- [Debian/Ubuntu 文档组件离线准备](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/deploy-offline-debian.md): 如何在 无网络连接 的 Debian/Ubuntu 服务器上准备 Aegis 3.1.0 文档处理组件所需的运行环境依赖，主要面向 Aegis.Documents 体系；章节：目录、系统要求、依赖项清单、离线包准备（有网络机器）、离线安装（目标机器）、验证安装
- [IIS 应用程序池配置](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/IIS%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F%E6%B1%A0%E9%85%8D%E7%BD%AE.md): Windows 下 Aegis 应用部署完成后的 IIS 应用程序池参数建议。不讨论 Chrome、LibreOffice 等文档组件运行环境
- [Linux 应用部署](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/Linux%E9%83%A8%E7%BD%B2.md): Aegis 3.x 应用在 Linux 上的发布、运行和托管方式。不讨论 Aegis.Documents 体系依赖的浏览器、LibreOffice、Python 等组件环境；章节：适用范围、推荐部署流程、使用 systemd 托管、网络与防火墙、验收清单、常见问题
- [NuGet 包源设置](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/NUGET%E4%B8%8ENUGET%E6%BA%90%E8%AE%BE%E7%BD%AE.md): Aegis 框架包源（Nexus 聚合源，已包含内部包与 nuget.org 公共包，配此一个源即可）：
- [RHEL/CentOS 文档组件离线准备](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/deploy-offline-rhel.md): 如何在 无网络连接 的 RHEL/CentOS 服务器上准备 Aegis 3.1.0 文档处理组件所需的运行环境依赖，主要面向 Aegis.Documents 体系；章节：目录、系统要求、依赖项清单、离线包准备（有网络机器）、离线安装（目标机器）、验证安装
- [Seq 部署和维护](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/Seq%E9%83%A8%E7%BD%B2%E5%92%8C%E7%BB%B4%E6%8A%A4.md): Seq 是 Aegis 框架推荐的集中式日志平台。应用通过 NLog.Targets.Seq 将结构化日志推送到 Seq，运维人员在 Seq Web UI 中检索和分析日志；章节：Docker 部署、NLog 配置、ApiKey 管理、通用属性约定、数据维护
- [Seq 使用手册](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/Seq%E4%BD%BF%E7%94%A8%E6%89%8B%E5%86%8C.md): 在 Starter 项目里，打开Nuget包管理器，搜索并安装 NLog.Targets.Seq （也可以非侵入式依赖，直接拷贝dll文件到对应程序文件夹内也可） 以下两种方式配合修改配置均可引入Seq；章节：搜索表达式、使用时间来定位日志、复杂查询
- [Windows 文档组件离线准备](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/deploy-offline-windows.md): 如何在 无网络连接 的 Windows 服务器上准备 Aegis 3.1.0 文档处理组件所需的运行环境依赖，主要面向 Aegis.Documents 体系；章节：目录、系统要求、依赖项说明、离线包下载、安装步骤、验证安装
- [Windows 应用部署](https://doc.dezhentech.com/md/%E5%85%B6%E4%BB%96/windows-app-deploy.md): Aegis 3.x 应用在 Windows 上的发布与 IIS 托管方式。不讨论 Aegis.Documents 体系依赖的浏览器、LibreOffice、Python 等组件环境；章节：适用范围、推荐部署流程、验收清单、常见问题