企业官网建设流程全解析

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）中新增一个服务块，并在其下声明widget：

widget: 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

参数逐项解析

不带 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

提示：因为不依赖href，Widget 卡片不会跳转，纯粹作为「监控读数」展示；多实例监控只需再追加一个 service 块并指向不同url或metric即可。

三、支持的指标（Metrics）详解

metric字段决定 Widget 展示哪类系统监控数据。component.jsx（src/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} />;

各指标说明如下：

各指标的底层 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}/quicklook（CPU/RAM/SWAP 占比、percpu数组）与${version}/system（hostname、linux_distro、os_version）。系统信息非常稳定，因此其刷新间隔被硬编码为30 秒（源码注释：This data is usually super stable），而 quicklook 的间隔跟随refreshInterval（metrics/info.jsx）。
• network：请求${version}/network返回接口数组，按network:xxx中的接口名匹配item[item.key] === interfaceName，通过(rx * 8) / time_since_update计算实时下行/上行 bitrate；v3 用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.rss（metrics/process.jsx）。
• containers：请求${version}/containers，同样最多展示 5 个容器，状态图标映射 running/healthy/paused/stopped；v3 与 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，无图表视图下为 5000ms）；
• info指标的system端点固定 30 秒刷新一次；
• 所有刷新间隔都经过Math.max(defaultInterval, refreshInterval)兜底，即配置值不能小于默认值，避免对 Glances API 造成过频请求；
• pointsLimit（默认 15）控制图表保留的数据点数量：每轮询一次向数组尾部追加新数据点，超出上限时从头部移除（shift()），形成滑动窗口。

3. 认证与代理

Widget 使用credentialedProxyHandler（src/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

七、常见问题排查

1. Widget 一直显示-占位符：通常是metric中冒号后的标识与 Glances API 返回不一致。可先直接访问http://<url>/api/<version>/network（或diskio、sensors、gpu、fs）核对实际的接口名/挂载点/传感器标签，再回填到配置。
2. v4 环境数据异常：确认已添加version: 4；漏配会导致字段名（如网络rx/tx、容器Id）按 v3 解析而匹配失败。
3. 认证失败/401：确认 Glances 已开启认证，并在 Widget 中正确填写username/password（由 Homepage 代理层统一携带）。
4. 数据更新过快导致服务压力大：调大refreshInterval（毫秒），并注意info之外各指标的最小间隔受默认值兜底。
5. 网络接口速率显示异常：确认time_since_update字段可用；Widget 以「累计字节增量 / 时间差」计算 bitrate，Glances 侧数据采样异常会直接反映到数值上。

参考与延伸

• 指标与配置的权威说明：docs/widgets/services/glances.md
• 信息类 Glances Widget（系统摘要）：docs/widgets/info/glances.md
• Widget 路由与 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