Homepage 项目集成 Proxmox Backup Server 监控组件：API Token 配置与数据聚合原理全解析-迪斯科星球

Homepage 项目集成 Proxmox Backup Server 监控组件：API Token 配置与数据聚合原理全解析

【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage

Homepage 的 Proxmox Backup Server（PBS）服务组件（type: proxmoxbackupserver）可以在个人首页仪表盘上直接展示 PBS 备份服务器的数据存储使用率、最近 24 小时失败任务数、CPU 与内存占用。本文以 proxmoxbackupserver.md 为核心，完整讲解前置权限准备、服务配置写法，并结合仓库源码剖析其 API 端点、PBSAPIToken认证头与指标计算逻辑，帮助你实现可复现、可排障的 PBS 监控面板。

前置条件：创建带 Audit 角色的用户与 API Token

与 Proxmox VE 组件类似，PBS 组件要求通过 API Token 认证访问其 REST API。文档明确要求：

Create a user and an API token similar to the Proxmox VE description. The "Audit" role is required for both the user and token (not group).

即：用户和 API Token 都必须被赋予Audit角色（注意是赋给 token 本身，而不是仅赋给其所属的组）。角色不能只挂在 Group 上，否则接口调用会因权限不足而失败。

具体创建步骤可参照 docs/configs/proxmox.md#create-token 中针对 Proxmox 的完整流程，在 PBS Web 管理门户中操作：

新建一个仅用于只读 API 访问的用户（例如api），归属到一个专用组（例如api-ro-users）；
在 Permissions → API Tokens 中为该用户添加 Token，Token ID 取有意义的名称（如homepage），并勾选 Privilege Separation（权限分离）；
为API Token 本身单独添加 API Token Permission，路径/、角色选Audit、Propagate 勾选。

创建完成后，你会得到 Token ID（形如apitoken@pbs!homepage或用户自定义的api_token_id）与 Token Secret（api_token_secret）。将 Token ID 填入组件的username字段、Secret 填入password字段即可。

服务配置：最小可运行示例与参数说明

在services.yaml（或docker.yaml等自定义服务配置）中为 PBS 服务添加 widget 配置：

widget: type: proxmoxbackupserver url: https://proxmoxbackupserver.host:port username: api_token_id password: api_token_secret datastore: datastore_name # optional; if ommitted, will display a combination of all datastores used / total

参数	必填	说明
`type`	是	固定为`proxmoxbackupserver`，组件注册表见 src/widgets/widgets.js#L265
`url`	是	PBS 服务器的地址与端口，如`https://pbs.example.com:8007`，需可被 Homepage 后端访问
`username`	是	API Token ID（Token 的用户标识部分）
`password`	是	API Token Secret（创建 Token 时生成的密钥）
`datastore`	否	指定要展示的数据存储名称；省略时展示所有数据存储聚合后的 used / total 百分比

datastore未指定时，组件会把所有数据存储的使用量相加除以总容量之和，得到一个整体占用百分比；指定后则只针对该单一存储计算。该逻辑在 component.jsx 中通过findIndex(ds => ds.store == widget.datastore)定位目标存储实现。

展示字段：四类监控指标

组件支持（Allowed fields）以下四个展示字段：

["datastore_usage", "failed_tasks_24h", "cpu_usage", "memory_usage"]

对应前端国际化文案见 public/locales/en/common.json#L722-L727：

字段	展示标签	含义
`datastore_usage`	Datastore	数据存储使用率（百分比）
`failed_tasks_24h`	Failed Tasks 24h	近 24 小时失败任务数（上限显示 99+）
`cpu_usage`	CPU	节点 CPU 占用（百分比）
`memory_usage`	Memory	节点内存占用（百分比）

其中 Datastore、CPU、Memory 三项在渲染时会通过highlightValue传入数值，用于触发组件的高亮色阶反馈（超过阈值变色），详见 component.jsx。

实现原理：从配置到面板的完整调用链

API 端点与请求映射

组件在 widget.js 中声明了统一的 API 基址与三个端点映射：

api: "{url}/api2/json/{endpoint}", mappings: { "status/datastore-usage": { endpoint: "status/datastore-usage" }, "nodes/localhost/tasks": { endpoint: "nodes/localhost/tasks", params: ["errors", "limit", "since"] }, "nodes/localhost/status": { endpoint: "nodes/localhost/status" }, }

即所有请求都走 PBS 的/api2/json/只读端点：

status/datastore-usage：返回数据存储列表，每项含store、used、total字段（data.data数组）；
nodes/localhost/tasks：返回任务列表，配合查询参数过滤失败任务；
nodes/localhost/status：返回节点状态，含data.cpu（0~1 小数）与data.memory.used / total。

这些映射被 credentialedProxyHandler 消费：Homepage 后端根据请求的group、service、endpoint找到对应 widget 配置，用formatApiCall拼出目标 URL 后转发请求，并把响应数据回传给前端，凭证不会暴露到浏览器端。

PBS 专用认证头

与其他组件不同，PBS 组件在 credentialed.js#L88-L90 中被特殊处理：

} else if (widget.type === "proxmoxbackupserver") { delete headers["Content-Type"]; headers.Authorization = `PBSAPIToken=${widget.username}:${widget.password}`; }

请求头会携带Authorization: PBSAPIToken=<username>:<password>（并移除默认的Content-Type）。这就是为什么配置中username/password必须分别对应 Token ID 与 Token Secret——它们被拼接为 PBS 官方 API Token 认证格式。

指标计算细节

组件在加载完成后并行请求三个端点（见 component.jsx#L17-L19），然后执行如下计算：

任务查询参数：{ errors: true, limit: 100, since: 当前时间戳(秒) - 24h }，只取最近 24 小时内的失败任务，最多 100 条；
失败任务数：直接取响应total字段，且total >= 100时显示为"99+"（防止长数字溢出布局，测试用例 component.test.jsx#L53-L76 专门验证了这一截断行为）；
数据存储使用率：指定datastore时按used/total×100计算单一存储；未指定时按Σused/Σtotal×100计算整体聚合值；
CPU 使用率：data.cpu × 100（PBS 返回 0~1 的小数）；
内存使用率：data.memory.used / data.memory.total × 100。

任一端点请求失败时，组件会优先展示任务端点的错误信息，并渲染统一的错误提示界面（见 component.test.jsx#L40-L51 的 error 分支测试）。

排障要点

认证失败（401）：确认username/password分别是 Token ID 与 Secret，且 Token 已直接授予Audit角色（而非仅通过组继承），同时检查 Privilege Separation 设置是否符合预期；
URL 不通：确认url指向 PBS 的 HTTPS 端口（默认8007），且 Homepage 后端所在主机可访问该地址，必要时在widget配置中补充headers或调整代理设置；
数据存储显示为空：确认datastore名称与 PBS 中实际的store名称完全一致（大小写敏感），代码中通过ds.store == widget.datastore严格匹配；
字段不生效：确认widget下的展示字段仅在允许列表["datastore_usage", "failed_tasks_24h", "cpu_usage", "memory_usage"]内。

企业官网建设流程全解析