fengling-auth-service/.planning/codebase/ARCHITECTURE.md

架构分析

分析日期： 2026-02-28

模式概述

整体架构： 基于 ASP.NET Core 的现代 Web 应用架构，采用分层设计结合领域驱动思想。

核心特性：

• 使用 OpenIddict 实现 OAuth2/OIDC 授权服务器功能
• 采用 ASP.NET Core Identity 进行用户身份管理
• 基于 Entity Framework Core 进行数据访问
• 支持多租户（Tenant）架构
• 集成 MediatR 实现 CQRS 模式（通过共享基础设施包）

分层架构

1. 表现层（Presentation Layer）

位置： src/Controllers/、src/Views/

职责：

• 处理 HTTP 请求与响应
• 渲染 Razor 视图
• 用户交互界面

关键控制器：

• AccountController：用户登录、注册、登出
• AuthorizationController：OAuth2 授权端点
• TokenController：令牌颁发端点
• DashboardController：用户仪表板
• UsersController、RolesController、TenantsController：管理功能

2. 视图模型层（ViewModel Layer）

位置： src/ViewModels/

职责：

• 在控制器与视图之间传递数据
• 表单数据绑定与验证

关键视图模型：

• LoginViewModel：登录表单
• RegisterViewModel：注册表单
• AuthorizeViewModel：授权确认表单
• DashboardViewModel：仪表板数据

3. 配置层（Configuration Layer）

位置： src/Configuration/

职责：

• 集中管理应用程序配置
• OpenIddict 服务配置
• 身份验证策略配置

关键配置：

• OpenIddictSetup.cs：OpenIddict 完整配置，包括授权流程、令牌生命周期、作用域等
• FormValueRequiredAttribute.cs：自定义属性用于表单提交处理

4. 基础设施层（Infrastructure Layer）

外部依赖： Fengling.Platform.Infrastructure NuGet 包

提供的功能：

• PlatformDbContext：Entity Framework Core 数据库上下文
• ApplicationUser：应用程序用户实体
• ApplicationRole：应用程序角色实体
• 仓储（Repository）模式实现
• MediatR 中间件与行为（Behaviors）
• 命令锁定行为（Command Lock Behavior）
• 工作单元（Unit of Work）支持

数据流

用户认证流程

1. 用户访问 /account/login
   ↓
2. AccountController 返回登录视图（Login.cshtml）
   ↓
3. 用户提交表单 → AccountController.Login POST
   ↓
4. UserManager 验证用户名密码
   ↓
5. SignInManager 创建认证 Cookie
   ↓
6. 重定向到原始 URL 或 /dashboard

OAuth2 授权码流程

1. 客户端应用重定向到 /connect/authorize
   ↓
2. AuthorizationController.Authorize 检查用户登录状态
   ↓
3. 未登录 → 重定向到登录页面
   ↓
4. 已登录 → 检查授权记录
   ↓
5. 需要用户授权 → 返回授权确认视图（Authorize.cshtml）
   ↓
6. 用户确认 → AuthorizationController.Accept
   ↓
7. 创建授权记录 → 返回令牌

令牌颁发流程

1. 客户端 POST /connect/token
   ↓
2. TokenController.Exchange 处理请求
   ↓
3. 根据授权类型（password/refresh_token/authorization_code）处理
   ↓
4. 从 UserManager 获取用户信息
   ↓
5. 构建 Claims 身份（包括租户信息、角色）
   ↓
6. 设置 Claim Destinations
   ↓
7. SignIn 返回令牌

关键抽象

用户与租户抽象

ApplicationUser：

• 继承自 ASP.NET Core Identity 的 IdentityUser
• 包含 TenantInfo 属性实现多租户支持

TenantInfo 值对象：

• TenantId：租户标识符
• TenantCode：租户代码
• TenantName：租户名称

声明（Claims）抽象

标准声明：

• sub：用户唯一标识
• name：用户名
• email：用户邮箱
• role：用户角色

自定义声明：

• tenant_id：租户 ID
• tenant_code：租户代码
• tenant_name：租户名称

授权（Authorization）抽象

OpenIddict 实体：

• OpenIddictApplication：OAuth2 客户端应用
• OpenIddictAuthorization：授权记录
• OpenIddictScope：授权作用域
• OpenIddictToken：访问令牌/刷新令牌

入口点

Web 应用程序入口

位置： src/Program.cs

启动流程：

1. 配置 Serilog 日志
2. 注册平台核心服务（AddPlatformCore）
3. 配置 ASP.NET Core Identity
4. 配置 Razor Pages 和 MVC
5. 配置 Cookie 认证
6. 配置 OpenIddict
7. 配置 OpenTelemetry 分布式追踪
8. 配置健康检查
9. 注册仓储（Repositories）
10. 注册 MediatR 和中间件行为
11. 配置 Swagger（开发环境）
12. 初始化数据库

HTTP 端点

认证端点：

• GET/POST /account/login：用户登录
• GET/POST /account/register：用户注册
• POST /account/~/connect/logout：用户登出
• GET/POST /connect/authorize：授权端点
• POST /connect/token：令牌端点
• GET /connect/userinfo：用户信息端点

管理端点：

• GET /dashboard：用户仪表板
• GET /dashboard/profile：用户资料
• GET /dashboard/settings：设置页面
• GET/POST /users：用户管理
• GET/POST /roles：角色管理
• GET/POST /tenants：租户管理

系统端点：

• GET /health：健康检查
• GET /swagger/index.html：API 文档

错误处理

策略： 基于 ASP.NET Core 标准异常处理

模式：

• 模型验证失败返回视图（ModelState）
• 认证失败返回 401/403
• OpenIddict 错误返回标准错误响应
• 全局异常由中间件捕获并记录

跨领域关注点

日志记录

框架： Serilog

配置： 在 Program.cs 中配置，控制台输出

模板：

[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}

分布式追踪

框架： OpenTelemetry

组件：

• AspNetCoreInstrumentation
• HttpClientInstrumentation
• OpenIddict.Server.AspNetCore 追踪源
• OTLP Exporter

健康检查

端点： /health

检查项：

• PostgreSQL 数据库连接（NpgSql）

安全配置

认证方案：

• Cookie 认证（默认方案）：用于 Web 界面登录
• OpenIddict Server：用于 OAuth2/OIDC

令牌配置：

• 访问令牌生命周期：24 小时
• 使用引用令牌（Reference Tokens）
• 支持刷新令牌

---

架构分析：2026-02-28