189 lines
4.9 KiB
Markdown
189 lines
4.9 KiB
Markdown
# YARP 网关技术栈文档
|
||
|
||
## 1. 语言和运行时
|
||
|
||
### .NET 版本
|
||
- **目标框架**: .NET 10.0
|
||
- **项目文件**: `src/YarpGateway.csproj`
|
||
- **SDK**: `Microsoft.NET.Sdk.Web`
|
||
|
||
```xml
|
||
<TargetFramework>net10.0</TargetFramework>
|
||
<Nullable>enable</Nullable>
|
||
<ImplicitUsings>enable</ImplicitUsings>
|
||
```
|
||
|
||
## 2. 核心框架
|
||
|
||
### YARP (Yet Another Reverse Proxy)
|
||
- **包**: `Yarp.ReverseProxy`
|
||
- **用途**: 微服务 API 网关核心反向代理引擎
|
||
- **主要功能**:
|
||
- 动态路由配置
|
||
- 负载均衡策略
|
||
- 健康检查
|
||
- 请求转发
|
||
|
||
### ASP.NET Core
|
||
- **用途**: Web 应用宿主框架
|
||
- **特性**:
|
||
- 依赖注入 (DI)
|
||
- 中间件管道
|
||
- 配置系统
|
||
- 日志集成
|
||
|
||
## 3. 主要依赖包
|
||
|
||
### 数据访问
|
||
| 包名 | 用途 |
|
||
|------|------|
|
||
| `Npgsql.EntityFrameworkCore.PostgreSQL` | PostgreSQL Entity Framework Core 提供程序 |
|
||
| `Microsoft.EntityFrameworkCore.Design` | EF Core 设计时工具（迁移） |
|
||
|
||
### 缓存与分布式锁
|
||
| 包名 | 用途 |
|
||
|------|------|
|
||
| `StackExchange.Redis` | Redis 客户端，用于分布式锁和缓存 |
|
||
|
||
### 认证授权
|
||
| 包名 | 用途 |
|
||
|------|------|
|
||
| `Microsoft.AspNetCore.Authentication.JwtBearer` | JWT Bearer 认证支持 |
|
||
|
||
### 日志
|
||
| 包名 | 用途 |
|
||
|------|------|
|
||
| `Serilog.AspNetCore` | Serilog ASP.NET Core 集成 |
|
||
| `Serilog.Sinks.Console` | 控制台日志输出 |
|
||
| `Serilog.Sinks.File` | 文件日志输出 |
|
||
|
||
### 服务发现（自定义包）
|
||
| 包名 | 用途 |
|
||
|------|------|
|
||
| `Fengling.ServiceDiscovery.Core` | 服务发现核心接口 |
|
||
| `Fengling.ServiceDiscovery.Kubernetes` | Kubernetes 服务发现实现 |
|
||
| `Fengling.ServiceDiscovery.Static` | 静态配置服务发现 |
|
||
|
||
## 4. 配置文件
|
||
|
||
### 主配置文件
|
||
**位置**: `src/appsettings.json`
|
||
|
||
```json
|
||
{
|
||
"ConnectionStrings": {
|
||
"DefaultConnection": "Host=...;Port=...;Database=...;Username=...;Password=..."
|
||
},
|
||
"Jwt": {
|
||
"Authority": "https://your-auth-server.com",
|
||
"Audience": "fengling-gateway",
|
||
"ValidateIssuer": true,
|
||
"ValidateAudience": true
|
||
},
|
||
"Redis": {
|
||
"ConnectionString": "host:port",
|
||
"Database": 0,
|
||
"InstanceName": "YarpGateway"
|
||
},
|
||
"Cors": {
|
||
"AllowedOrigins": ["http://localhost:5173"],
|
||
"AllowAnyOrigin": false
|
||
},
|
||
"Kestrel": {
|
||
"Endpoints": {
|
||
"Http": { "Url": "http://0.0.0.0:8080" }
|
||
}
|
||
},
|
||
"Serilog": {
|
||
"MinimumLevel": "Information",
|
||
"WriteTo": [
|
||
{ "Name": "Console" },
|
||
{ "Name": "File", "Args": { "path": "logs/gateway-.log", "rollingInterval": "Day" } }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 配置类
|
||
| 文件路径 | 类名 | 用途 |
|
||
|----------|------|------|
|
||
| `src/Config/JwtConfig.cs` | `JwtConfig` | JWT 认证配置 |
|
||
| `src/Config/RedisConfig.cs` | `RedisConfig` | Redis 连接配置 |
|
||
| `src/Config/ConfigNotifyChannel.cs` | `ConfigNotifyChannel` | PostgreSQL NOTIFY 通道常量 |
|
||
|
||
## 5. Docker 支持
|
||
|
||
### Dockerfile
|
||
**位置**: `Dockerfile`
|
||
|
||
```dockerfile
|
||
# 基础镜像
|
||
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
|
||
EXPOSE 8080
|
||
EXPOSE 8081
|
||
|
||
# 构建镜像
|
||
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
|
||
# 多阶段构建...
|
||
|
||
# 最终镜像
|
||
FROM base AS final
|
||
ENTRYPOINT ["dotnet", "YarpGateway.dll"]
|
||
```
|
||
|
||
### Docker 配置
|
||
- **默认目标 OS**: Linux
|
||
- **暴露端口**: 8080 (HTTP), 8081 (HTTPS)
|
||
- **工作目录**: `/app`
|
||
|
||
## 6. 项目结构
|
||
|
||
```
|
||
src/
|
||
├── Config/ # 配置类
|
||
│ ├── JwtConfig.cs
|
||
│ ├── RedisConfig.cs
|
||
│ ├── ConfigNotifyChannel.cs
|
||
│ ├── DatabaseRouteConfigProvider.cs
|
||
│ └── DatabaseClusterConfigProvider.cs
|
||
├── Data/ # 数据访问层
|
||
│ ├── GatewayDbContext.cs
|
||
│ └── GatewayDbContextFactory.cs
|
||
├── DynamicProxy/ # 动态代理配置
|
||
│ └── DynamicProxyConfigProvider.cs
|
||
├── LoadBalancing/ # 负载均衡策略
|
||
│ └── DistributedWeightedRoundRobinPolicy.cs
|
||
├── Middleware/ # 中间件
|
||
│ ├── JwtTransformMiddleware.cs
|
||
│ └── TenantRoutingMiddleware.cs
|
||
├── Models/ # 数据模型
|
||
│ ├── GwTenant.cs
|
||
│ ├── GwTenantRoute.cs
|
||
│ ├── GwServiceInstance.cs
|
||
│ └── GwPendingServiceDiscovery.cs
|
||
├── Services/ # 业务服务
|
||
│ ├── RouteCache.cs
|
||
│ ├── RedisConnectionManager.cs
|
||
│ ├── KubernetesPendingSyncService.cs
|
||
│ └── PgSqlConfigChangeListener.cs
|
||
├── Program.cs # 应用入口
|
||
├── appsettings.json # 配置文件
|
||
└── YarpGateway.csproj # 项目文件
|
||
```
|
||
|
||
## 7. 中间件管道
|
||
|
||
请求处理管道顺序（`Program.cs`）：
|
||
|
||
1. **CORS** - 跨域请求处理
|
||
2. **JwtTransformMiddleware** - JWT 解析与转换
|
||
3. **TenantRoutingMiddleware** - 租户路由解析
|
||
4. **Controllers** - API 控制器
|
||
5. **ReverseProxy** - YARP 反向代理
|
||
|
||
## 8. 托管与部署
|
||
|
||
### Kestrel 配置
|
||
- 监听地址: `http://0.0.0.0:8080`
|
||
- 支持 Docker 容器化部署
|
||
- 支持 Kubernetes 集群部署 |