开箱即用的 YARP 管理面板：Aneiang.Yarp.Dashboard 架构与功能全解析

Aneiang.Yarp 源码解析系列篇 03可视化 DashboardYARP 本身不提供管理界面配置变更靠改 JSON 重启。Aneiang.Yarp.Dashboard 是一个嵌入式管理面板 —— 两行代码启用不依赖数据库不依赖前端构建工具NuGet 装完就能用。本文你会了解到Dashboard 如何用 Razor Class Library 打包成单个 DLL路由前缀如何通过 MVC Convention 动态注入日志采集管道的实现不依赖第三方日志框架配置快照与回滚机制四种认证模式的切换方式嵌入式架构一个 DLL 包含一切Dashboard 采用 ASP.NET Core 的Razor Class Library (RCL)技术Aneiang.Yarp.Dashboard.dll ├── wwwroot/ ← 静态资源CSS、JS作为嵌入资源 ├── Pages/ ← Razor Pages 页面 └── Controllers/ ← API 控制器为什么不用 Vue / React 做 SPA零前端构建步骤不需要 Node.js、Webpack、npm部署简单 —— 一个 DLL 包含所有内容升级方便 —— 升级 NuGet 包前端自动更新维护成本低 —— 没有前后端版本同步问题两行代码启用// 注册服务builder.Services.AddAneiangYarpDashboard();// 注册中间件UseRouting 之后、MapReverseProxy 之前app.UseAneiangYarpDashboard();AddAneiangYarpDashboard()内部完成1. 配置 RazorPages 2. 注册 DashboardOptions绑定 Gateway:Dashboard 配置节 3. 注册 5 个 Controller 4. 注册 DashboardRouteConvention路由前缀注入 5. 配置认证None / ApiKey / DefaultJwt / CustomJwt 6. 注册 ProxyLogStore内存日志存储 7. 可选AuthorizeRequest 自定义授权UseAneiangYarpDashboard()注册的中间件链请求进入 ├── YarpRequestCaptureMiddleware — 捕获经过网关的请求/响应 ├── MapDashboardEndpoints() — Razor Pages API └── MapReverseProxy() — YARP 代理必须最后路由前缀注入Dashboard 的所有端点都在/{prefix}下默认apigateway通过IApplicationModelConvention实现internalsealedclassDashboardRouteConvention:IApplicationModelConvention{publicvoidApply(ApplicationModelapplication){foreach(varctrlinapplication.Controllers){// 只处理 Dashboard 程序集中的 Controllerif(ctrl.ControllerType.Assembly!typeof(DashboardController).Assembly)continue;// 跳过已有前缀的 Controller防重复varexistingctrl.Selectors.FirstOrDefault(ss.AttributeRouteModel?.Template!null)?.AttributeRouteModel?.Template??;if(existing.StartsWith(_prefix,StringComparison.OrdinalIgnoreCase))continue;// 为每个 Action 的路由添加前缀foreach(varactioninctrl.Actions)foreach(varselectorinaction.Selectors)if(selector.AttributeRouteModel!null)selector.AttributeRouteModel.Template_prefix/selector.AttributeRouteModel.Template;}}}为什么用 Convention 而不是硬编码[Route(apigateway/...)]前缀可配置RoutePrefix选项Convention 自动适配Controller 代码干净不耦合前缀统一管理改一处全局生效配置管理快照与回滚ConfigManagementController提供完整的配置 CRUD 和版本管理。核心操作操作端点关键行为集群 CRUDPUT/DELETE /apigateway/api/config/clusters/{id}每次写操作前自动保存快照集群重命名PUT .../clusters/{id}/rename单次写锁内完成创建新集群 → 更新引用路由 → 删除旧集群路由 CRUDPUT/DELETE /apigateway/api/config/routes/{id}自动创建快照导入导出GET/POST .../config/export.../import标准 YARP 格式导入时自动校验回滚POST .../config/rollback/{versionId}全量替换当前配置历史GET .../config/history查看所有变更快照集群重命名是最复杂的操作 ——DynamicYarpConfigService.TryRenameCluster()在单次写锁内完成全部步骤任何一步失败则整体回滚。日志采集管道Dashboard 的日志采集不依赖任何第三方日志框架通过 YARP 的中间件和 Transform 实现请求进入网关 ├── YarpRequestCaptureMiddleware请求前 │ └── 记录 Method、Path、Headers、Body ├── YARP 反向代理 → 下游服务 │ └── DownstreamCaptureTransform响应后 │ └── 记录 StatusCode、响应 Headers、Body、耗时 └── YarpRequestCaptureMiddleware响应后 └── 组装完整日志 → ProxyLogStore内存环形缓冲关键设计中间件自动跳过 Dashboard 自身请求通过路径前缀判断避免日志污染。生产环境安全控制日志功能强大但生产环境要注意安全和性能配置项效果EnableLogSamplingLogSamplingRate: 0.1只记录 10% 的请求LogErrorsOnly: true只记录 4xx/5xxLogMaxBodyLength: 4096Body 超 4KB 截断LogHeaderBlacklist指定 Header 值替换为***REDACTED***LogJsonFieldSanitizeListJSON 中指定字段自动脱敏LogRouteWhitelist/LogRouteBlacklist按路由过滤支持 WebSocket 实时推送WebSocketLogController可以在 Dashboard 页面实时看到日志流。四种认证模式模式适合场景配置None本地开发零配置DefaultJwt个人 / 小团队配一个JwtPasswordCustomJwt企业项目自定义用户名 密码ApiKeyAPI 对接Header 传 API Key最常用的是DefaultJwt{Gateway:{Dashboard:{AuthMode:DefaultJwt,JwtPassword:demo123}}}还可以通过AuthorizeRequest委托接入自己的认证体系优先级最高builder.Services.AddAneiangYarpDashboard(options{options.AuthorizeRequestasync(context){returncontext.User.Identity?.IsAuthenticatedtruecontext.User.IsInRole(GatewayAdmin);};});端点一览页面路径说明/apigatewayDashboard 首页/apigateway/login登录/apigateway/clusters集群列表/apigateway/routes路由列表/apigateway/logs请求日志API路径说明/apigateway/api/config/export导出 YARP 配置/apigateway/api/config/import导入配置/apigateway/api/config/history变更历史/apigateway/api/config/rollback/{id}回滚/apigateway/api/config/clusters/{id}集群 CRUD/apigateway/api/config/routes/{id}路由 CRUD/apigateway/api/audit-logs审计日志设计亮点特性实现优势嵌入式部署Razor Class Library零构建步骤一个 DLL路由前缀可配IApplicationModelConvention灵活部署不硬编码配置快照写操作前自动保存改坏了一键回滚日志采集YARP 中间件 Transform不侵入业务代码多层脱敏Header / Query / JSON生产环境安全合规四种认证None / ApiKey / JWT / 自定义从开发到生产全覆盖多语言中英文运行时切换国际化友好源码地址GitHubhttps://github.com/AneiangSoft/Aneiang.YarpGiteehttps://gitee.com/aneiangsoft/aneiang-yarp)在线预览http://113.45.65.71:8930/apigatewayadmin / demo123dotnetaddpackage Aneiang.Yarp.Dashboard# Program.cs: builder.Services.AddAneiangYarpDashboard();# app.UseAneiangYarpDashboard();Aneiang.Yarp 源码解析系列觉得有用去 GitHub 或 Gitee 点个 Star 支持一下。