OneUptime 仪表盘组件（Widget）完全指南：从图表、HTML 沙箱到 Kubernetes 与 SLO 可视化

OneUptime 仪表盘组件（Widget）完全指南：从图表、HTML 沙箱到 Kubernetes 与 SLO 可视化

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

本指南以 OneUptime 官方文档 App/FeatureSet/Docs/Content/fa/dashboards/widgets.md 为骨架，系统讲解仪表盘（Dashboard）上每一类组件（Widget/ابزارک）的用途、可配置项、适用场景与底层实现。读完本文，你将能根据监控需求准确选择组件类型，掌握 HTML 组件沙箱安全边界与变量插值机制，并理解 SLO、日志、链路追踪、Kubernetes/Docker 资源清单等组件在源码中的真实工作方式。本文同时以仓库源码为证，说明各组件在 OneUptime 前端中的实现位置。

组件是什么

组件（Widget）就是仪表盘画布上的一块“瓷砖”（tile）。每个组件负责展示一种特定的数据或内容：可以是一个趋势图、一个大数字、一张表、一段 Markdown 文本、一组实时列表，甚至是你自己编写的 HTML/CSS/JavaScript。组件面板（picker）在左侧栏按“大类分组 → 细分分类 → 具体组件”三层组织，源码中的枚举 DashboardComponentType 定义了全部 40+ 种组件类型，而 WidgetCatalog 则记录了每个组件的名称、图标、描述和检索关键词。

从源码结构看，组件的渲染实现集中在 App/FeatureSet/Dashboard/src/Components/Dashboard/Components 目录，每个组件一个DashboardXxxComponent.tsx文件；组件如何摆放、如何设置参数，属于“编写仪表盘”的范畴，见 writing a dashboard。

图表与数字类组件

这类组件回答“指标随时间如何变化、当前数值是多少”的问题，数据来自 OneUptime 自身的指标查询（metrics query）。

图表（Chart）

折线图、柱状图或面积图，展示一个或多个指标序列在仪表盘时间范围内的走势。

可配置项：

• 一个或多个指标查询（metrics query）；
• 可选的公式（formula），把两个查询组合起来，例如errors / total * 100得到错误率；
• “按速率展示（show as rate）”选项，适用于不重置、持续增长的计数器（counter）类指标；
• 展示选项：堆叠（stacked）还是并排（overlay）、Y 轴单位、图例（legend）位置、图表类型。

适用场景：趋势很重要的时候。延迟随时间的变化、错误数量、队列深度——任何“曲线的形状就是在讲故事”的数据。图表组件的渲染实现在 DashboardChartComponent.tsx，其组件类型为Chart。

数值（Value）

一个单独的大数字，可选彩色阈值（threshold）。

可配置项：

• 返回单个数字的指标查询（取值方式为时间范围内的最后值、平均值或最大值）；
• 可选**告警（warning）**阈值——超过则显示黄色；
• 可选**严重（critical）**阈值——超过则显示红色；
• 数字格式与单位。

适用场景：一个数字就能回答的问题。当前错误率、此刻的 P95 延迟、未关闭的事件数量。实现见 DashboardValueComponent.tsx。

仪表盘（Gauge）

圆形仪表，带最小值、最大值、告警区间和严重区间。

可配置项：一个指标查询 + 四个边界值（min / max / warning / critical）。

适用场景：数值落在已知区间内时。CPU 百分比（0–100%）、磁盘占用、队列容量。渲染实现见 DashboardGaugeComponent.tsx 与 GaugeWidgetView.tsx。

表格（Table）

指标结果表，每个分组（group）一行。

可配置项：指标查询（通常按某个标签分组，如host或service）、要显示的列、行数上限（limit）。

适用场景：需要的是拆分（breakdown）而不是趋势。Top 10 最吵的主机、按服务统计的错误数、按端点统计的请求数。组件目录中对表格的补充说明还包括：可设置 Group By（例如host.name）让每个实体一行，或不分组按时间分桶；还可通过公式增加派生列（如可用性百分比），见 WidgetCatalog.ts。实现见 DashboardTableComponent.tsx。

文本类组件

文本（Text）

一块静态的 Markdown 内容。

可配置项：Markdown 正文。标题、列表、链接、强调和代码块都会被渲染。

适用场景：章节标题、一段背景说明、指向 Runbook 的链接列表，或事件处理期间的临时横幅。实现见 DashboardTextComponent.tsx。组件目录中把文本与时钟（Clock）、HTML 一起归入“Essentials / 无需数据源的布局与展示组件”，见 WidgetCatalog.ts。

HTML 组件：自定义能力的边界

