fengling/fengling-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 13 Wiki Activity
38f71d7274
fengling-platform/docs/yarp-configuration-model.md

293 lines
10 KiB
Markdown
Raw Blame History

# YARP 配置模型分析
**来源:** [microsoft/reverse-proxy](https://github.com/microsoft/reverse-proxy)
**日期:** 2026-03-03
---
## 核心概念
YARP (Yet Another Reverse Proxy) 的配置模型由三个核心接口/类组成：
1. **IProxyConfigProvider** - 配置数据源接口
2. **IProxyConfig** - 配置快照接口
3. **RouteConfig / ClusterConfig** - 路由和集群配置
```
┌─────────────────────────────────────────────────────────────┐
│ IProxyConfigProvider │
│ GetConfig() → IProxyConfig │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ IProxyConfig │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ RouteConfig[] │ │ ClusterConfig[] │ │
│ │ (路由规则) │ │ (集群配置) │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ ChangeToken: IChangeToken (配置变更通知) │
└─────────────────────────────────────────────────────────────┘
```
---
## 1. RouteConfig (路由配置)
路由定义了如何匹配传入请求并将其代理到集群。
### 核心字段
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `RouteId` | `string` | ✓ | 全局唯一路由标识 |
| `Match` | `RouteMatch` | ✓ | 请求匹配规则 |
| `ClusterId` | `string` | ○ | 目标集群 ID |
| `Order` | `int?` | ○ | 路由优先级 (数值越小优先级越高) |
| `AuthorizationPolicy` | `string?` | ○ | 授权策略名称 |
| `RateLimiterPolicy` | `string?` | ○ | 限流策略名称 |
| `TimeoutPolicy` | `string?` | ○ | 超时策略名称 |
| `CorsPolicy` | `string?` | ○ | CORS 策略名称 |
| `MaxRequestBodySize` | `long?` | ○ | 请求体最大大小 |
| `Metadata` | `IReadOnlyDictionary<string, string>?` | ○ | 自定义元数据 |
| `Transforms` | `IReadOnlyList<IReadOnlyDictionary<string, string>>?` | ○ | 请求/响应转换规则 |
### RouteMatch (匹配规则)
| 字段 | 类型 | 说明 |
|------|------|------|
| `Methods` | `IReadOnlyList<string>?` | HTTP 方法列表 (GET, POST 等) |
| `Hosts` | `IReadOnlyList<string>?` | Host 头匹配 (支持通配符) |
| `Path` | `string?` | 路径模式 (如 `/api/{**catch-all}`) |
| `Headers` | `IReadOnlyList<RouteHeader>?` | 请求头匹配规则 |
| `QueryParameters` | `IReadOnlyList<RouteQueryParameter>?` | 查询参数匹配规则 |
---
## 2. ClusterConfig (集群配置)
集群是一组等价的后端服务端点及其相关策略。
### 核心字段
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `ClusterId` | `string` | ✓ | 全局唯一集群标识 |
| `Destinations` | `IReadOnlyDictionary<string, DestinationConfig>?` | ○ | 目标端点字典 |
| `LoadBalancingPolicy` | `string?` | ○ | 负载均衡策略 |
| `SessionAffinity` | `SessionAffinityConfig?` | ○ | 会话亲和配置 |
| `HealthCheck` | `HealthCheckConfig?` | ○ | 健康检查配置 |
| `HttpClient` | `HttpClientConfig?` | ○ | HTTP 客户端配置 |
| `HttpRequest` | `ForwarderRequestConfig?` | ○ | 出站请求配置 |
| `Metadata` | `IReadOnlyDictionary<string, string>?` | ○ | 自定义元数据 |
### DestinationConfig (目标端点)
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `Address` | `string` | ✓ | 后端地址 (如 `https://127.0.0.1:8080/`) |
| `Health` | `string?` | ○ | 主动健康检查端点 |
| `Host` | `string?` | ○ | Host 头值 |
| `Metadata` | `IReadOnlyDictionary<string, string>?` | ○ | 自定义元数据 |
---
## 3. 负载均衡策略
YARP 内置以下负载均衡策略：
| 策略名称 | 说明 |
|----------|------|
| `RoundRobin` | 轮询 |
| `LeastRequests` | 最少请求 |
| `Random` | 随机 |
| `PowerOfTwoChoices` | 二选一 (推荐默认) |
| `First` | 第一个 |
| `WeightedRoundRobin` | 加权轮询 |
> **注意:** `WeightedRoundRobin` 需要在 Destination 的 Metadata 中配置 `Weight` 字段。
---
## 4. 健康检查配置
### HealthCheckConfig
```csharp
public sealed record HealthCheckConfig
{
public PassiveHealthCheckConfig? Passive { get; init; } // 被动健康检查
public ActiveHealthCheckConfig? Active { get; init; } // 主动健康检查
public string? AvailableDestinationsPolicy { get; init; } // 可用目标策略
}
```
### ActiveHealthCheckConfig (主动健康检查)
| 字段 | 类型 | 说明 |
|------|------|------|
| `Enabled` | `bool?` | 是否启用 |
| `Interval` | `TimeSpan?` | 检查间隔 |
| `Timeout` | `TimeSpan?` | 超时时间 |
| `Policy` | `string?` | 健康检查策略 |
| `Path` | `string?` | 健康检查路径 |
### PassiveHealthCheckConfig (被动健康检查)
| 字段 | 类型 | 说明 |
|------|------|------|
| `Enabled` | `bool?` | 是否启用 |
| `Policy` | `string?` | 策略名称 |
| `ReactivationPeriod` | `TimeSpan?` | 重新激活周期 |
---
## 5. 会话亲和配置
### SessionAffinityConfig
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `Enabled` | `bool?` | ○ | 是否启用 |
| `Policy` | `string?` | ○ | 策略 (Cookie, Header) |
| `FailurePolicy` | `string?` | ○ | 失败处理策略 |
| `AffinityKeyName` | `string` | ✓ | 亲和键名称 |
| `Cookie` | `SessionAffinityCookieConfig?` | ○ | Cookie 配置 |
---
## 6. 动态配置更新
### IProxyConfig 接口
```csharp
public interface IProxyConfig
{
string RevisionId { get; } // 配置版本 ID
IReadOnlyList<RouteConfig> Routes { get; }
IReadOnlyList<ClusterConfig> Clusters { get; }
IChangeToken ChangeToken { get; } // 配置变更通知
}
```
### 配置更新机制
1. **ChangeToken**: 当配置发生变化时，`ChangeToken` 会触发通知
2. **RevisionId**: 每次配置更新都会生成新的版本 ID
3. **YARP 内部**: 监听 `ChangeToken`，触发时重新加载配置
### 实现动态更新的方式
```csharp
public class CustomConfigProvider : IProxyConfigProvider
{
private volatile CustomProxyConfig _config;
public IProxyConfig GetConfig() => _config;
public void UpdateConfig(List<RouteConfig> routes, List<ClusterConfig> clusters)
{
var oldConfig = _config;
_config = new CustomProxyConfig(routes, clusters);
oldConfig.SignalChange(); // 触发 ChangeToken
}
}
```
---
## 7. 与现有实体的映射关系
### GwTenantRoute → RouteConfig
| GwTenantRoute 字段 | RouteConfig 字段 | 映射说明 |
|-------------------|------------------|----------|
| `Id` | `RouteId` | 直接映射 |
| `PathPattern` | `Match.Path` | 路径匹配模式 |
| `ClusterId` | `ClusterId` | 目标集群 |
| `Priority` | `Order` | 路由优先级 |
| `TenantCode` | `Metadata["TenantCode"]` | 租户标识 (元数据) |
| `ServiceName` | `Metadata["ServiceName"]` | 服务名称 (元数据) |
| `IsGlobal` | `Metadata["IsGlobal"]` | 全局路由标记 |
### GwServiceInstance → DestinationConfig
| GwServiceInstance 字段 | DestinationConfig 字段 | 映射说明 |
|-----------------------|------------------------|----------|
| `Address` | `Address` | 后端地址 |
| `Health` | `Health` | 健康检查端点 |
| `Weight` | `Metadata["Weight"]` | 权重 (加权负载均衡) |
| `DestinationId` | Dictionary Key | 目标字典的 Key |
### 多租户路由生成逻辑
```
for each GwTenantRoute:
routeId = $"{TenantCode}_{ServiceName}" or Id
routeConfig = new RouteConfig {
RouteId = routeId,
Match = new RouteMatch { Path = PathPattern },
ClusterId = ClusterId,
Order = Priority,
Metadata = { TenantCode, ServiceName, IsGlobal }
}
```
---
## 8. 实体结构对比与建议
### 当前实体 vs YARP 需求
| 方面 | 当前实体 | YARP 需求 | 差异 |
|------|----------|-----------|------|
| 路由匹配 | 只有 `PathPattern` | `Methods`, `Hosts`, `Headers`, `QueryParameters` | 缺少高级匹配 |
| 负载均衡 | 无配置 | `LoadBalancingPolicy` | 缺少策略配置 |
| 会话亲和 | 无配置 | `SessionAffinityConfig` | 缺少会话保持 |
| 转换规则 | 无配置 | `Transforms` | 缺少请求/响应转换 |
| 授权策略 | 无配置 | `AuthorizationPolicy` | 缺少授权配置 |
| 限流 | 无配置 | `RateLimiterPolicy` | 缺少限流配置 |
### 建议新增字段
**GwTenantRoute 新增:**
```csharp
// 匹配规则扩展
public string? Methods { get; set; } // GET,POST,PUT
public string? Hosts { get; set; } // api.example.com
// 策略配置
public string? LoadBalancingPolicy { get; set; } // RoundRobin, WeightedRoundRobin
public string? AuthorizationPolicy { get; set; } // 授权策略
public string? RateLimiterPolicy { get; set; } // 限流策略
public string? CorsPolicy { get; set; } // CORS 策略
// 转换规则 (JSON)
public string? Transforms { get; set; } // 请求/响应转换
// 会话亲和
public bool SessionAffinityEnabled { get; set; }
public string? SessionAffinityPolicy { get; set; } // Cookie, Header
public string? SessionAffinityKeyName { get; set; }
```
**GwServiceInstance 新增:**
```csharp
// 健康检查
public string? HealthCheckPath { get; set; } // /health
public int? HealthCheckInterval { get; set; } // 秒
// 主动健康检查端点
public string? HealthEndpoint { get; set; } // http://host:port/health
```
---
## 9. 参考资源
- [YARP 官方文档](https://microsoft.github.io/reverse-proxy/)
- [YARP GitHub 仓库](https://github.com/microsoft/reverse-proxy)
- [配置提供程序示例](https://github.com/microsoft/reverse-proxy/tree/main/samples)
- [Yarp.EfCore.Configuration](https://github.com/microsoft/reverse-proxy/tree/main/samples/Yarp.EfCore.Configuration) - EF Core 数据库配置示例
Reference in New Issue View Git Blame Copy Permalink