企业官网建设流程全解析

OneUptime 仪表盘完全指南：把指标、日志、事件与基础设施汇聚到同一屏

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

本文基于 OneUptime 官方文档《Dashboards – 概览》，系统讲解仪表盘（Dashboard）的设计目标、可放置的组件类型、核心概念术语、在界面中的位置、从零搭建到公开分享的完整流程，并结合仓库源码剖析其模式切换、组件类型枚举、变量机制与自动刷新配置等实现细节，帮助读者掌握“一屏掌握系统健康状况”的实战能力。

一、仪表盘解决什么问题

OneUptime 的仪表盘（Dashboard）把平台已经收集到的各类数据——指标（Metrics）、日志（Logs）、链路追踪（Traces）、事件（Incidents）、监控器（Monitors）、Kubernetes 资源、主机（Hosts）——汇聚到同一个页面上，让人用一眼就能看出系统当前发生了什么。

典型的组合方式：在页面上放置一个请求延迟图表，旁边放一个未关闭事件列表，再放一个 CPU 数值显示和一个带上下文说明的文本块，保存后即可通过链接分享。

具体来说，仪表盘适合以下四类场景：

• “一切正常吗”看板——面向值班轮岗（Rufbereitschaft）、每日站会或墙上的大屏电视；
• 发现关联——CPU 峰值、延迟升高、未关闭事件这三者同时出现在同一页面上，比分散在三个标签页里更容易被察觉；
• 问题排查——分析故障时，临时拼出来的一个仪表盘往往优于连续执行十条独立查询；
• 对外分享——面向客户的性能页、合作伙伴状态区，或开源项目的公开仪表盘。

二、仪表盘中可放置的组件

文档列出的可放置组件分为五类，它们与仓库源码中的组件类型枚举一一对应：

从源码结构看，Common/Types/Dashboard/DashboardComponentType.ts中的DashboardComponentType枚举定义了全部 50 余种组件类型，覆盖：

• 基础可视化：Chart、Value、Text、Clock、Table、Gauge；
• 外部数据源组件：DataSourceChart、DataSourceValue、DataSourceGauge、DataSourceTable——源码注释明确说明，这些组件读取的是外部数据源（Prometheus、SQL、ClickHouse、Loki、Elasticsearch、REST），而非 OneUptime 自身的遥测数据，且在公开仪表盘中不可用；
• 日志与追踪：LogStream、LogChart、TraceList、TraceChart、TraceTable；
• 运维实时列表：IncidentList（事件列表）、AlertList（告警列表）、MonitorList（监控器列表）；
• SLO：Slo、SloList；
• 云原生与基础设施：KubernetesPodList等 8 种 K8s 工作负载/节点列表、DockerHostList等 5 种 Docker 列表、PodmanHostList等 5 种 Podman 列表、ProxmoxNodeList、VMwareHostList、DockerSwarmNodeList、CephOsdList、CephPoolList、HostList；
• 其他：NetworkMap（网络地图）、Html、安全事件流等。

每种组件类型在Common/Types/Dashboard/DashboardComponents/目录下都有独立的接口定义文件（如DashboardChartComponent.ts、DashboardIncidentListComponent.ts），每种组件可携带的数据源、查询编辑器和渲染配置各不相同。完整的组件清单（每个组件显示什么、何时选用）见仓库文档 widgets.md。

三、核心概念术语表

文档给出了六个关键术语的定义，这也是理解整个模块的骨架：

这些术语在源码中都有精确对应：

模式：编辑与查看

Common/Types/Dashboard/DashboardMode.ts只定义了两个枚举值，印证了文档的二分法：

enum DashboardMode { Edit = "Edit", View = "View", }

变量：五种类型

Common/Types/Dashboard/DashboardVariable.ts中，变量并非只是简单的下拉框，而是支持五种类型：