HTML 组件让你把自己的 HTML、CSS 和 JavaScript作为一块组件渲染在仪表盘上。

可配置项：HTML 正文、可选样式表（CSS）、可选脚本（JavaScript），以及三个权限开关（见下文“权限”小节）。

适用场景：内置组件覆盖不了的东西——第三方嵌入徽章、从内部 API 画出的表格、自定义提示、一组链接到自有工具的精美入口。

能做什么、不能做什么

HTML 组件渲染在一个独立源（opaque origin）的隔离 iframe中。在 frame 内部，你的代码几乎可以做任何事情：构造 DOM、运行定时器、从任意地址fetch、在 canvas 上绘图。

它不能做的是触达 OneUptime 页面本体：拿不到外层 DOM、Cookie、localStorage，也拿不到仪表盘的 API 会话，更不能把浏览器标签页导航到别处。无论这是私有仪表盘还是分享出去的公共仪表盘，这条限制都成立。

粘贴任何内容之前有两点值得知道：

• 组件的fetch是从一个匿名源发出的跨源请求，所以被调用的服务必须用CORS放行；从组件里直接调用 OneUptime 自身的 API 不受支持。
• 组件默认透明背景。如果想让卡片被填满，请在 CSS 里给body设置背景色。

源码 HtmlWidgetDocument.ts 对安全模型做了明确说明：公共仪表盘与/dashboard、/api同源，因此 iframe 的 sandbox 属性就是全部边界——iframe 拿到allow-scripts但永远不给allow-same-origin。allow-same-origin与allow-scripts同时存在等价于没有沙箱（文档可以反手摘掉自己的 sandbox 属性），所以两者绝不一起出现，getSandboxAttribute()也没有任何输入能产生allow-same-origin。组件会默认注入一段基础 CSS（透明背景、系统字体栈、box-sizing: border-box），作者自己的<style>后注入，因此在层叠顺序上可以覆盖它，见 BASE_CSS。

使用仪表盘变量

在 HTML、CSS 或 JavaScript 的任何位置写{{variableName}}，渲染组件前它会被替换为变量的当前值。选择新值会重新渲染组件。引用不存在的变量时，占位符会原样保留（而非清空），见 interpolate——这是为了让作者更可能写的是字面花括号（如自己 JS 里的模板字符串）而不是引用了已删除的变量。

脚本还能通过window.ONEUPTIME拿到同样的值，外加仪表盘时间范围：

window.ONEUPTIME.variables.environment; // 当前值，未设置时为 "" window.ONEUPTIME.startDate; // ISO 8601 字符串，仪表盘时间范围起点 window.ONEUPTIME.endDate; // ISO 8601 字符串，时间范围终点

每次仪表盘刷新，组件都会重新加载，因此自行抓取数据的组件能跟上刷新节奏。从源码看，window.ONEUPTIME上下文对象在 getContext 中构造，序列化时把所有<改写为\u003c，防止变量值中的任何内容提前终结<script>元素，见 serializeContext。此外脚本块仅在allowScripts开启时才被写入文档；关闭时连<script>标签都不会输出，避免“为什么没跑起来”的困惑，见 build。

权限开关

• Run JavaScript（默认开启）：执行你的脚本。关闭后只渲染标记和样式——此时脚本不是被简单屏蔽，而是整体从组件中移除。
• Open links in a new tab（默认开启）：允许链接和window.open打开浏览器新标签页。链接总是在新标签页打开；组件永远不会把仪表盘本身导航走。源码中对应 sandbox 令牌allow-popups与allow-popups-to-escape-sandbox（后者保证弹出的新标签页是普通顶层页面而不是同样被沙箱化的空白文档），见 getSandboxAttribute。
• Allow forms to submit（默认关闭）：允许组件内的<form>提交（sandbox 令牌allow-forms）。

安全提示（文档原话）：任何能编辑仪表盘的人决定了这个组件执行什么代码，而任何查看仪表盘的人都会执行它——在公共仪表盘上，这包括匿名访客。请把“对携带 HTML 组件的仪表盘的编辑权限”当作“对你要发布的任何代码的权限”来对待。

交互细节在 DashboardHtmlComponent.tsx 中有补充：iframe 的key包含refreshTick，因此每次刷新会通过重挂载真正重跑作者脚本；编辑模式下pointer-events: none，否则 iframe 会吞掉所有指针事件、导致组件无法选中、拖拽或缩放。

日志与链路追踪类组件

日志图表（Log Chart）

日志量（log volume）在仪表盘时间范围内的时序图。每个序列代表一个严重级别（severity），因此错误数从正常流量中的跳变会被凸显出来。

可配置项：

