OneUptime 面板（Dashboard）创建与编排实战指南：画布布局、Widget 配置、阈值与刷新机制全解析

OneUptime 面板（Dashboard）创建与编排实战指南：画布布局、Widget 配置、阈值与刷新机制全解析

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

OneUptime 的 Dashboard（面板）模块把平台已经采集的指标、日志、追踪、事件、监控器与基础设施数据汇聚到单一页面，供值班、复盘或对外展示时一眼掌握系统状态。本文以官方文档《Crear un Panel》（创建面板）为骨架，结合仓库源码展开，带你完整掌握从创建面板、理解网格画布、添加与配置 Widget、设置数据源与阈值，到时间范围、自动刷新与长期维护设计的一整套实战方法。

快速上手：创建你的第一个面板

在左侧导航中打开Paneles → Crear Panel（Dashboards → Create Dashboard），为面板起一个名字并打开它。画布会默认进入Edición（编辑）模式，随时可以开始往里面添加 Widget。

在数据模型层面，面板在仓库中对应Dashboard模型（Common/Models/DatabaseModels/Dashboard.ts），它承载了面板的名称、描述、所属项目（projectId）、标签（labels）、视图配置（DashboardView）以及 Logo、Favicon 等展示资源。前端列表页通过 DashboardElement.tsx 渲染每个面板的入口链接，点击后跳转到对应面板视图路由。可以说，面板是整个监控展示体系的“容器”，后续所有 Widget、变量、时间范围都挂载在它之上。

理解画布（Canvas）：网格布局机制

一个面板本质上是一张网格（grid）：

• Widget 会吸附到网格上：你决定每个 Widget 的位置与大小，它们会整齐地对齐，不会随意重叠或漂移。
• 页面可以向下生长：随着添加更多行，画布会持续向下扩展，没有固定的行数上限。
• 比例保持：每个 Widget 在大屏或小屏上都会保持自身宽高比例，因此同样一份面板在壁挂大屏、桌面浏览器和移动端都能保持可读。

从源码看，画布核心逻辑位于 App/FeatureSet/Dashboard/src/Components/Dashboard/Canvas/Index.tsx，它负责 Widget 的摆放、尺寸调整与配置弹窗（ComponentSettingsModal.tsx）的渲染。拖拽移动与拖角缩放是画布的两个基础交互，在编辑模式下始终可用。

编辑模式与查看模式

面板头部有一个开关，用于在两种模式之间切换：

• Edición（编辑）— Widget 调色板打开，可以拖拽 Widget、调整大小，点击任意 Widget 即可修改其配置。
• Vista（查看）— 面板变为只读，与访问者和其他团队成员看到的效果完全一致。分享之前先用它预览成品。

两个模式操作的是同一个面板，不存在独立的“发布”步骤——每次编辑在保存的瞬间即生效，是一种“所见即所得、改了即上线”的实时工作流。

添加与配置 Widget

向面板添加 Widget 的标准流程：

1. 点击+按钮打开 Widget 调色板（Palette）。
2. 选择 Widget 类型。完整目录参见 Widgets 文档。
3. Widget 随即出现在画布上。
4. 点击 Widget 上的齿轮图标打开它的配置面板。
5. 选择数据源（一条指标、一个列表过滤器、一段文本等）以及展示选项。
6. 拖拽 Widget 移动位置；拖拽角落调整大小。

从源码看，所有 Widget 类型统一由枚举DashboardComponentType定义（Common/Types/Dashboard/DashboardComponentType.ts），覆盖图表（Chart）、数值（Value）、文本（Text）、时钟（Clock）、表格（Table）、仪表盘（Gauge）、日志流/日志图（LogStream/LogChart）、追踪列表（TraceList）、事件与告警列表（IncidentList/AlertList）、监控器列表（MonitorList）、SLO、Kubernetes 与 Docker 各类资源列表、宿主机列表、网络地图（NetworkMap）、HTML 自定义组件等几十种类型。配置面板中的表单（ArgumentsForm.tsx）会根据所选组件类型动态渲染对应的参数输入项。

数据从哪来：Widget 的三大数据源

大多数 Widget 从以下三种来源读取数据：

• 指标（Métricas）— 选择一条指标并指定聚合方式（平均值 average、最大值 max、计数 count、百分位 percentile），可添加过滤器，并选择结果如何分组。这套查询构建器与 OneUptime 其他位置使用的是同一个，学习一次即可到处使用。
• 实时列表（Listas en vivo）— 事件（incidentes）、告警（alertas）、监控器（monitores）、Kubernetes Pod、Docker 容器、宿主机等。每个列表 Widget 接收一个过滤器，并实时展示匹配的元素。
• 静态内容（Contenido estático）—Texto（文本）Widget 接收一段 Markdown，适合用作标题、上下文说明、指向 Runbook 的链接，或事件处置期间的临时备注。

