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/homepageHomepage 的 Proxmox Backup ServerPBS服务组件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 中为该用户添加 TokenToken ID 取有意义的名称如homepage并勾选 Privilege Separation权限分离为API Token 本身单独添加 API Token Permission路径/、角色选Audit、Propagate 勾选。创建完成后你会得到 Token ID形如apitokenpbs!homepage或用户自定义的api_token_id与 Token Secretapi_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#L265url是PBS 服务器的地址与端口如https://pbs.example.com:8007需可被 Homepage 后端访问username是API Token IDToken 的用户标识部分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_usageDatastore数据存储使用率百分比failed_tasks_24hFailed Tasks 24h近 24 小时失败任务数上限显示 99cpu_usageCPU节点 CPU 占用百分比memory_usageMemory节点内存占用百分比其中 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.cpu0~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: PBSAPITokenusername: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 × 100PBS 返回 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]内。相关资源组件配置文档docs/widgets/services/proxmoxbackupserver.md姊妹组件Proxmox VE配置docs/widgets/services/proxmox.mdAPI Token 创建流程docs/configs/proxmox.md#create-token组件实现src/widgets/proxmoxbackupserver/widget.js 与 src/widgets/proxmoxbackupserver/component.jsx认证代理实现src/utils/proxy/handlers/credentialed.js测试用例src/widgets/proxmoxbackupserver/widget.test.js 与 src/widgets/proxmoxbackupserver/component.test.jsx【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考