Homepage 项目 Grafana 状态 Widget 完整配置指南版本兼容、API 鉴权与告警统计原理【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage本文是 Homepage一个高度可定制的个人起始页 / 应用仪表盘中 Grafana 信息 Widget 的实战配置指南。Grafana 是广受欢迎的可观测性与监控可视化平台通过本 Widget你可以在 Homepage 的服务分组中直接展示 Grafana 实例的面板数量Dashboards、数据源数量Data Sources、告警总数Total Alerts与当前触发的告警数Alerts Triggered。读完本文你将掌握 widget 的完整 YAML 配置、v1/v2 版本选择依据以及告警统计在源码层面的具体实现原理。一、Widget 能力概览能展示哪些信息在 Homepage 中Grafana Widget 会在服务卡片上渲染 4 个指标块对应字段名分别为dashboards、datasources、totalalerts、alertstriggered。其界面文案定义在 public/locales/en/common.json 中显示为 Dashboards、Data Sources、Total Alerts 与 Alerts Triggered。字段含义数据来源dashboards面板数量admin/stats接口返回的dashboards字段datasources数据源数量admin/stats接口返回的datasources字段totalalerts告警总数admin/stats接口返回的alerts字段alertstriggered已触发的告警数由告警列表接口统计得出v1/v2 逻辑不同见下文二、版本选择Grafana 版本与 Widget 版本的对应关系由于 Grafana 自身的告警 API 在不同版本间发生过破坏性变更Homepage 的 Grafana Widget 提供了version参数来适配不同的 Grafana 版本选择依据如下表Grafana VersionHomepage Widget Version v10.41默认 v10.42v10.4 及更早版本使用 Widgetversion: 1这是默认值可以省略不写。此时组件优先调用 Grafana 旧版告警列表接口/api/alerts并按告警对象的state alerting过滤统计。v10.5 及更新版本必须显式配置version: 2组件将改走 Grafana Alertmanager 的 Prometheus Alertmanager API/alertmanager/grafana/api/v2/alerts此时已触发告警数直接按该接口返回的告警条目数统计。三、最小可用配置在config.yaml的服务分组services中为 Grafana 服务添加如下 widget 配置即可widget: type: grafana url: http://grafana.host.or.ip:port username: username password: password这是最简形态等价于显式声明version: 1、alerts: grafana的默认行为。需要接入新版 Grafana v10.4或切换到 Alertmanager 数据源时使用完整配置widget: type: grafana version: 2 # optional, default is 1 alerts: alertmanager # optional, default is grafana url: http://grafana.host.or.ip:port username: username password: password四、参数详解参数必填默认值说明type是无固定为grafana用于让 Homepage 匹配到 Grafana Widget 的定义url是无Grafana 实例的地址格式为http://host:port或带 HTTPS 的域名Widget 会在此地址基础上拼接/api/{endpoint}发起请求username/password是无访问 Grafana 的用户名与密码用于 Basic Auth 鉴权建议使用具备只读权限的服务账号version否1适配 Grafana 告警 API 的版本开关1对应 Grafana v10.42对应 Grafana v10.4alerts否grafana仅version: 2时生效。可选grafana使用 Grafana 内置 Alertmanager或alertmanager使用独立部署的 Alertmanageralerts 参数在 v2 下的取值在version: 2模式下alerts参数决定告警列表请求打到哪个 Alertmanager 端点。从 src/widgets/grafana/widget.js 中的 mappings 定义可以看到两个候选端点alertmanager→alertmanager/alertmanager/api/v2/alerts独立 Alertmanager 实例grafana→alertmanager/grafana/api/v2/alertsGrafana 内置 Alertmanager因此如果你的 Grafana 将告警交由独立部署的 Alertmanager 统一处理应配置alerts: alertmanager如果直接使用 Grafana 内置的 Alertmanager默认场景保持默认的grafana即可。五、底层 API 与代理链路Widget 的所有数据都通过 Homepage 的服务端代理获取而非浏览器直连 Grafana从而避免跨域与凭据泄露问题。5.1 API 模板与端点映射在 src/widgets/grafana/widget.js 中Widget 声明了统一的 API 模板与端点映射const widget { api: {url}/api/{endpoint}, proxyHandler: genericProxyHandler, mappings: { alerts: { endpoint: alerts }, alertmanager: { endpoint: alertmanager/alertmanager/api/v2/alerts }, grafana: { endpoint: alertmanager/grafana/api/v2/alerts }, stats: { endpoint: admin/stats, validate: [dashboards] }, }, };可以梳理出组件实际发起的三个请求均以{url}/api/为前缀stats→{url}/api/admin/stats返回dashboards、datasources、alerts三个统计字段告警列表v1→{url}/api/alerts返回告警对象数组每个对象含state字段告警列表v2→{url}/api/alertmanager/{grafana|alertmanager}/api/v2/alerts返回告警条目数组。5.2 代理处理器与 Basic Auth所有请求最终由通用代理处理器 genericProxyHandler 统一处理。其关键逻辑包括用formatApiCall将api模板中的{endpoint}与{url}替换为实际值拼接出完整请求 URL当 widget 配置了username与password时自动生成 Basic Auth 头headers.Authorization Basic ${Buffer.from(${widget.username}:${widget.password}).toString(base64)};请求成功HTTP 200后调用validateWidgetData对返回数据做校验详见下文返回给前端的错误信息中的 URL 会经过sanitizeErrorURL脱敏避免泄露凭据或内部地址。5.3 数据校验stats端点声明了validate: [dashboards]。在 validate-widget-data.js 中代理处理器会在返回数据中查找对应的 mapping按endpoint匹配然后逐一校验validate数组中的字段是否存在若dashboards缺失则该请求会被判定为 Invalid data 并返回错误。这保证了当 Grafana 返回异常结构时前端不会渲染出误导性的数据。六、告警统计逻辑v1 与 v2 的差异已触发告警数alertstriggered是四个指标中唯一需要二次计算的字段其统计逻辑在 src/widgets/grafana/component.jsx 中实现且 v1 与 v2 存在显著差异理解这点对排查告警数不对的问题至关重要。6.1 v1按 statealerting 过滤并带备用端点在version: 1下组件同时发起两个告警请求主端点alertsGrafana 旧版/api/alerts配置在 component.jsx 中备用端点grafanaalertmanager/grafana/api/v2/alerts。统计规则如下if (primaryAlertsError || !primaryAlertsData || primaryAlertsData.length 0) { if (secondaryAlertsData) { alertsInt secondaryAlertsData.length; // 主端点不可用时回退到备用端点直接取条目数 } } else { alertsInt primaryAlertsData.filter((a) a.state alerting).length; // 主端点可用统计 alerting 状态 }即优先使用 Grafana 旧版告警接口返回的数组仅统计state alerting的告警如果主端点报错或返回空数组则自动回退到内置 Alertmanager 的 v2 接口把返回的告警条目总数作为已触发数。只有当两个端点同时失败时组件才会向用户展示错误。6.2 v2直接统计 Alertmanager 返回的条目数在version: 2下组件只请求一个告警端点由alerts参数决定并将返回数组的长度直接作为已触发告警数不再做state过滤if (primaryAlertsData) { alertsInt primaryAlertsData.length; }由于新版 Grafana v10.4的/api/alerts已移除旧版告警数据模型不再适用因此必须通过 Alertmanager v2 API 取数这也是为什么要根据 Grafana 版本切换version的原因。6.3 测试用例佐证上述逻辑均有对应测试覆盖见 src/widgets/grafana/component.test.jsxv1 状态过滤返回[{state:ok}, {state:alerting}, {state:alerting}]时alertstriggered期望值为 2v1 端点回退主端点alerts请求失败、备用端点返回 3 条时组件不报错且alertstriggered为 3v2 自定义端点配置version: 2, alerts: custom时组件实际请求的端点为custom且按返回数组长度统计。另外 widget.test.js 会通过expectWidgetConfigShape校验 widget 配置对象的整体结构合法性保证api、proxyHandler、mappings等字段的约定格式不因改动而被破坏。七、配置与排错建议明确 Grafana 版本部署前先确认 Grafana 主版本。≤ v10.4 可省略version默认 1 v10.4 必须写version: 2否则告警数将统计不到数据或持续报错。凭据权限最小化admin/stats与告警列表接口通常需要管理员或至少具备告警读取权限的账号建议创建专用的只读服务账号而不是使用 root 账号。排查思路若指标块显示错误可从服务端代理日志确认具体是哪个端点失败stats、alerts还是alertmanager/...。由于代理层会对错误 URL 脱敏日志中的地址不会暴露明文密码。多实例场景如果环境中有多个 Grafana 或独立的 Alertmanager只需为每个服务条目分别配置自己的url与alerts取值互不干扰。八、延伸阅读配置文件的整体结构可参考 src/skeleton/services.yaml所有服务类 Widget 的统一入口定义在 src/widgets/widgets.jsWidget 组件与代理处理器协作的通用机制见 src/utils/proxy/handlers/generic.js 与 src/utils/proxy/use-widget-api.js。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考