此外，源码中的DataSourceComponentTypes（DashboardComponentType.ts）还揭示了第四类特殊来源：外部数据源组件（DataSourceChart、DataSourceValue、DataSourceGauge、DataSourceTable），它们直接读取 Prometheus、SQL、ClickHouse、Loki、Elasticsearch、REST 等外部数据源而非 OneUptime 自身的遥测数据；这些组件类型被独立设计、各自携带专属查询编辑器，且在公开面板（public dashboards）上不可用，以免向匿名访客暴露项目数据聚合。

阈值与格式化

单值类 Widget（Valor 数值、Indicador 仪表盘）支持两类阈值：

• 警告阈值（Umbral de advertencia）— 当数值越过阈值时颜色变为黄色。
• 严重阈值（Umbral crítico）— 当数值越过阈值时颜色变为红色。

颜色变化是单向跨越触发的（“超过即变色”），因此你可以把“1% 错误率=黄色、5% 错误率=红色”这类规则直接编码进面板。

图表类 Widget允许配置 Y 轴单位、图例（legend）的位置，并决定多条序列是**堆叠（stack）还是叠加（overlay）**展示。表格类 Widget则允许选择要显示的列以及行数上限。

时间范围与自动刷新

面板顶部有两个全局控件，影响每一个基于时间的遥测 Widget：

• Rango de tiempo（时间范围）— 使用预设（最近 1 小时、24 小时、7 天、30 天）或自定义范围。每个图表和数字都使用这个窗口。
• Actualización（刷新）— Widget 重新查询数据的频率，可选关闭、5s、10s、30s、1m、5m、15m。实时列表（Live lists）不受此设置影响，它们按自身机制持续更新。

不使用时间范围的 Widget（如Texto 文本Widget）会同时忽略这两个控件。需要特别注意的是，时间范围会编码在面板 URL 中——分享链接即分享时间窗口，事件处置时把“今天 10:00–10:30 UTC”固定下来再粘贴到事件频道，是非常实用的做法。

在查看模式下，你还可以框选缩放（zoom into a spike）：在任意折线图或面积图上拖拽选中一段感兴趣的区域，整个面板都会移动到该时间窗口——所有其他图表会一起重新查询，保证你在同一时刻横跨多个面板阅读数据，而不是看一张张尺度各异的图。双击任意图表即可撤销缩放，恢复到缩放前的范围；缩放激活期间时间选择器旁会出现Reset zoom按钮。需要留意：缩放后的窗口是固定的，自动刷新开启时它不会继续向前滚动（这是刻意设计，避免调查中途窗口溜走）；重置缩放后滚动恢复。缩放只在查看模式下生效——编辑模式下拖拽是移动/缩放 Widget。柱状图（bar chart）不能发起缩放（没有可拖拽的区域），但双击它仍然可以重置面板。

自动保存与安全备份

画布在工作过程中自动保存。面板头部有一个小指示器，告诉你最近一次变更何时已落盘。如果要进行大规模改动，先复制（duplicate）一份面板作为安全副本再动手，这是官方文档明确建议的防失误做法。

让面板历久弥新的四条设计建议

官方文档给出了一组经过实践检验的编排原则：

1. 一个面板一个主题。抵制把“我们监控的一切”塞进同一页的冲动。几个聚焦的面板远胜一个巨型页面。
2. 把最重要的 Widget 放在顶部。人们习惯自上而下浏览——让第一眼看到的就是“这个系统健康吗”的答案。
3. 用 Text Widget 标注区块。每隔几行放一个简短标题（“Latency 延迟”“Errors 错误”“Capacity 容量”），让整页在房间另一端也能一眼扫清。
4. 用变量代替复制。如果你正准备为第二个服务构建同样的面板，改为构建一个带service变量的面板。详细机制参见 Variables y Filtros（变量与过滤器）——一个带service下拉框的面板，就能同时服务checkout、payments、search等所有服务，而无需复制三份近乎相同的面板。

从源码看 Widget 全景：一份可对照的类型清单

为了让面板编排时对可用 Widget 胸有成竹，这里把 DashboardComponentType 枚举中的主要类型按数据源归类整理（与 Widgets 目录文档一一对应）：

绝大多数生产面板都是混合编排：顶部一个趋势图，旁边一两个单值，中间一条文本分隔线，下方一到两个列表。

延伸阅读

面板编排只是整个 Dashboard 体系的入口，官方文档（对应西班牙语版本）提供了完整的后续学习路径：

• Widgets 目录 — 每个 Widget 展示什么、何时使用。
• Variables y Filtros（变量与过滤器） — 让一个面板复用于多个服务或客户。
• Compartir y Paneles Públicos（分享与公开面板） — 在团队之外分享面板。
• Configuración y Permisos（配置与权限） — 属主与访问控制。

若需深入源码，可继续阅读 DashboardComponentType.ts（Widget 类型全集）、Dashboard.ts（面板数据模型）以及 Canvas 组件目录（画布与配置表单实现）。

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