OneUptime 仪表盘编排完全指南：画布、组件、时间范围与自动刷新-平芜编程栈

OneUptime 仪表盘编排完全指南：画布、组件、时间范围与自动刷新

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

本指南以 OneUptime 开源可观测平台（Open-source monitoring and observability platform）的 Dashboard 编排功能为核心，讲解从创建仪表盘、操作网格画布、添加与配置组件，到时间范围、自动刷新、拖拽缩放与自动保存的完整工作流。读完本文，你将掌握 OneUptime 仪表盘的编辑/查看双模式、组件数据源体系（指标、日志、追踪、实时列表、静态内容）、阈值与格式化配置，以及让仪表盘长期可维护的设计技巧，并能结合仓库源码理解其底层实现原理。

创建仪表盘：进入画布的起点

在 OneUptime 左侧导航打开Dashboards，点击Create Dashboard新建仪表盘，为其命名后即可进入画布。画布默认处于Edit（编辑）模式，随时可以开始添加组件。

从源码结构看，仪表盘的页面级入口位于 App/FeatureSet/Dashboard/src/Pages/Dashboards/View/，其中Index.tsx、Layout.tsx承载画布外壳，Overview.tsx展示描述、属主与标签，而画布的核心交互逻辑集中在 App/FeatureSet/Dashboard/src/Components/Dashboard/Canvas/ 目录下。

画布机制：一个网格系统

OneUptime 的仪表盘本质上是一个网格（grid）：

组件会吸附（snap）到网格上，位置与大小由你决定；
随着添加更多行，页面可以向下无限增长；
每个组件在更大或更小的屏幕上都会保持自身比例，不会因为容器尺寸变化而变形。

网格的源码实现

在 App/FeatureSet/Dashboard/src/Components/Dashboard/Canvas/Index.tsx 中可以看到网格的具体实现细节：

编辑模式下，画布在最底部组件之下额外保留 4 行缓冲区域（EDIT_MODE_BUFFER_ROWS = 4），同时画布至少显示 12 行（EDIT_MODE_MIN_ROWS = 12），保证空画布也有足够的摆放空间；
列数由DefaultDashboardSize.widthInDashboardUnits决定，组件之间保留固定像素间距（SpaceBetweenUnitsInPx）；
画布通过ResizeObserver实时测量容器实际宽度，再据此反推每个网格单位的像素尺寸（unitSizeInPx），从而保证组件在所有屏幕宽度下都能获得精确的像素宽高；
拖拽与缩放能力由useDashboardGridDnd（位于Common/UI/Utils/UseDashboardGridDnd.ts）提供：拖动组件移动（move）、拖拽角落调整大小（resize），并通过GridLayoutUtil.applyRectsToComponents将网格坐标写回组件配置。

拖拽过程中会显示占位矩形（renderPlaceholder）：调整大小时显示“宽 × 高”（如4 × 3），移动时显示网格坐标（如2, 1），让你精确定位。

Edit 与 View：两种模式的切换

仪表盘顶部的切换开关控制两种模式：

Edit（编辑）——组件面板（widget palette）打开，可以拖拽组件、调整大小，点击任意组件打开设置；
View（查看）——仪表盘变为只读，与访客和团队成员看到的完全一致，适合在分享前检查效果。

两种模式操作的是同一个仪表盘，没有独立的“发布（publish）”步骤——每一次修改保存后立即生效，团队看到的始终是最新版本。

从 App/FeatureSet/Dashboard/src/Components/Dashboard/Canvas/Index.tsx 可以看到，拖拽交互（dnd）仅在isEditMode为真时启用，这也是 View 模式下画布不可编辑的源码依据。

添加一个组件

在画布上添加组件遵循以下步骤：

点击+按钮打开组件面板（widget palette）；
选择组件类型（完整目录见组件目录）；
组件出现在画布上；
点击组件上的齿轮图标打开其设置；
选择数据源（一个指标、一个列表过滤器、一段文本等）及显示选项；
拖动组件移动位置，拖动角落调整大小。