• 可视化方式：柱状图、折线图或面积图；柱状图和面积图会把各级别序列堆叠起来；
• 可选的严重级别过滤；
• 可选的日志正文全文搜索；
• OpenTelemetry 属性（attribute）的精确过滤，支持可搜索的键/值行——输入时已知的属性名和值会给出建议，自定义值同样支持；
• 可选标题。

仪表盘的时间范围与刷新控件会自动触发图表重新查询。仪表盘的遥测属性变量也会作用于它，包括多选变量。日志图表目前要求已认证的仪表盘；公共仪表盘不会显示该组件，以免匿名暴露项目日志聚合。实现见 DashboardLogChartComponent.tsx 与 LogChartQueryEditor.tsx。

适用场景：想在不离开仪表盘的情况下观察日志量的变化，或对比 error / warning / info 日志。

日志流（Log Stream）

与过滤器匹配的实时日志行流。

可配置项：日志过滤器（服务、严重级别、属性）和要显示的列。

适用场景：想不离开仪表盘就看到程序此刻在说什么。实现见 DashboardLogStreamComponent.tsx。

链路追踪列表（Trace List）

与过滤器匹配的近期追踪（trace）列表，含耗时、状态与服务。

可配置项：追踪过滤器（服务、状态、属性）。

适用场景：比起图表，更想要一份近期活动的列表。常见布局是上方放延迟图、下方放慢追踪列表。实现见 DashboardTraceListComponent.tsx 与 TraceChartQueryEditor.tsx。

此外组件目录中还列出了追踪图表（Trace Chart：Span 计数或响应时间百分位随时间变化，可按属性拆分，关键词含 p95/p99）与追踪表格（Trace Table：按 span 名/状态/属性统计请求数的 Top 维度，含中位数、均值、最小/最大响应时间），见 WidgetCatalog.ts。

实时列表类组件

这类组件回答“现在系统里正在发生什么”。

事件列表（Incident List）

与过滤器匹配的实时事件列表。

可配置项：按状态、严重级别、标签、监控项（monitor）或团队过滤。

适用场景：仪表盘回答“现在什么东西坏了？”。实现见 DashboardIncidentListComponent.tsx。

告警列表（Alert List）

与过滤器匹配的实时告警列表。

可配置项：按状态、严重级别、标签过滤。

适用场景：团队仪表盘跟踪各服务的告警。实现见 DashboardAlertListComponent.tsx。

监控项列表（Monitor List）

实时监控项及其当前状态列表。

可配置项：按监控类型、标签或当前状态过滤。

适用场景：舰队视图——“所有站点都正常吗？”。实现见 DashboardMonitorListComponent.tsx。

服务水平目标（SLO）

SLO 组件

展示一个服务水平目标，可渲染为单一数字或随时间变化的折线。

可配置项：选哪个 SLO；三个数字中显示哪个（SLI、Error Budget Remaining（剩余错误预算）或Burn Rate（燃烧率））；瓷砖（tile）或图表（chart）展示；可选标题。

• 瓷砖（tile）：打印当前数字，并在任何位置打印第二行——SLI 低于目标时、错误预算剩余分钟数不足时。其状态色为整块染色。
• 图表（chart）：把同一个数字画在仪表盘时间范围内，目标值在 SLI 序列上以虚线标出。历史数据由评估 worker 每隔几分钟写入，因此新创建的 SLO 在首次评估前会画出空白。评估 worker 的周期与SloHistory模型相关，见 Common/Models/AnalyticsModels/SloHistory.ts。

适用场景：仪表盘回答“我们在兑现承诺吗？”，而不是“现在发生了什么”。

公共仪表盘的披露边界：SLO 组件可以在公共仪表盘上工作。对外发布的是 SLO 的摘要数字——名称、目标、当前 SLI、剩余错误预算、燃烧率与状态——无论组件渲染的是哪一个。其定义保持私有：它监控的监控项、标签、描述、查询和评估时间表，绝不发送给公共访客。瓷砖组件只发布那几个当前数字；图表组件除了自己绘制的那一个历史序列之外什么也不发布。

源码为这一承诺提供了直接证据：SloWidgetData.ts中的SLO_WIDGET_SELECT白名单只挑选name / targetPercentage / currentSliPercentage / errorBudgetRemainingPercentage / errorBudgetRemainingSeconds / currentBurnRate / sloStatus这些字段；公共仪表盘走共享的 resource-list 端点，由服务端固定这份 select 并忽略客户端发送的任何东西，因此这份列表是组件的“契约”而非“访问控制”，见 SloWidgetData.ts。公共仪表盘下历史聚合也通过componentId端点由服务端从存储的组件配置重建，见 aggregateSloHistory。

