Aneiang.Yarp 2.3.0.20 发布一览：安全网关要塞正式登场

这是自项目发布以来规模最大的一次更新——WAF 防火墙、通知告警、健康检查与熔断面板、存储架构彻底重构、gRPC 双协议注册、SQLCipher 加密……从反向代理管道到生产级安全网关要塞的质变。

GitHub https://github.com/AneiangSoft/Aneiang.Yarp

Gitee https://gitee.com/aneiangsoft/aneiang-yarp

官方文档 https://yarp.aneiang.com

在线演示 https://yarp-test.aneiang.com/aneiang （账号 admin / demo123）

在这里插入图片描述

一句话总结

从"能代理"到"敢上生产"：2.3.0.20 用 WAF 防火墙 + 通知告警完成安全闭环，用接口隔离重构奠定可演进架构，用健康检查/熔断/限流三大面板实现全景可观测。

新增功能速览

WAF 防火墙 —— 网关内建的 Web 应用防火墙

在 YARP 代理管道前插入 424 行 WafMiddleware，零外部依赖，请求在进入反向代理前完成安全检查：

防护能力 详情
IP 黑白名单 精确 IP、CIDR 网段、通配符；白名单优先；预编译正则缓存
SQL 注入检测 2 组预编译正则（关键字 + 注入模式），5ms ReDoS 超时
XSS 检测 <script> 标签、javascript: 伪协议、事件处理器、eval 注入
路径遍历检测 ../、URL 编码变体、双重编码攻击
请求限制 请求体上限（10MB）、Header 数量/大小、URI 长度（4096）
安全响应头 自动注入 5 个安全头（CSP 可配置）
按路由控制 路由 Metadata 中 Waf:Enabled 精细控制

拦截时返回 403 JSON（含 waf:true 标记），安全事件环形缓冲区保留最近 1000 条，Dashboard 实时查看 + 攻击统计图表。

深入阅读：WAF 防火墙深入指南（05-waf-firewall-guide.md）

通知告警系统 —— 让事件即刻触达

多渠道 Webhook 告警 + 事件分发队列 + 冷却机制，构成完整的"烽火台"体系：

能力 详情
6 种事件类型 熔断器打开、重试耗尽、WAF 拦截、代理错误、限流触发、配置变更
多渠道 钉钉机器人（Markdown）、通用 HTTP Webhook（JSON）
冷却机制 每事件类型独立冷却时间，防止告警风暴
队列分发 ConfigChangeEventDispatcher（BackgroundService）200ms 轮询，不阻塞主流程
历史持久化 SQLite 存储 + Dashboard 分页查询
配置变更联动 路由/集群 CRUD 操作自动产生通知事件

深入阅读：通知告警系统深入指南（06-notification-guide.md）

三大可观测性面板

面板 功能
健康检查 集群/节点两级钻取、Unhealthy 红色标注、主动+被动双模式、DefaultHealthCheckService 启动自动配置
熔断器 Closed/Open/HalfOpen 三色可视化、失败次数 vs 阈值对比、恢复倒计时、一键重置
限流 固定窗口/滑动窗口/令牌桶/并发限制四种策略的实时指标（限制数、活跃请求、已拒绝数）

深入阅读：可观测性面板深入指南（08-observability-guide.md）

客户端注册：HTTP/gRPC 双协议

从 2.3.0.10 的纯 REST 升级为双协议架构：

增强 详情
gRPC 注册 GatewayRegistry.proto 定义标准化契约，GatewayRegistryService 服务端实现
指数退避重试 5 次重试（2s → 4s → 8s → 16s → 30s）
自动端口分配 gRPC 端口 = HTTP 端口 + 1；Kestrel 自动配置 HTTP/2 (h2c)
IP 自动解析 多源检测：Kestrel:EndPoints > Urls > ASPNETCORE_URLS
多认证 Bearer Token、Basic Auth、API Key
智能默认值 RouteName = 入口程序集名、MatchPath = /{**catch-all}

深入阅读：客户端双协议注册深入指南（09-client-grpc-guide.md）

数据库加密与下载

功能 详情
SQLCipher 加密 ConnectionString 加 Password=xxx 即可启用 AES-256 加密，对上层代码完全透明
数据库下载 Dashboard 设置页一键下载 .db 文件，方便 DB Browser 等工具离线分析

架构重构

Storage 模块接口隔离 —— 消灭上帝接口

这是 2.3.0.20 最深层的架构改进：