设置面板的源码构成

Canvas 目录下的编辑器文件印证了设置面板的能力边界：

ComponentSettingsModal.tsx——组件的设置弹窗，负责汇总渲染所有表单字段；
DataSourceQueryEditor.tsx——指标/数据源查询构建器；
LogChartQueryEditor.tsx、TraceChartQueryEditor.tsx——日志图与追踪图的专用查询编辑；
TelemetryAttributeVariableDropdown.tsx、ProjectLabelVariableDropdown.tsx——遥测属性变量与项目标签变量的下拉绑定；
TableColumnsEditor.tsx——表格列选择编辑器。

组件类型的完整定义可以在 Common/Types/Dashboard/DashboardComponents/ 中找到，包括DashboardChartComponent、DashboardValueComponent、DashboardGaugeComponent、DashboardTableComponent、DashboardTextComponent、DashboardHtmlComponent、DashboardLogChartComponent、DashboardLogStreamComponent、DashboardTraceListComponent、DashboardIncidentListComponent、DashboardAlertListComponent、DashboardMonitorListComponent、DashboardSloComponent、DashboardNetworkMapComponent以及各类 Kubernetes / Docker / Podman / Proxmox / VMware 资源列表组件。

数据从哪来：四种数据源

大多数组件从以下四个来源读取数据：

数据源	说明
Metrics（指标）	选择一个指标与聚合方式（average、max、count、percentile），添加过滤器，选择分组方式。这与 OneUptime 其他位置使用的是同一个查询构建器。
Logs and traces（日志与追踪）	按时间绘制日志量或追踪性能曲线，或以列表展示匹配的最近遥测数据。遥测组件可按服务、严重级别、正文文本与属性进行收窄。
Live lists（实时列表）	事件（incidents）、告警（alerts）、监控器（monitors）、Kubernetes Pod、Docker 容器、主机等。每个列表组件接受一个过滤器，展示匹配项并实时更新。
Static content（静态内容）	Text组件接受一段 Markdown。适合做标题、上下文说明、指向 runbook 的链接，或在事件处理期间放临时备注。

说明：以上组件分类覆盖完整目录。详细的每个组件的用途、设置项与适用场景，参见组件目录（含 Chart、Value、Gauge、Table、Text、HTML、Log Chart、Log Stream、Trace List、Incident List、Alert List、Monitor List、SLO、Kubernetes/Docker 资源列表、Host List、Network Map 等）。

阈值与格式化

Value（数值）与Gauge（仪表盘）这类单值组件支持设置两个阈值：

warning threshold（警告阈值）——数值超过后颜色变黄色；
critical threshold（严重阈值）——数值超过后颜色变红色。

图表（Chart）可以设置Y 轴单位、图例位置，以及序列是堆叠（stack）还是叠加（overlay）。表格（Table）可以选择要展示的列与行数上限。

时间范围与刷新

仪表盘顶部有两个控件，作用于每一个基于时间的遥测组件：

时间范围（Time range）

预设——过去 1 小时、24 小时、7 天、30 天（以及取决于数据保留期的 90 天）；
自定义——手动选择起止时间。

每一个指标、日志、追踪图表都使用这一时间窗口。时间范围会编码在仪表盘的URL中——分享 URL 即分享了时间窗口，非常适合事件处理期间固定窗口后把链接贴到事件频道。

刷新（Refresh）

组件重新查询数据的频率：

Off——页面加载时查询一次；
5s / 10s / 30s / 1m / 5m / 15m——按间隔自动刷新。

实时列表（Live lists）不受此设置约束，始终自行更新。不使用时间范围的组件（如 Text 组件）会忽略这两个控件。

刷新间隔的源码实现

刷新间隔的枚举与毫秒换算定义在 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", }

