Homepage 集成 Watchtower 容器更新监控 Widget配置指南与 Prometheus 指标解析原理【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage导读本文讲解如何在 Homepage 应用仪表盘中集成 Watchtower 为骨架结合仓库中src/widgets/watchtower/目录下的源码与测试深入剖析该 Widget 如何通过带 Bearer Token 的 HTTP 代理请求 Watchtower 的 Prometheus 指标端点并把纯文本指标转换为看板数据块的全过程。读完你将能独立完成 Watchtower Widget 的配置、排错并理解其底层实现机制。前置条件为 Watchtower 开启 Metrics APIWatchtower 的默认安装并不会暴露指标接口因此在配置 Homepage Widget 之前需要先启用 Watchtower 的 metrics 功能。官方要求 Widget 正常工作Watchtower 必须配置为启用 metrics API对应--metrics启动参数或WATCHTOWER_METRICStrue环境变量。启用后Watchtower 会额外监听一个 HTTP 端口默认8080并暴露/v1/metrics端点以 Prometheus 文本格式输出运行时指标——这正是 Homepage Widget 的数据来源。Widget 基础配置在 Homepage 的services.yaml中为对应的 Watchtower 服务添加如下 Widget 配置块widget: type: watchtower url: http://your-ip-address:8080 key: demotoken三个核心字段的含义如下字段必填说明type是固定为watchtower用于在 src/widgets/widgets.js 的组件注册表中查找对应实现url是Watchtower Metrics API 的访问地址协议 IP/域名 端口如http://192.168.1.10:8080key否访问 Metrics API 所需的访问令牌对应 Watchtower 的--metrics-token启动参数或WATCHTOWER_METRICS_TOKEN环境变量说明key是可选的——如果 Watchtower 未设置 tokenHomepage 仍会发送Authorization: Bearer key请求头但此时 key 为空即可若 Watchtower 配置了 token则必须在此处填写相同值否则请求会被 Watchtower 拒绝。数据字段三个核心指标该 Widget 支持三个数据字段由文档明确限定与前端组件一一对应containers_scanned本次扫描检查的容器总数对应指标watchtower_containers_scannedcontainers_updated本次扫描中实际完成更新的容器数量对应指标watchtower_containers_updatedcontainers_failed本次扫描中更新失败的容器数量对应指标watchtower_containers_failed这三个指标在 public/locales/en/common.json 中定义了显示标签Scanned / Updated / Failed前端组件据此渲染三个数据块。源码级原理从 Metrics 端点到看板数据块配置之外的实现细节全部可以在src/widgets/watchtower/目录下找到。整个数据链路分为三层。1. Widget 定义与端点映射widget.js 定义了 API 模板与端点映射const widget { api: {url}/{endpoint}, proxyHandler: watchtowerProxyHandler, mappings: { watchtower: { endpoint: v1/metrics, }, }, };api: {url}/{endpoint}是通用 API 地址模板{url}会被替换为配置里的url{endpoint}被替换为v1/metrics最终拼接出完整地址http://your-ip-address:8080/v1/metrics。模板替换逻辑位于 src/utils/proxy/api-helpers.js 的formatApiCall该函数还会自动去掉url末尾的多余斜杠。mappings.watchtower.endpoint指明本 Widget 唯一使用的端点是v1/metrics即 Watchtower 官方文档中的 Prometheus 指标路径。2. 代理处理器请求鉴权与指标解析proxy.js 是核心实现其工作流程如下从请求参数中取出group、service、index并通过getServiceWidget来自 src/utils/config/service-helpers.js加载该服务对应的 Widget 配置若服务不存在直接返回400。用formatApiCall拼接完整指标 URL。通过httpProxy来自 src/utils/proxy/http.js发起GET请求请求头携带Authorization: Bearer ${widget.key}——这就是文档中key字段的底层用途。状态码非200或无数据时记录日志并返回对应 HTTP 错误。文本解析Watchtower 的/v1/metrics返回的是 Prometheus 纯文本格式。代理处理器将响应体按换行拆分仅保留以watchtower开头的行再按空格切分组装为{ 指标名: 值 }的 JSON 对象返回前端。这一解析逻辑在 proxy.test.js 中有完整的单测覆盖测试构造了包含watchtower_running 1、foo 2、watchtower_status 3三行的模拟响应断言最终只保留watchtower_running与watchtower_status两个键并验证请求 URL 为http://watch/metrics、鉴权头为Bearer k。3. 前端组件渲染三个数据块component.jsx 通过useWidgetAPI来自 src/utils/proxy/use-widget-api.js底层基于 SWR请求watchtower端点数据加载中渲染三个仅含标签Scanned / Updated / Failed的占位块加载成功分别读取watchData.watchtower_containers_scanned、watchData.watchtower_containers_updated、watchData.watchtower_containers_failed并用common.number国际化格式化数值后填入三个 Block请求出错显示错误容器。component.test.jsx 验证了加载占位与数据渲染两种状态确保三个数据块与指标键严格对应。完整配置示例结合以上分析一个可运行的完整services.yaml配置片段如下- Watchtower: icon: sh-watchtower href: http://your-ip-address:8080 description: Container auto-update monitor widget: type: watchtower url: http://your-ip-address:8080 key: demotoken若 Watchtower 未启用 token 鉴权key字段可省略。常见问题排查显示 HTTP Error 401/403key与 Watchtower 的WATCHTOWER_METRICS_TOKEN不一致或该字段为空但 Watchtower 启用了 token 校验。显示 HTTP Error 404Watchtower 未启用 metrics API缺少--metrics/WATCHTOWER_METRICStrue或url端口填写错误metrics 端口默认8080与 Watchtower 主控制端口不同。数据一直为占位符确认url中的 IP/端口在 Homepage 服务端可达Homepage 的代理请求由服务端发起而非浏览器。指标值全部为 0属正常现象——Watchtower 的指标记录的是最近一次扫描结果若尚未到扫描周期或扫描刚完成、无失败/更新发生updated与failed自然为 0。小结Watchtower Widget 是 Homepage 服务仪表盘中典型的「Metrics 端点 服务端代理 纯文本解析」类 Widget 代表文档负责给出配置入口widget.js负责端点映射proxy.js负责 Bearer 鉴权与 Prometheus 文本解析component.jsx负责三块指标展示测试文件则固化了整条链路的正确性。配置时只需确保 Watchtower 开启 metrics、端口与 token 一致即可在首页实时掌握容器自动更新的健康状态。相关实现与测试可继续查阅 src/widgets/watchtower/ 目录。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考