fengling-gateway/.planning/codebase/STACK.md

YARP 网关技术栈文档

1. 语言和运行时

.NET 版本

• 目标框架: .NET 10.0
• 项目文件: src/YarpGateway.csproj
• SDK: Microsoft.NET.Sdk.Web

<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

{
  "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

# 基础镜像
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 集群部署