在 Homepage 中接入 Prometheus Widget监控抓取目标状态一目了然【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepageHomepage 是一个高度可定制的个人起始页startpage / application dashboard支持通过 Docker 与各类服务 API 集成。本文聚焦其内置的Prometheus 服务小组件基于 Prometheus HTTP API 实时拉取抓取目标Targets的存活状态并在首页直接展示 Up / Down / 总数三个指标。读完本文你将掌握该组件的完整配置方法、字段含义、底层代理调用链以及常见的排错思路。Prometheus 组件是什么Prometheus 组件是 Homepage 众多服务组件之一用于在起始页上以三块统计卡片的形式展示 Prometheus 当前所有抓取目标的健康状态。它不展示具体的指标曲线那是 Grafana 或 Prometheus 自身 UI 的职责而是聚焦哪些目标活着、哪些目标挂了这一运维高频问题让你打开首页即可一眼掌握监控集群的整体健康状况。该组件读取的数据源是 Prometheus 的官方 HTTP API/api/v1/targets而非 Prometheus 的 Web UI因此不需要额外的导出器或中间代理配置非常简单。快速配置在 Homepage 的services.yaml中将某个服务条目的widget类型设为prometheus并填入 Prometheus 实例的访问地址即可widget: type: prometheus url: http://prometheushost:porttype固定为prometheus用于告诉 Homepage 使用 Prometheus 组件及其代理逻辑。urlPrometheus 服务的基础地址例如http://localhost:9090或http://prometheus.internal:9090。组件会在此基础上拼接/api/v1/{endpoint}详见下文源码分析。组件允许展示的字段Allowed fields为[targets_up, targets_down, targets_total]这三个字段分别对应三块统计卡片Targets Up正常目标数、Targets Down故障目标数、Total Targets目标总数。完整示例结合 Homepage 的服务分组语法一个真实可用的配置片段如下- Monitoring: - Prometheus: icon: sh-prometheus.png href: http://prometheushost:port description: Monitoring stack widget: type: prometheus url: http://prometheushost:porturl通常指向内网地址如果 Prometheus 部署在 Docker 中可填写容器名如http://prometheus:9090。统计数据的含义与计算逻辑组件展示的三个数字并非来自某个现成的汇总接口而是由前端组件对 Prometheus API 返回的activeTargets数组实时统计得出。从 src/widgets/prometheus/component.jsx 可以看到核心计算逻辑const upCount targetsData.data.activeTargets.filter((a) a.health up).length; const downCount targetsData.data.activeTargets.filter((a) a.health down).length; const totalCount targetsData.data.activeTargets.length;即字段含义计算方式targets_up状态健康的抓取目标数activeTargets中health up的数量targets_down抓取失败的目标数activeTargets中health down的数量targets_total抓取目标总数activeTargets数组的长度这里的health字段是 Prometheus 官方 API 对每个 target 的抓取健康判定up/down/unknown。值得注意只统计了activeTargets活动目标被停止或已移除的目标不会计入总数。卡片的显示文案由国际化文件定义见 public/locales/en/common.jsonprometheus: { targets_up: Targets Up, targets_down: Targets Down, targets_total: Total Targets }其他语言如 zh-Hans 语言包也提供了对应翻译界面语言会随 Homepage 的显示语言自动切换。底层实现组件如何请求 Prometheus API组件的数据获取链路分为两层代理层与前端数据层。代理层widget.js 与 genericProxyHandlerPrometheus 组件的核心配置定义在 src/widgets/prometheus/widget.jsconst widget { api: {url}/api/v1/{endpoint}, proxyHandler: genericProxyHandler, mappings: { targets: { endpoint: targets?stateactive, validate: [data], }, }, };api模板说明所有请求最终都会打到{url}/api/v1/{endpoint}其中{endpoint}由映射定义替换。mappings.targets将内部端点名targets映射到 Prometheus API 路径/api/v1/targets?stateactive即只拉取活动目标。validate: [data]要求响应 JSON 中必须存在data字段否则视为非法响应详见下文数据校验。代理执行逻辑位于 src/utils/proxy/handlers/generic.js它先从请求参数中解析出group、service和endpoint通过getServiceWidget找到对应的组件配置然后调用formatApiCall把api模板与真实 url、endpoint 拼接成完整请求地址最终经httpProxy发起服务端请求并把结果返回前端。整个过程在 Homepage 的服务端完成因此浏览器与 Prometheus 之间不存在 CORS 问题。前端数据层useWidgetAPI组件前端通过useWidgetAPI(widget, targets)获取数据见 src/widgets/prometheus/component.jsx。该 Hook 封装了 use-widget-api.js内部使用 SWR 做请求缓存与自动重试并把响应中的data与error统一暴露给组件targets即对应上面映射中的端点名。组件渲染逻辑component.jsx数据加载中显示三块占位卡片无数字请求出错渲染错误容器并展示错误信息数据就绪分别渲染 Up / Down / Total 三块卡片数字通过t(common.number, { value })格式化。需要认证的 Prometheus 如何配置如果 Prometheus 实例启用了 Basic Auth例如前置了 Nginx 反向代理做鉴权Homepage 的通用代理会为其自动生成Authorization: Basic ...请求头。相关逻辑位于 src/utils/proxy/handlers/generic.jsif (widget.username widget.password) { headers.Authorization Basic ${Buffer.from(${widget.username}:${widget.password}).toString(base64)}; }因此在 widget 配置中补充username与password字段即可widget: type: prometheus url: http://prometheushost:port username: admin password: your-secret响应数据校验机制为防止组件在收到异常响应时渲染出错误数据Homepage 会对代理返回的内容做校验。校验逻辑见 src/utils/proxy/validate-widget-data.js它会根据widget.type找到对应的mappings再依据当前endpoint匹配映射项逐项检查validate数组中声明的字段是否存在于响应中。对 Prometheus 组件而言映射targets声明了validate: [data]意味着只要响应 JSON 中缺少data字段整个请求即被判定为 Invalid data前端将显示错误而不是错误的数字。这也是为什么组件配置里只关心data.activeTargets——它已被代理层保证存在。常见问题排查卡片一直显示错误/无数据先用浏览器或 curl 直接访问http://prometheushost:port/api/v1/targets?stateactive确认返回 JSON 中包含data.activeTargets数组。若返回 404检查url是否填写正确不要带/api/v1后缀若返回 403则需补充username/password字段。数字与 Prometheus UI 不一致组件只统计activeTargets中的up与downunknown状态的目标既不计入 Up 也不计入 Down但会计入总数与官方 UI 的展示口径可能略有差异。跨域报错该组件所有请求均经由 Homepage 服务端代理generic.js转发前端不直接访问 Prometheus因此一般不会遇到浏览器 CORS 拦截。与 Prometheus Metric 组件的区别仓库还提供了 Prometheus Metric 组件文档它面向的是自定义指标数值如告警数量、队列长度而本文的 Prometheus 组件专注于抓取目标健康状态两者用途互补可按需选用。小结Prometheus 组件是 Homepage 中接入监控体系最轻量的一环一段 YAML、一个 URL即可把 Prometheus 抓取目标的 Up / Down / 总数搬到起始页上。其实现依托 Homepage 统一的通用代理genericProxyHandler与映射校验机制validate-widget-data.js支持 Basic Auth且对 Prometheus HTTP API 的依赖极小适用于任何暴露了/api/v1/targets的 Prometheus 实例。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考