export enum DashboardVariableType { CustomList = "Custom List", // 自定义列表（逗号分隔的值） Query = "Query", // 通过 ClickHouse 查询动态填充选项 TextInput = "Text Input", // 文本输入 TelemetryAttribute = "Telemetry Attribute", // 绑定某个 OTel 属性键 ProjectLabel = "Project Labels", // 项目标签 }

其中TelemetryAttribute类型最有特色：变量绑定一个 OpenTelemetry 属性键（例如k8s.cluster.name），渲染时所选值会注入到任何针对该属性键的组件过滤条件中，选项则从当前时间范围内该属性的去重值中获取。变量还支持多值选择（isMultiSelect）与默认值（defaultValue）。

自动刷新：七档间隔

文档说“刷新频率是关闭、每几秒或每几分钟”，源码Common/Types/Dashboard/DashboardViewConfig.ts给出了完整的七档配置：

export enum AutoRefreshInterval { OFF = "off", FIVE_SECONDS = "5s", TEN_SECONDS = "10s", THIRTY_SECONDS = "30s", ONE_MINUTE = "1m", FIVE_MINUTES = "5m", FIFTEEN_MINUTES = "15m", }

getAutoRefreshIntervalInMs()将枚举转换为毫秒（off返回null表示不刷新）。该配置存储在仪表盘视图配置对象中：

export default interface DashboardViewConfig { _type: ObjectType.DashboardViewConfig; components: Array<DashboardBaseComponent>; // 页面上所有组件 heightInDashboardUnits: number; // 栅格高度（以“仪表盘单位”计） refreshInterval?: AutoRefreshInterval | undefined; // 自动刷新间隔 variables?: Array<DashboardVariable> | undefined; // 页面级变量 }

前端在App/FeatureSet/Dashboard/src/Components/Dashboard/DashboardView.tsx中消费该配置：页面加载时若config.refreshInterval存在则写入本地状态，随后以getAutoRefreshIntervalInMs(...)返回的毫秒值驱动周期性重新查询。也就是说，刷新间隔是页面级配置，作用于所有组件——这与术语表中“时间范围只设置一次、所有图表共用”的设计一致。

四、在哪里找到仪表盘

打开左侧导航中的Dashboards入口，文档描述了六个页面及其用途：

五、搭建一个仪表盘：六步流程

文档给出的标准流程如下，每步都结合源码补充了背景：

1. 创建——起一个名称，工作区以空白状态打开（对应一个空的components数组）；
2. 添加组件——选择组件类型、配置其数据源、拖拽到期望位置（每个组件的位置与尺寸由Common/Types/Dashboard/ComponentPosition.ts和ComponentSize.ts描述）；
3. （可选）添加变量——例如添加一个service下拉框，让同一个仪表盘适用于每个服务；
4. 设置时间范围——预设值通常够用，之后可微调；
5. （可选）公开分享——在设置中打开开关，按需加密码或 IP 访问白名单；
6. （可选）自定义域名——把仪表盘托管到status.ihre-domain.de之类的自有域名上。

关于公开分享，从源码可以确认其安全边界：Common/Server/Services/DashboardService.ts在读取仪表盘时会检查isPublicDashboard标志（未公开则拒绝匿名访问），Common/Server/API/DashboardAPI.ts对所有公开仪表盘接口统一套用了publicDashboardRateLimit限流中间件。这解释了 widgets 文档中的多处限制：外部数据源组件和 Log 聚合图表在公开仪表盘中不可用，SLO 组件仅对外发布当前数值而绝不泄露其定义（监控的监控器、查询、评估周期）。

六、实战示例：Checkout 服务的值班页

文档给出了一个完整的小案例，目标是给 Checkout 服务做一个值班页，包含延迟、错误率、未关闭事件和一个实时日志流：

1. 创建一个名为“Checkout 值班”的仪表盘；
2. 添加变量service，默认值checkout；
3. 添加一个图表组件，查询 P95 延迟，过滤条件引用变量service；
4. 旁边放一个数值组件展示错误率，1% 触发黄色警告、5% 触发红色严重；
5. 下方放一个事件列表组件，过滤带checkout标签的事件；
6. 再下方放一个日志流组件，显示同一服务的日志；
7. 保存。把顶部下拉框切换到payments——同一个仪表盘现在展示的就是 Payments 服务。

这个示例完整演示了“变量驱动复用”的核心思想：组件中的过滤条件不写死服务名，而是引用页面级变量，切换下拉框即整体刷新。结合DashboardVariable接口可以看到，这类变量的attributeKey或名称会在渲染时注入各组件的过滤条件中，且切换取值会触发重新渲染。

七、仪表盘在 OneUptime 全局中的位置

文档用四条边界说明仪表盘与其他模块的关系，理解这些边界可以避免职责混淆：

• 监控器与遥测是数据源。你收集的每一条指标、每一行日志、每一个 Trace，都可以在某个组件中被查询——这是所有Chart、Value、LogChart、TraceChart组件的数据基础；
• 事件与告警通知是只读的。IncidentList、AlertList组件只负责展示；事件的创建与更新在其他地方完成。从源码结构看，DashboardIncidentListComponent.ts等列表组件只定义过滤与展示字段，不包含任何事件状态修改逻辑，印证了“仪表盘只读”这一原则；
• 状态页与仪表盘互补而非替代。状态页（StatusPage）是面向客户的外部沟通（“系统正常吗”），仪表盘用于内部深入查看系统行为细节。仓库中App/FeatureSet/StatusPage/与App/FeatureSet/Dashboard/正是两个独立的功能模块；
• 工作流是行动的手段，仪表盘是观察的手段。OneUptime 用工作流（Workflow）来执行处理动作，用仪表盘来呈现正在发生什么。

八、延伸阅读

以下姊妹文档与本篇互为补充，均位于App/FeatureSet/Docs/Content/de/dashboards/目录：

• Dashboard 创建（authoring）——如何使用工作区、编辑组件；
• 组件清单（widgets）——全部组件的完整列表、每个组件的设置项与适用场景，以及“该用哪个组件”的速查规则；
• 变量与过滤（variables）——让一个仪表盘复用于多个服务或客户；
• 分享与公开仪表盘（sharing）——公开 URL、密码、IP 白名单、自定义域名；
• 配置与权限（configuration）——所有者、标签、访问控制。

此外，前端工作区的实现入口在 Dashboard 视图组件 中，可结合Common/Types/Dashboard/下的类型定义继续深入阅读。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime