Homepage Glances 监控 Widget 完全指南：服务器资源指标、配置参数与源码实现解析

Homepage Glances 监控 Widget 完全指南服务器资源指标、配置参数与源码实现解析【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage导读Glances 是一款开源的跨平台系统监控工具其 Web/RESTful API 模式可对外暴露 CPU、内存、磁盘、传感器、进程等实时数据。Homepage 内置的 Glances Widget 让你无需额外前端页面就能把宿主机或远端机器的资源占用情况直接渲染到个人仪表盘中并与 Docker、Kubernetes、服务状态等其他 Widget 同屏展示。读完本文你将掌握 Glances Widget 的完整 YAML 配置、全部metric指标含义与写法、图表视图切换并通过源码了解其 API 调用链、版本兼容逻辑与轮询机制从而在真实环境中高效排障与二次定制。一、Widget 概览与工作方式Glances Widget 用于监控主机或另一台机器的 CPU、内存、磁盘 I/O、传感器温度与进程等资源信息。其数据并非由 Homepage 直接采集而是通过 Glances 自带的 RESTful API 获取Homepage 侧只负责「请求 展示」配置url指向 Glances 的 Web 服务地址Widget 内部按指标类型调用对应的 API 端点通过新增一个 service 块可以创建多个 Glances Widget 实例分别监控不同主机或不同指标该 Widget 属于信息类监控组件其父级 service不需要href、icon或description字段这一点与普通服务卡片不同。关于 Glances 信息类 Widget展示 hostname、OS、CPU 型号等摘要信息可参考 docs/widgets/info/glances.md本文聚焦于资源监控型 Widget。前置要求Glances 需以 Web/RESTful 模式运行Widget 的数据全部来自 Glances 的 REST API因此被监控端必须以 Web 模式启动 Glances例如glances -w并确保 Homepage 所在容器/主机能够通过网络访问http://glances.host.or.ip:port。若 Glances 开启了认证还需要在 Widget 配置中提供username/password。二、基础配置完整参数说明在services.yaml示例骨架见 src/skeleton/services.yaml中新增一个服务块并在其下声明widgetwidget: type: glances url: http://glances.host.or.ip:port username: user # 可选仅当 Glances 开启了认证时填写 password: pass # 可选仅当 Glances 开启了认证时填写 version: 4 # 仅当运行 Glances v4 或更高版本时必须填写默认 3 metric: cpu diskUnits: bytes # 可选bytes默认或 bbytes仅对 disk 相关指标生效 refreshInterval: 5000 # 可选单位毫秒默认值视指标不同为 1000 或更大 pointsLimit: 15 # 可选默认 15参数逐项解析参数是否必填默认值说明type必填-固定为glances用于路由到对应 Widget 实现url必填-Glances Web 服务地址如http://glances.host.or.ip:portusername/password可选无在 Glances 开启认证时提供Widget 使用带凭据的代理处理器请求 APIversion视情况3运行 Glances v4 及以上时必须设为4v3 可省略metric必填-指定监控数据类型详见下文「支持的指标」一节diskUnits可选bytes磁盘容量显示单位bytesB/KB/MB…或bbytesbit 单位仅对 disk 指标生效refreshInterval可选1000网络指标图表视图下为5000数据轮询间隔毫秒源码保证最终值不小于默认值pointsLimit可选15图表中保留的数据点数量滑动窗口长度不带 href/icon/description 的完整示例官方文档强调该 Widget 不需要父级 service 的href、icon或description。要达到与示例截图相同的效果请按下面这样写- CPU Usage: widget: type: glances url: http://glances.host.or.ip:port metric: cpu - Network Usage: widget: type: glances url: http://glances.host.or.ip:port metric: network:enp0s25提示因为不依赖hrefWidget 卡片不会跳转纯粹作为「监控读数」展示多实例监控只需再追加一个 service 块并指向不同url或metric即可。三、支持的指标Metrics详解metric字段决定 Widget 展示哪类系统监控数据。component.jsxsrc/widgets/glances/component.jsx会按 metric 值路由到对应的渲染组件这是判断合法写法的权威依据if (widget.metric info) return Info service{service} /; if (widget.metric memory) return Memory service{service} /; if (widget.metric process) return Process service{service} /; if (widget.metric containers) return Containers service{service} /; if (widget.metric cpu) return Cpu service{service} /; if (widget.metric.match(/^network:/)) return Net service{service} /; if (widget.metric.match(/^sensor:/)) return Sensor service{service} /; if (widget.metric.match(/^disk:/)) return Disk service{service} /; if (widget.metric.match(/^gpu:/)) return GPU service{service} /; if (widget.metric.match(/^fs:/)) return Fs service{service} /;各指标说明如下metric展示内容info系统信息主机名、操作系统、内核版本、CPU 型号、CPU 使用率、RAM 与 SWAP 使用率cpuCPU 使用率当前系统计算资源占用百分比memory内存使用率当前 RAM 占用百分比process按 CPU 占用排序的前 5 个进程图表视图概览最耗资源的进程containersDocker / Kubernetes 容器列表最多展示 5 个容器及其资源占用network:interface_name指定网络接口的流量数据如network:enp0s25接口名需与 Glances 中的一致sensor:sensor_id指定传感器温度常用于 CPU 温度如sensor:Package id 0需与 Glances 中的传感器标签一致disk:disk_id指定磁盘的 I/O 数据如disk:sdb需与 Glances 中的磁盘 ID 一致gpu:gpu_id指定 GPU 的使用率如gpu:0需与 Glances 中的 GPU ID 一致fs:mnt_point指定挂载点的磁盘容量使用情况如fs:/mnt/storage需与 Glances 中的挂载点路径一致各指标的底层 API 与实现要点从 src/widgets/glances/widget.js 可以看到Widget 的 API 模板为{url}/api/{endpoint}并且通过白名单正则限制了可访问的端点api: {url}/api/{endpoint}, allowedEndpoints: /^\d\/(quicklook|diskio|cpu|fs|gpu|system|mem|network|processlist|sensors|containers)$/,这意味着每个指标最终都会以「版本号 端点名」的形式请求例如http://host:port/api/3/cpu、http://host:port/api/4/network。结合各 metric 组件的实现可归纳出对应的数据源cpu请求${version}/cpu获取总使用率data.total同时请求${version}/quicklook获取cpu_name等摘要图表纵轴以百分比展示metrics/cpu.jsx。info请求${version}/quicklookCPU/RAM/SWAP 占比、percpu数组与${version}/systemhostname、linux_distro、os_version。系统信息非常稳定因此其刷新间隔被硬编码为30 秒源码注释This data is usually super stable而 quicklook 的间隔跟随refreshIntervalmetrics/info.jsx。network请求${version}/network返回接口数组按network:xxx中的接口名匹配item[item.key] interfaceName通过(rx * 8) / time_since_update计算实时下行/上行 bitratev3 用rx/tx字段v4 用bytes_recv/bytes_sent字段这是版本差异的典型体现metrics/net.jsx。disk请求${version}/diskio按disk_name匹配磁盘用read_bytes/write_bytes与time_since_update计算读写速率并以磁盘的critical值作为图表纵轴上限metrics/disk.jsx。sensor请求${version}/sensors按label sensorName匹配传感器图表显示value与单位unit并可展示 Glances 返回的warning/critical阈值metrics/sensor.jsx。gpu请求${version}/gpu按item[item.key] gpuName匹配 GPU图表同时堆叠「显存占用mem」与「GPU 利用率proc」两条曲线无图表视图下还会显示温度metrics/gpu.jsx。fs请求${version}/fs按挂载点匹配文件系统以渐变条直观展示已用空间占比并通过diskUnits切换common.bytes或common.bbytes的容量格式metrics/fs.jsx。process请求${version}/processlist取前 5 条图表视图或前 1 条无图表视图展示进程名、CPU%、内存内存字段在 v3 下取memory_info[0]v4 下取memory_info.rssmetrics/process.jsx。containers请求${version}/containers同样最多展示 5 个容器状态图标映射 running/healthy/paused/stoppedv3 与 v4 的Id/id、Status/status字段名不同源码通过apiVersion 3 ? Id : id兼容metrics/containers.jsx。从以上实现可以看出一个通用规律network:、sensor:、disk:、gpu:、fs:这五类带参数指标冒号后的值都必须与 Glances API 返回的字段一一对应否则组件会因找不到匹配项而显示占位符-。四、视图切换图表视图与无图表视图所有 Glances 指标都提供两种视图默认「图表」视图在 Widget 卡片内绘制实时折线/柱状图如 CPU 使用率曲线、网络上下行双曲线「无图表」紧凑视图仅显示当前读数与关键摘要信息占用空间更小适合信息密度较高的仪表盘。切换方式非常简单在 Widget 配置中传入chart: false即可- Network Usage: widget: type: glances url: http://glances.host.or.ip:port metric: network:enp0s25 chart: false无图表视图在布局上做了针对性调整例如process/containers只保留最耗资源的 1 条记录data.splice(chart ? 5 : 1)让单卡片内容更精炼network无图表时默认刷新间隔提高到 5 秒defaultInterval isChart ? 1000 : 5000减少无谓轮询。五、源码级原理版本兼容、轮询与认证1. 版本兼容version参数如何生效每个指标组件都会调用parseVersionForUrl(version, 3)见 src/utils/proxy/api-helpers.js将配置中的version规范化后拼接到端点前。v3 与 v4 的主要差异已内建到组件中网络字段rx/txvsbytes_recv/bytes_sent进程内存memory_info[0]vsmemory_info.rss容器字段Id/Statusvsid/status。因此当被监控端是 Glances v4 及以上时务必在配置中写明version: 4否则字段名不匹配将导致数据无法正确渲染。2. 轮询与数据点滑动窗口默认refreshInterval为 1000ms网络指标的图表视图下也为 1000ms无图表视图下为 5000msinfo指标的system端点固定 30 秒刷新一次所有刷新间隔都经过Math.max(defaultInterval, refreshInterval)兜底即配置值不能小于默认值避免对 Glances API 造成过频请求pointsLimit默认 15控制图表保留的数据点数量每轮询一次向数组尾部追加新数据点超出上限时从头部移除shift()形成滑动窗口。3. 认证与代理Widget 使用credentialedProxyHandlersrc/utils/proxy/handlers/credentialed.js作为代理处理器它会在请求 Glances API 时附加配置中的username/password凭据因此你不应把密码直接拼进url而是通过username/password字段交给代理层处理避免凭据暴露在前端地址栏中。所有对 Glances 的请求均由 Homepage 后端代理转发而非浏览器直连这也有助于规避浏览器跨域CORS限制。六、多实例与组合监控示例结合前文一个同时监控「本机 CPU」「NAS 磁盘 I/O」「主力机 GPU」的完整配置片段如下- Server CPU: widget: type: glances url: http://glances.host.or.ip:port metric: cpu - NAS Disk I/O: widget: type: glances url: http://nas.local:61208 metric: disk:sdb - GPU Usage: widget: type: glances url: http://gpu-box.local:61208 version: 4 metric: gpu:0 chart: false七、常见问题排查Widget 一直显示-占位符通常是metric中冒号后的标识与 Glances API 返回不一致。可先直接访问http://url/api/version/network或diskio、sensors、gpu、fs核对实际的接口名/挂载点/传感器标签再回填到配置。v4 环境数据异常确认已添加version: 4漏配会导致字段名如网络rx/tx、容器Id按 v3 解析而匹配失败。认证失败/401确认 Glances 已开启认证并在 Widget 中正确填写username/password由 Homepage 代理层统一携带。数据更新过快导致服务压力大调大refreshInterval毫秒并注意info之外各指标的最小间隔受默认值兜底。网络接口速率显示异常确认time_since_update字段可用Widget 以「累计字节增量 / 时间差」计算 bitrateGlances 侧数据采样异常会直接反映到数值上。参考与延伸指标与配置的权威说明docs/widgets/services/glances.md信息类 Glances Widget系统摘要docs/widgets/info/glances.mdWidget 路由与 API 白名单src/widgets/glances/component.jsx、src/widgets/glances/widget.js各指标渲染实现src/widgets/glances/metrics/服务配置骨架src/skeleton/services.yaml【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考