Homepage 如何用 Longhorn 组件展示集群存储用量

2026-09-09 11:42:51作者：龚格成

如果你在 Kubernetes 集群上使用 Longhorn 存储驱动，可以在 Homepage 的首页顶部添加一个 Longhorn info widget，把各节点的存储用量直接显示在面板上。配置完成后，该组件会拉取 Longhorn 的存储指标并渲染成类似 Resource 组件磁盘用量的展示形式，文档说明其数值与 Longhorn 自身 dashboard 上看到的非常接近（见 Longhorn 组件文档）。

适用前提：

Homepage 已经安装并可访问，配置目录中有 settings.yaml 与 widgets.yaml（安装方式见安装文档）；
集群中运行着 Longhorn 存储驱动，并且你能访问其 API 地址（组件从 Kubernetes 上的 Longhorn 存储驱动拉取指标）。

第一步：在 settings.yaml 中配置 Longhorn provider

Longhorn 的 URL 和凭据不写在组件里，而是存放在 settings.yaml 的 providers 段（providers 用于定义共享的 API provider 选项与密钥，见 settings 文档）。在 settings.yaml 中加入：

providers:
  longhorn:
    url: https://longhorn.aesop.network
    username: "longhorn-username" # 可选
    password: "very-secret-longhorn-password" # 可选

以上是组件文档中的示例值，请把 url 替换为你自己的 Longhorn 服务地址。username 和 password 是可选的：只有两者都提供时，Homepage 才会带着 Basic 认证请求 Longhorn API。

第二步：在 widgets.yaml 中添加 Longhorn info widget

Info widget 定义在 widgets.yaml 中，按文件里的顺序显示在首页顶部（见 info widgets 说明，格式可参考 widgets.yaml 骨架）。按组件文档的写法，在 widgets.yaml 的列表中追加：

- longhorn:
    # 显示展开视图
    expanded: true
    # 显示一个代表聚合值的节点
    total: true
    # 用节点名作为标签
    labels: true
    # 显示各节点
    nodes: true
    # 明确列出要显示的节点；nodes 为 true 时默认显示全部
    include:
      - node1
      - node2

各选项的作用（与文档注释一致）：

选项	作用
`expanded`	显示展开视图
`total`	显示一个代表聚合值（所有节点合计）的节点
`labels`	显示节点名称作为标签
`nodes`	显示各节点
`include`	明确列出要显示的节点；未配置时，`nodes: true` 会显示全部节点

上面的 node1、node2 是文档示例中的节点名，替换为你集群中实际的 Longhorn 节点 ID；不需要筛选节点时可以删掉 include 段。

验证展示结果

保存配置并访问 Homepage 首页，确认以下现象：

Longhorn 组件出现在 info widgets 区域（位置由它在 widgets.yaml 中的顺序决定），每个节点以磁盘用量形式呈现，与 Resource 组件的 disk 展示风格一致；
节点卡片显示剩余可用容量；开启 expanded 后还会显示总容量与用量百分比（节点渲染逻辑见 node.jsx）；
文档给出的核对基准是：组件显示的指标应当与 Longhorn dashboard 上看到的非常接近，直接对照两处数值即可判断配置是否生效。

如果组件未正常显示数据，可对照 API 处理代码中的分支检查：settings.yaml 缺少 providers.longhorn.url 时接口会返回 400 和 Missing Longhorn URL 错误；Longhorn API 返回 401 时日志会记录 Authorization failure，此时检查 username / password 是否正确（注意只有两者同时提供才会发送认证头）；其他非 200 响应也会被记录在 Homepage 日志中。