对应的毫秒值依次为 5000 / 10000 / 30000 / 60000 / 300000 / 900000。保存仪表盘时，DashboardView会把当前刷新间隔连同组件布局一起序列化（JSONFunctions.serializeValue）写入后端Dashboard模型的dashboardViewConfig字段，见 App/FeatureSet/Dashboard/src/Components/Dashboard/DashboardView.tsx。

放大到峰值：整板拖拽缩放

不需要为了观察一个峰值而手动去调整时间范围选择器：

在任意折线图或面积图上拖动选中感兴趣的时间段，整个仪表盘都会移动到该窗口——所有其他面板会随之重新查询，让你在同一时刻横跨整个面板读数，而不是逐张图表、各用不同比例地看；
双击任意图表即可撤销缩放：无论你钻取了多少次，仪表盘都会回到缩放前的时间范围；
缩放激活时，时间范围选择器旁会出现一个Reset zoom按钮；
双击一个未缩放的仪表盘不会有任何效果。

缩放的有意设计

缩放后的窗口是固定的，因此在自动刷新开启时它不会继续向前滚动——这是刻意为之：调查途中窗口若悄然滑走反而更糟。重置缩放后即恢复滚动；
缩放仅在工作于 View 模式；在 Edit 模式下拖动是移动/调整组件；
柱状图（bar chart）不能发起缩放（没有可拖拽的区域），但双击柱状图仍然可以重置整个仪表盘。

缩放的源码实现

整板缩放的逻辑由 Common/UI/Utils/UseDashboardTimeRangeZoom.ts 提供，它同时被认证版仪表盘（DashboardView）与公开仪表盘复用，保证两种入口的交互语义一致：

zoomToTimeRange(startTime, endTime)——由时间序列面板的拖选触发，把整板窗口收窄到选中区间；
resetZoom()——双击面板或点击工具栏的重置按钮，撤销缩放；
三个回调均保持 identity-stable，以便安全下传到被React.memo包裹的组件中而不产生过期闭包。

在 DashboardView.tsx 中，缩放回调被传入画布（onDashboardTimeRangeSelect/onDashboardTimeRangeReset/isDashboardTimeRangeZoomed）；在 Canvas/Index.tsx 的接口注释中可以看到，这是“由仪表盘外壳持有的、整板级别的拖拽缩放”。相关交互还配有测试覆盖，见 App/Tests/Dashboard/DashboardTimeRangeZoomWiring.test.ts 与 App/Tests/Dashboard/DashboardCanvasLayering.test.ts。

保存：边工作边自动落盘

画布随工作自动保存。头部有一个小的指示器，显示最新更改是否已保存。

从 App/FeatureSet/Dashboard/src/Components/Dashboard/DashboardView.tsx 的实现可以看出几个细节：

保存通过ModelAPI.updateById将序列化后的dashboardViewConfig写入Dashboard模型；
保存前会做编辑权限校验（canEditDashboard），权限不足时停留在编辑模式并提示缺失权限信息；
保存失败不会丢失已放置的组件：错误信息单独展示（saveError），画布保持在编辑模式，用户的工作仍然留在屏幕上，而不是被整个页面错误提示覆盖。

如果要做一个大的改动，建议先复制（duplicate）仪表盘再动手，这样始终有一个安全的备份副本。

让仪表盘经得起时间考验的技巧

官方文档在 authoring.md 中给出的四条长期维护建议：

一个仪表盘一个主题——拒绝把“我们监控的一切”塞进一页。几个聚焦的仪表盘胜过一张巨型页面；
最重要的组件放在最顶部——人们从上往下扫视，让第一眼看到的内容直接回答“系统健康吗？”；
用 Text 组件给分区加标题——每隔几行放一个短标题（“Latency”“Errors”“Capacity”），让整页可以一眼扫读；
用变量代替复制——如果正准备为第二个服务复制同一张仪表盘，请改为构建一张带service变量的仪表盘。详见变量与过滤器（支持 Custom List、Text Input、Telemetry Attribute、Project Labels 等变量类型与多选、默认值机制）。