Aspire Dashboard 深度指南分布式应用运行观测、安全加固与完整配置参考【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspireAspire Dashboard 是 .NET Aspire 的浏览器端可视化面板用于查看分布式应用运行时的资源清单、实时控制台日志与结构化遥测数据日志、追踪、指标。本文以仓库内 src/Aspire.Dashboard/README.md 为骨架结合 配置强类型定义、默认值填充逻辑 与 配置校验逻辑 等源码系统讲解 Dashboard 的启动方式、全部配置项、认证与安全加固要点以及遥测数据收集与退出机制帮助你在本地开发与生产部署场景下正确、安全地使用 Dashboard。一、Dashboard 是什么Aspire Dashboard 是一个浏览器端应用用于查看分布式应用distributed application的运行时信息。它展示三类核心数据资源Resources构成应用的 .NET 项目、可执行文件与容器等实时控制台日志Live console logs各资源的实时输出实时遥测Live telemetry结构化日志structured logs、追踪traces与指标metrics。从进程结构看Dashboard 的入口非常简洁Program.cs仅构造并运行一个DashboardWebApplication实例见 Program.cs所有启动、配置绑定、Kestrel 端点与认证管线的搭建都集中在 DashboardWebApplication.cs 中完成。二、安全注意事项必须前置了解Dashboard 会展示敏感信息包括资源配置、环境变量、控制台日志与遥测数据。因此只要 Dashboard 及其端点可能被可信本地开发环境之外的网络访问就必须对其进行安全加固。原文档给出的核心原则如下前端使用 HTTPS 并要求认证Dashboard 默认采用浏览器 Tokenbrowser token认证入站 OTLP 遥测必须认证使用 API Key 或客户端证书注意Standalone 模式默认接受未认证的遥测不要在不可信网络开启匿名访问任何能触达 Dashboard 的人都能查看敏感数据或提交遥测用网络控制限制 OTLP 端点访问不可信发送方可以伪造遥测或消耗 CPU、内存与网络带宽。遥测存储限制telemetry storage limits只降低内存占用并非请求速率或准入限制request rate/admission limits。对应源码实现PostConfigureDashboardOptions.PostConfigure中当配置了ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS时会一次性把Frontend.AuthMode、Otlp.AuthMode、Api.AuthMode全部置为Unsecured同时 UI 与日志会给出匿名访问的风险告警见 PostConfigureDashboardOptions.cs。三、配置总览三种配置来源Dashboard 在启动时完成配置配置内容包括前端与 OTLP 地址、资源服务端点、认证方式、遥测限制等。具体配置方式取决于它是由 Aspire AppHost 启动还是以 Standalone 模式独立运行。3.1 由 Aspire AppHost 启动AppHost 会自动完成 Dashboard 的配置一般无需手工干预。如需覆盖默认值推荐的做法是在launchSettings.json中添加环境变量。由于环境变量名不能包含:配置键中的冒号分隔符必须替换为双下划线__。例如配置项Dashboard:TelemetryLimits:MaxLogCount对应的环境变量是DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT3.2 Standalone 模式独立运行 Dashboard 时配置来源非常灵活支持命令行参数command line arguments环境变量同样用__替换:例如DASHBOARD__OTLP__AUTHMODE可选的 JSON 配置文件通过ASPIRE_DASHBOARD_CONFIG_FILE_PATH指定 JSON 配置文件路径。示例 JSON 配置文件与 README 中示例一致{ Dashboard: { TelemetryLimits: { MaxLogCount: 1000, MaxTraceCount: 1000, MaxMetricsCount: 1000 } } }源码验证在 DashboardWebApplication.cs 中如果指定了ASPIRE_DASHBOARD_CONFIG_FILE_PATH会以optional: false的方式加载该 JSON 文件文件不存在则直接启动失败如果指定了ASPIRE_DASHBOARD_FILE_CONFIG_DIRECTORY则通过AddKeyPerFile加载该目录下“每个文件一个配置键”的配置典型场景是 Docker secrets。两者都开启了reloadOnChange: true支持配置热更新。四、公共配置项Common configuration选项说明ASPNETCORE_URLS默认值http://localhost:18888Dashboard 前端对外提供 HTTP 服务的一个或多个端点。由 AppHost 启动时该地址会以 HTTPS 保护。建议对 Dashboard 启用 HTTPS。ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL默认值http://localhost:18889OTLP/gRPC 端点承载 OTLP 服务并以 gRPC 接收遥测。由 AppHost 启动时该地址会以 HTTPS 保护。ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL默认值http://localhost:18890OTLP/HTTP 端点承载 OTLP 服务并以 HTTP Protobuf 接收遥测。由 AppHost 启动时默认不配置该端点。ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS默认值false让 Dashboard 不使用认证并接受匿名访问等价于把Dashboard:Frontend:AuthMode、Dashboard:Otlp:AuthMode、Dashboard:Api:AuthMode全部设为Unsecured。开启前务必评估安全影响。ASPIRE_DASHBOARD_CONFIG_FILE_PATH默认值null可选 JSON 配置文件路径。在 Docker 容器中运行时指挂载卷内配置文件的路径。ASPIRE_DASHBOARD_FILE_CONFIG_DIRECTORY默认值nullDashboard 按“每个文件一个键”方式查找配置的目录可选。ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL默认值nullDashboard 连接资源数据所用的 gRPC 端点等价于Dashboard:ResourceServiceClient:Url。若不指定Dashboard 只展示遥测数据不显示资源列表与控制台日志。以上环境变量名的定义可在 KnownConfigNames.cs 中确认其中还保留了以DOTNET_DASHBOARD_*/DOTNET_RESOURCE_SERVICE_*开头的旧版Legacy别名用于兼容过渡。五、前端Frontend配置与浏览器 Token 认证前端端点认证由Dashboard:Frontend:AuthMode控制支持OpenID ConnectOIDC与浏览器 Token 认证两种安全方案。浏览器 Token 认证的工作方式向用户索要 TokenToken 可以在 UI 中输入也可以作为登录页的查询字符串传入例如https://localhost:1234/login?tTheTokenToken 校验通过后浏览器会持久化一个认证 Cookie并重定向到应用。选项说明Dashboard:Frontend:AuthMode默认值BrowserToken可选BrowserToken、OpenIdConnect或Unsecured。Unsecured只应在本地开发时使用不适合公网或生产托管。Dashboard:Frontend:BrowserToken默认值null指定浏览器 Token未指定时 Dashboard 会自动生成一个。自动化登录工具可以指定 Token 并携带查询字符串打开浏览器。每次启动 Dashboard 都应重新生成 Token。Dashboard:Frontend:MaxConsoleLogCount默认值10,000查看器保留的控制台日志条数上限达到上限后移除最旧的日志。Dashboard:Frontend:PublicUrl默认值nullDashboard 前端被访问的公网 URL用于构造指向它的链接。未指定时使用前端端点本身。当 Dashboard 经过代理访问且端点不可直接触达时此项很重要。Dashboard:Frontend:OpenIdConnect:NameClaimType默认值name用于展示认证用户全名的一个或多个 claim 类型支持逗号分隔列表。Dashboard:Frontend:OpenIdConnect:UsernameClaimType默认值preferred_username用于展示认证用户用户名的 claim 类型支持逗号分隔列表。Dashboard:Frontend:OpenIdConnect:RequiredClaimType默认值null授权用户必须携带的 claim缺失该 claim 则授权失败可选。Dashboard:Frontend:OpenIdConnect:RequiredClaimValue默认值null必须存在的 claim 的值仅在同时指定了RequiredClaimType时生效可选。Dashboard:Frontend:OpenIdConnect:ClaimActions默认值null配置在 OpenID Connect 选项上的 claim 动作列表每条包含ClaimType、JsonKey以及可选的SubKey、IsUnique、ValueType。Authentication:Schemes:OpenIdConnect:Authority默认值null身份提供方IdP的 URL。Authentication:Schemes:OpenIdConnect:ClientId默认值null依赖方RP的标识。Authentication:Schemes:OpenIdConnect:ClientSecret默认值null仅真实 RP 知晓的机密。Authentication:Schemes:OpenIdConnect:*的其他OpenIdConnectOptions属性默认值null该配置段下的其他值都会绑定到OpenIdConnectOptions例如Scope。反向代理场景当使用OpenIdConnect且前端位于终止 SSL 的反向代理之后时可能需要额外配置检查是否应设置ASPNETCORE_FORWARDEDHEADERS_ENABLEDtrue对应的配置名定义见 KnownConfigNames.cs 中的DashboardForwardedHeadersEnabled。源码层面的补充说明强类型FrontendOptions定义在 DashboardOptions.cs其中MaxConsoleLogCount默认值 10,000 与 AppHost 发布侧环形缓冲区的默认值保持一致Token 生成逻辑PostConfigureDashboardOptions在AuthMode BrowserToken且未提供 Token 时调用TokenGenerator.GenerateToken()自动生成并写回配置保证多实例 Options 读取到一致的 Token见 PostConfigureDashboardOptions.cs校验逻辑ValidateDashboardOptions要求BrowserToken模式必须有 TokenOpenIdConnect模式必须能解析出NameClaimType与UsernameClaimTypeUnsecured模式被明确提示仅限本地开发见 ValidateDashboardOptions.cs。六、OTLP 端点配置与认证OTLP 端点认证由Dashboard:Otlp:AuthMode控制支持API Key或客户端证书认证client certificate authentication。API Key 认证要求每个 OTLP 请求携带有效的x-otlp-api-key请求头其值需匹配主 Key 或次 Key 之一客户端证书认证使用 ASP.NET Core 证书认证校验 TLS 连接的客户端证书并可选地使用显式证书白名单。选项说明Dashboard:Otlp:AuthMode默认值Unsecured可选ApiKey、ClientCertificate或Unsecured。Unsecured只应在本地开发使用不适合公网托管。Dashboard:Otlp:PrimaryApiKey默认值null主 API Key。建议使用至少 128 位熵的密钥。AuthMode为ApiKey时必填。Dashboard:Otlp:SecondaryApiKey默认值null可选次 API Key指定后入站x-otlp-api-key可匹配主或次 Key用于平滑轮换。Dashboard:Otlp:SuppressUnsecuredMessage默认值false当AuthMode为Unsecured时抑制未安全告警消息。仅当外部前门代理保护了端点访问时才应设置。Dashboard:Otlp:AllowedCertificates默认值null允许的客户端证书白名单见下文“Allowed certificates”。Dashboard:Otlp:CertificateAuthOptions:*下的CertificateAuthenticationOptions属性默认值null该段下的值会绑定到CertificateAuthenticationOptions例如AllowedCertificateTypes。Allowed certificates证书白名单使用客户端证书认证时可通过Dashboard:Otlp:AllowedCertificates配置显式证书白名单。每条记录必须包含Thumbprint证书的 SHA256 指纹。若未配置白名单则所有通过 ASP.NET Core 证书校验的证书都能完成认证。示例 JSON 配置{ Dashboard: { Otlp: { AllowedCertificates: [ { Thumbprint: HEX_SHA256_THUMBPRINT } ] } } }源码层面的补充说明OtlpOptions与AllowedCertificateRule定义于 DashboardOptions.cs其中还包含GrpcEndpointUrl、HttpEndpointUrl与Cors子配置校验逻辑ValidateDashboardOptions.cs只在至少配置了一个 OTLP 端点时才校验认证模式ApiKey模式缺少PrimaryApiKey会报错ClientCertificate模式下每条白名单规则都必须有Thumbprint从源码可推断OTLP 端点本身是可选的“OTLP endpoints are optional - telemetry can be imported via the UI”也就是说遥测还可以通过 UI 导入而不必开启 OTLP 接收端点。七、OTLP CORS浏览器遥测跨域资源共享CORS可配置为允许浏览器应用向 Dashboard 发送遥测使用Dashboard:Otlp:Cors段配置允许的来源与请求头。选项说明Dashboard:Otlp:Cors:AllowedOrigins默认值null逗号分隔的允许来源列表可包含*通配符以允许任意域名可选。Dashboard:Otlp:Cors:AllowedHeaders默认值null逗号分隔的允许请求头列表可选。注意限制Dashboard 只支持以POST方法发送遥测不允许配置 CORS 的允许方法Access-Control-Allow-Methods。源码层面的补充说明OtlpCors类型DashboardOptions.cs中IsCorsEnabled仅在配置了AllowedOrigins时为真校验逻辑DashboardOptions.cs要求配置了 CORS 但未配置 OTLP HTTP 端点时会直接启动失败——因为 CORS 只对 OTLP/HTTP 有意义提示要么移除 CORS 配置要么指定ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL。八、Telemetry HTTP API 配置Dashboard:Api段配置 Dashboard 的 Telemetry HTTP API/api/telemetry/*端点。该 API默认开启并使用 API Key 认证未提供 API Key 时会在启动时自动生成一个。选项说明Dashboard:Api:Disabled默认值false禁用 Telemetry HTTP API 端点为true时端点不注册。可用环境变量ASPIRE_DASHBOARD_API_DISABLEDtrue禁用。Dashboard:Api:Enabled默认值true已弃用Deprecated改用Dashboard:Api:Disabled。为false时禁用 Telemetry HTTP API 端点。Dashboard:Api:AuthMode默认值ApiKey可选ApiKey或Unsecured。Unsecured只应在本地开发使用。Dashboard:Api:PrimaryApiKey默认值自动生成主 API Key。建议至少 128 位熵。AuthMode为ApiKey且未提供时启动时生成 128 位密钥。Dashboard:Api:SecondaryApiKey默认值null可选次 API Key。源码层面的补充说明ApiOptions中Enabled属性带[Obsolete]标记其 setter 会反向写入_disabledPostConfigureDashboardOptions中Disabled的优先级高于Enabled见 PostConfigureDashboardOptions.csAPI Key 自动生成与浏览器 Token 一样通过TokenGenerator.GenerateToken()生成并回写配置见 PostConfigureDashboardOptions.cs。九、资源服务Resource Service连接配置Dashboard 连接资源服务resource service以加载和展示资源信息客户端支持API Key与客户端证书认证。选项说明Dashboard:ResourceServiceClient:Url默认值nullDashboard 获取数据所连接的 gRPC 端点。未指定时 Dashboard 只显示遥测数据不显示资源列表或控制台日志。Dashboard:ResourceServiceClient:AuthMode默认值null可选ApiKey、Certificate或Unsecured。指定了资源服务 URL 后此项必填。Unsecured只应在本地开发使用。Dashboard:ResourceServiceClient:ApiKey默认值null以x-resource-service-api-key请求头发送给资源服务的 API Key。AuthMode为ApiKey时必填。Dashboard:ResourceServiceClient:ClientCertificate:Source默认值null可选File或KeyStore。AuthMode为Certificate时必填。Dashboard:ResourceServiceClient:ClientCertificate:FilePath默认值null证书文件路径Source为File时必填。Dashboard:ResourceServiceClient:ClientCertificate:Password默认值null证书文件的可选密码。Dashboard:ResourceServiceClient:ClientCertificate:Subject默认值null证书主题Source为KeyStore时必填。Dashboard:ResourceServiceClient:ClientCertificate:Store默认值My证书的StoreName。Dashboard:ResourceServiceClient:ClientCertificate:Location默认值CurrentUser证书的StoreLocation。源码层面的补充说明ResourceServiceClientOptions的TryParseOptions会解析 URL 合法性并缓存 API Key 的 UTF-8 字节见 DashboardOptions.cs校验逻辑ValidateDashboardOptions.cs仅在存在资源服务 URI 时校验认证Certificate模式必须指定Source且File必须有FilePath、KeyStore必须有Subject否则启动报错。十、遥测限制Telemetry Limits遥测数据保存在内存中。为避免内存过度占用Dashboard 对存储的遥测设置了限制。各类限制的淘汰策略不同日志Log、追踪Trace、指标Metric的保留限制存满后淘汰最旧的数据属性Attribute与 Span 事件span-event限制截断入站数据资源Resource限制达到上限后拒绝新资源的遥测。不同遥测类型的限制作用域不同MaxLogCount与MaxTraceCount跨所有资源共享MaxMetricsCount按资源per resource计算。选项说明Dashboard:TelemetryLimits:MaxLogCount默认值10,000日志条目数量上限跨资源共享。Dashboard:TelemetryLimits:MaxTraceCount默认值10,000追踪数量上限跨资源共享。Dashboard:TelemetryLimits:MaxMetricsCount默认值50,000指标数据点数量上限按维度per dimension计算。Dashboard:TelemetryLimits:MaxAttributeCount默认值128单条遥测上的属性数量上限。Dashboard:TelemetryLimits:MaxAttributeLength默认值null属性的最大长度。Dashboard:TelemetryLimits:MaxSpanEventCount默认值nullSpan 属性上的事件数量上限。Dashboard:TelemetryLimits:MaxResourceCount默认值10,000Dashboard 跟踪的资源数量上限。源码层面的补充说明TelemetryLimitOptionsDashboardOptions.cs中MaxAttributeLength与MaxSpanEventCount的实际默认值是int.MaxValue即默认不截断而 README 表中以null表达“无默认限制”MaxMetricsCount的注释显示 50,000 约可容纳“每秒 1 个指标点持续 12 小时以上”可作为容量规划的参考。十一、其他配置项选项说明Dashboard:ApplicationName默认值AspireUI 中显示的应用名。仅当未指定资源服务 URL 时生效存在资源服务时由资源服务指定应用名。Dashboard:UI:DisableResourceGraph默认值false禁用资源关系图resource graphUI。Dashboard:UI:DisableImport默认值false禁用遥测导入 UI。Dashboard:UI:DisableAgentHelp默认值false禁用 Dashboard 页头的AI Agents按钮为false时点击该按钮会打开一个对话框展示如何将 AI 编码代理与 Dashboard 配合使用的说明。源码层面的补充说明DashboardOptions中还包含 README 未展开的Data段Dashboard:Data:Directory数据目录与Dashboard:Data:PersistenceMode持久化模式取值None/Run/Resume以及DebugSession段调试端口、Token、服务端证书等对应定义见 DashboardOptions.cs 与 DashboardConfigNames.cs。持久化模式若解析失败会在启动校验阶段直接报错并给出合法取值列表。十二、配置的完整加载与校验链路将上文各节串联起来Dashboard 的配置生命周期如下对应 DashboardWebApplication.cs 与 ValidateDashboardOptions.cs构建配置源命令行参数、环境变量、可选的 JSON 文件ASPIRE_DASHBOARD_CONFIG_FILE_PATH、可选的 key-per-file 目录ASPIRE_DASHBOARD_FILE_CONFIG_DIRECTORY以及appsettings.json默认仅含AllowedHosts: *见 appsettings.json绑定强类型 OptionsDashboard配置段绑定到DashboardOptions并注册PostConfigureDashboardOptions与ValidateDashboardOptions填充默认值匿名开关ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS统一覆盖三段 AuthMode浏览器 Token 与 API Key 缺失时自动生成启动前校验前端 URL 必须配置、各 AuthMode 依赖项必须齐全、OTLP/CORS 组合必须合法、资源服务客户端证书来源必须与文件/存储方式匹配校验失败则打印错误并以非零退出码终止构建端点与中间件按解析后的绑定地址配置 Kestrel 端点并注册 OTLP gRPC 服务OtlpGrpcMetricsService、OtlpGrpcTraceService、OtlpGrpcLogsService见 DashboardWebApplication.cs、前端认证中间件Certificate / OpenIdConnect 等与 API 认证。十三、数据收集Data collection与退出机制软件可能收集你使用过程中的信息并发送给 Microsoft用于提供服务与改进产品。你可以按仓库说明关闭遥测。此外某些功能可能允许你或 Microsoft 从你的应用用户处收集数据若使用这些功能你必须遵守适用法律包括向应用用户提供适当通知并提供 Microsoft 隐私声明的副本。使用本软件即表示你同意这些做法。退出数据收集Opting outAspire Dashboard 的使用遥测仅当 Dashboard 通过 Visual Studio 或 Visual Studio Code 启动、作为运行中的 Aspire 应用一部分时才会被收集要为所有访问 Dashboard 的用户退出收集请将环境变量ASPIRE_DASHBOARD_TELEMETRY_OPTOUT设为true也可以在宿主 IDE 中禁用遥测收集。源码层面的补充说明DebugSessionOptions中提供了TelemetryOptOut布尔选项环境变量名对应DASHBOARD__DEBUGSESSION__TELEMETRYOPTOUT见 DashboardConfigNames.cs说明退出开关在调试会话配置层面也有对应的强类型入口。十四、实践建议小结本地开发直接由 AppHost 启动即可无需手工配置需要覆盖默认值时在launchSettings.json中以DASHBOARD__*双下划线形式注入环境变量。独立部署/容器化优先通过ASPIRE_DASHBOARD_CONFIG_FILE_PATH挂载 JSON 配置或用ASPIRE_DASHBOARD_FILE_CONFIG_DIRECTORY配合 Docker secrets 注入敏感配置如 API Key、证书指纹。安全底线不要在任何不可信网络开启Unsecured或ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUSOTLP 端点务必启用ApiKey或ClientCertificate认证并通过网络 ACL 限制来源前端务必启用 HTTPS 与BrowserToken/OpenIdConnect认证。容量规划按需调整TelemetryLimits日志/追踪默认 10,000、指标按资源 50,000并记住这些限制只约束内存占用不能替代速率限制与准入控制。如需查阅更多细节可继续深入 DashboardOptions.cs、PostConfigureDashboardOptions.cs、ValidateDashboardOptions.cs、DashboardWebApplication.cs 及配置名常量定义 KnownConfigNames.cs。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考