Kubernetes 资源清单

适用于已安装 Kubernetes Agent 的项目。每个组件都有可选的集群、命名空间与标签过滤器（源码中对应 Kubernetes 相关组件类型见 DashboardComponentType.ts，渲染基类为 DashboardKubernetesResourceListBase.tsx）：

• Kubernetes Pod List— Pod 及其阶段（phase）、重启次数与所在节点；
• Kubernetes Node List— 节点及其状况（conditions）与容量；
• Kubernetes Namespace List— 命名空间及负载数量；
• Kubernetes Deployment List— 部署及其期望副本数对比就绪数；
• Kubernetes StatefulSet List— 有状态集及其就绪副本数；
• Kubernetes DaemonSet List— DaemonSet 及其期望对比就绪；
• Kubernetes Job List— 任务及其完成状态；
• Kubernetes CronJob List— 定时任务及其调度计划与最近一次执行。

适用场景：一张把所有 Kubernetes 状态与那些负载的遥测结合起来的单块仪表盘。组件目录说明数据由 OneUptime Kubernetes Agent 填充的已连接集群实时清单填充，见 WidgetCatalog.ts。

Docker 资源清单

适用于已配置 Docker 监控的项目：

• Docker Host List— 运行 Docker 的主机及容器数量；
• Docker Container List— 容器及其状态、镜像、主机、运行时长；
• Docker Image List— 镜像及其大小；
• Docker Network List— Docker 网络及连接的容器；
• Docker Volume List— 卷及其使用情况。

这些清单由 OneUptime Docker Agent 填充，见 WidgetCatalog.ts。除 Docker 外，仓库还支持同类清单组件：Docker Swarm（Node/Service）、Podman（Host/Container/Image/Network/Volume）、Proxmox VE（Node/Guest）、VMware vCenter（Host/VirtualMachine）、Ceph（OSD/Pool），它们分别由对应 Agent 的 OpenTelemetry 采集器填充，全部可在 DashboardComponentType.ts 中看到。

基础设施与网络

主机列表（Host List）

OneUptime 服务器监控（Server Monitor）所监控的主机，含状态、CPU、内存与运行时长。

可配置项：按标签或当前状态过滤。实现见 DashboardHostListComponent.tsx。组件目录补充说明主机来自host.nameOTel 资源属性的自动发现，见 WidgetCatalog.ts。

网络地图（Network Map）

把你的网络站点画在世界地图上，每个站点按其经纬度钉在对应位置，并按汇总后的状态着色。彼此接近的站点共用一个带数量数字的标记；只代表一个站点的标记点击后会打开该站点。

地图会自动取景到它所绘制的站点上——某个国家内的站点会把取景框填满该国，散布在大洲间的站点则展开到世界视野。没有缩放或平移控件：仪表盘瓷砖是一张静态图像，层级浏览发生在 Network 菜单下的 Network Map 页面。地图上方打印有多少站点处于宕机状态（因为 200 个绿点里的一个 2 像素红点，没人能隔着仪表盘距离读出来）；下方一行覆盖说明地图没有显示什么——缺少坐标的站点，以及是否触发了行数上限。

可配置项：标题、地图/列表视图、最大绘制站点数、是否打印站点名称、按站点类型与状态过滤。当地图拥挤到名称不可读时，站点名会自动隐藏；悬浮提示仍会标注每个标记。站点只有在拥有坐标时才会出现——要钉住它，请在站点上添加经纬度（或通过 CSV 导入）。实现见 DashboardNetworkMapComponent.tsx。

该用哪个组件？

几条快速规则（原文整理）：

• 指标随时间变化？→ 图表（Chart）
• 日志量或错误跳变随时间变化？→ 日志图表（Log Chart）
• 此刻重要的一数字？→ 数值（Value）（或仪表盘 Gauge，若它有明确的 min/max）
• 众多对象间的拆分？→ 表格（Table）
• 系统此刻正在发生什么？→ 日志流、追踪列表、事件列表
• 一组特定资源的状态？→ 对应的列表组件
• 我们在兑现承诺的可靠性吗？→ SLO
• 你的网络在地图哪里、什么变红了？→ 网络地图
• 标题、段落或链接？→ 文本（Text）
• 上面哪个都覆盖不了？→ HTML——但先确认真的没有内置组件能做到

多数仪表盘会组合多种组件——上方一张图、旁边一两个数值、一个文本分隔条、下方一两张列表。若需要组件按服务或客户复用，请配合变量与过滤器；若需要了解画布操作机制，见编写仪表盘；若需要把仪表盘分享给团队之外的人，见分享与公共仪表盘。

参考实现索引

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