维度 重构前 重构后
仓储文件数 1 个（970 行上帝类） 8 个（平均 ~100 行）
接口粒度 IGatewayRepository（聚合 9 个子接口） 8 个独立接口
连接管理 各仓储自行管理 共享 SqliteConnectionFactory
建表时机 启动时一次性全量建表 懒加载（首次使用自动建表）
消费方依赖 注入上帝接口 按需注入 1-2 个子接口

6 个核心服务的依赖从"全量注入"缩减为"按需注入"，例如 DynamicYarpConfigService 从依赖上帝接口简化为只需 IRouteRepository + IClusterRepository。

深入阅读：存储架构重构深入指南（07-storage-architecture-guide.md）

启动预热机制

StartupWarmupService 通过 Task.WhenAll 并行预热 4 大模块（仓库建表、查询缓存、日志存储、通知种子），秒表计时 + 错误隔离，单模块失败不影响整体启动。

线程安全升级

DynamicYarpConfigService 将 ReaderWriterLockSlim（不支持 await）替换为 SemaphoreSlim(1,1)，解决异步方法内线程亲和性问题。WAF 设置、动态配置、通知设置统一采用双检锁缓存模式。

修复

修复项 详情
线程安全 ReaderWriterLockSlim → SemaphoreSlim(1,1)，解决异步上下文异常
元数据同步 TrySetRouteDisabled/TrySetClusterDisabled 修复内存元数据不同步 bug
编译二义性 ConfigPersistenceService 中 EntityMapper 与 ConfigEntityMapper 命名冲突修复
命名空间 SqliteConnectionFactory 的 StorageOptions 引用修正

移除的死代码（10+ 文件）

删除项 原因
IGatewayRepository 上帝接口，被 8 个独立接口替代
SqliteGatewayRepository（970 行） 上帝类，拆分为 8 个独立仓储
RedisGatewayRepositoryPlaceholder 所有方法抛 NotImplementedException
IDataStore / IStructuredDataStore 遗留抽象，已被独立仓储取代
IDynamicConfigPersistenceService 职责分散到 IRouteRepository + IClusterRepository
DynamicConfigPreloadService 合并入 StartupWarmupService
WebhookSettingsPreloadService 同上
GatewayRepositoryAdapter 适配器层不再需要
SqliteDataStore / RedisDataStore / StructuredSqliteStore 旧数据存储实现

国际化

新增 120+ 中英文 i18n 键值对，覆盖全部新增 UI：

  • WAF 防火墙：全局开关、检测规则、IP 名单、保存/加载状态
  • 通知告警：渠道管理、告警规则、高级设置、事件类型描述
  • 安全事件查看器
  • 健康检查面板：集群列表、目标节点、异常详情、状态标签
  • 熔断器面板：状态名称、操作确认、阈值显示
  • 限流面板：策略名称、窗口参数、统计数据
  • 数据库下载：按钮、描述、下载中/完成/失败提示

升级速查

NuGet 包

<PackageReference Include="Aneiang.Yarp" Version="2.3.0.20" />
<PackageReference Include="Aneiang.Yarp.Dashboard" Version="2.3.0.20" />
<PackageReference Include="Aneiang.Yarp.Client" Version="2.3.0.20" />
<PackageReference Include="Aneiang.Yarp.Grpc" Version="2.3.0.20" />  <!-- 新增：gRPC 场景 -->

新增配置节点

{
  "Gateway": {
    "Storage": {
      "Sqlite": {
        "ConnectionString": "Data Source=gateway-store.db"
      }
    },
    "Dashboard": {
      "Waf": {
        "Enabled": true
      }
    }
  }
}

代码迁移（如果直接引用了删除接口）

旧接口/类 替换为
IGatewayRepository IRouteRepository / IClusterRepository 等（按需）
IDataStore 独立仓储接口
DynamicConfigPreloadService StartupWarmupService（自动）

重要提示

  1. WAF 默认关闭，需登录 Dashboard 手动开启
  2. SQLCipher 密码丢失不可恢复，建议存储在环境变量或密钥管理中
  3. 中间件顺序必须正确：UseRouting → UseAneiangYarpDashboard
  4. gRPC 端口 = HTTP 端口 + 1，确保不被占用
  5. 首次启动执行 StartupWarmupService 并行预热，增加约 1-2 秒启动时间
  6. .db 文件路径相对于 ContentRootPath，Docker 部署需持久化卷
posted @ 2026-06-14 15:29  AneiangSoft  阅读(24)  评论(0)    收藏  举报