Homepage 集成 pfSense 路由器监控小部件pfsense-api 配置、认证模式与源码实现解析【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage本文介绍如何在 Homepage 仪表盘中集成 pfSense 路由器监控小部件。作为一款高度可定制的主页/应用仪表盘Homepage 通过pfsense服务小部件读取 pfSense 路由器的负载、内存、温度、WAN 状态与磁盘使用情况。读完本文你将掌握 pfSense API 的安装与只读配置、两种认证模式Local Database 与 API Key/Token的选型、wan接口参数的设置方法以及 v1/v2 两代 pfSense API 的配置差异。前置条件安装 pfsense-api 并开启只读模式Homepage 的 pfSense 小部件不会直接读取 pfSense 的 Web GUI而是依赖一个第三方的 pfSense 扩展包pfsense-api。该扩展包为 pfSense 提供了一套 REST API供外部程序安全地读取路由器状态。在 pfSense 上安装 pfsense-api 后建议立即将 API 设置为只读模式配置入口为 pfSense Web 管理界面的System API Settings。由于仪表盘小部件仅需要读取系统状态数据只读模式足以满足需求同时可以最大限度地降低 API 凭据被滥用时的风险。两种认证模式Local Database 与 API Key / Tokenpfsense-api 目前支持两种认证方式Homepage 小部件均可适配具体使用哪一种取决于你的 pfsense-api 版本认证模式Homepage 配置方式适用版本Local Database本地数据库账号usernamepassword填写一个管理员账号的凭据通用API KeyAPI 密钥headers中的X-API-KeypfSense API v2API TokenAPI 令牌headers中的Authorization: client_id client_tokenpfSense API v1配置时需要注意以下约束username/password与headers二选一不要同时配置否则认证头会相互冲突使用 Local Database 模式时凭据必须来自一个管理员admin用户普通只读账号可能无法获得足够的 API 权限API Key / Token 的具体取值方式取决于 pfsense-api 的版本安装后可在 pfSense 的System API页面中生成和查看。从源码层面看Homepage 的通用代理处理器genericProxyHandler会在发起请求前组装认证头当小部件同时配置了username与password时会自动将其编码为 HTTP Basic Auth 的Authorization请求头src/utils/proxy/handlers/generic.js随后再合并headers中的自定义头。因此无论你选择哪种模式最终都是通过请求头把凭据交给 pfSense API 的。指定监控接口wan 参数wan参数用于指定需要监控的网络接口它的取值必须与 pfSense Web 管理界面Interfaces Assignments中显示的接口名完全一致例如igb0、wan0等。在 Homepage 的组件实现中接口数据通过该名称进行精确匹配定位。component.jsx中执行了如下过滤逻辑从接口列表中取出hwif字段等于widget.wan的那一项再读取其状态与 IP 地址用于渲染。若wan名称与 pfSense 中的接口分配名不一致WAN 状态与 WAN IP 将无法正确显示。可监控字段与已知限制小部件允许展示以下字段最多同时启用4 个[load, memory, temp, wanStatus, wanIP, disk]字段通过小部件配置中的fields数组启用未启用的字段不会渲染。各字段含义如下字段含义说明load系统负载平均值基于load_avg[0]v1或cpu_load_avg[0]v2memory内存使用率v1 返回小数0-1Homepage 会乘以 100 换算为百分比tempCPU 温度摄氏度取自temp_c字段wanStatusWAN 接口在线状态显示为Up/DownwanIPWAN 接口 IP 地址取自接口数据中的ipaddr字段disk磁盘使用率v1 同样需要乘以 100 换算为百分比需要注意一个官方文档明确指出的限制load负载字段取代了 CPU 利用率。这是因为 pfSense API 出于 CPU 利用率计算的复杂性当前不提供直接的 CPU 使用率指标Homepage 因而以系统负载平均值代替未来版本的 API 有可能开放这一指标。另外由于wanIP与disk属于可选附加块Homepage 在组件层面对其做了数量校验只有当fields中非wanIP/disk的字段数不超过 4 时这两个字段才会被渲染见component.jsx中的showWanIP与showDiskUsage判断。完整配置示例pfSense API v2推荐新安装用户widget: type: pfsense url: http://pfsense.host.or.ip:port username: user # optional, or API key password: pass # optional, or API key headers: # optional, or username/password X-API-Key: key wan: igb0 version: 2 # optional, defaults to 1 for api v1 fields: [load, memory, temp, wanStatus] # optionalpfSense API v1旧版本widget: type: pfsense url: http://pfsense.host.or.ip:port headers: # optional, or username/password Authorization: client_id client_token # obtained from pfSense API wan: igb0 version: 1 fields: [load, memory, temp, wanStatus]配置要点type必须为pfsenseurl填写 pfSense 的地址与端口如http://192.168.1.1若 API 使用非默认端口需显式指定version缺省值为1即默认按 pfSense API v1 的端点与数据格式请求使用 v2 时务必显式设置version: 2fields为可选项不配置时按源码逻辑仍会渲染load、memory、temp、wanStatus四个默认块。源码级实现解析API 端点映射小部件的后端请求定义在src/widgets/pfsense/widget.js中。它声明了统一的 API 模板{url}/api/{endpoint}并针对 v1/v2 定义了四组映射mappings: { system: { endpoint: v1/status/system, validate: [data] }, interface: { endpoint: v1/status/interface, validate: [data] }, systemv2: { endpoint: v2/status/system, validate: [data] }, interfacev2: { endpoint: v2/status/interfaces?limit0offset0, validate: [data] }, }可以看到 v2 的接口端点改为v2/status/interfaces并显式带上limit0offset0以获取完整的接口列表即不使用分页默认值。所有端点均要求响应体存在data字段这对应了validate: [data]的校验规则。小部件本身使用通用代理处理器genericProxyHandler完成请求转发无需为 pfSense 编写专用的代理逻辑。请求会经过src/utils/proxy/handlers/generic.js的如下流程拼接最终 URL → 合并认证头 → 通过httpProxy发起请求 → 使用validateWidgetData校验响应结构 → 将结果回传给前端。数据渲染与 v1/v2 差异前端渲染逻辑位于src/widgets/pfsense/component.jsx其核心流程如下读取widget.version缺省按1处理根据版本选择请求端点v1 请求system/interfacev2 请求systemv2/interfacev2两个请求任一失败时组件直接渲染错误容器Container error{...} /数据尚未就绪时先渲染带骨架动画的占位块animate-pulse数据就绪后开始取值渲染。v1 与 v2 的数据结构存在差异组件做了两处关键适配百分比换算v1 的mem_usage与disk_usage返回的是 0~1 之间的小数组件会乘以 100 再格式化为百分比v2 返回的已是百分数值无需换算负载字段名v1 使用load_avg[0]v2 使用cpu_load_avg[0]。WAN 状态渲染时组件判断wan.status up显示为Up否则显示为Down对应的界面文案定义在public/locales/en/common.json的pfsense键下。字段过滤机制fields过滤由通用的Container组件src/components/services/widget/container.jsx统一处理它会把fields数组与子块的label做匹配仅渲染匹配到的数据块。这也是为什么fields中最多只能配置 4 个字段——容器按配置精确裁剪显示内容超出默认块之外的可选字段wanIP、disk还额外受组件层数量校验的约束。测试验证仓库为 pfSense 小部件提供了完整的测试覆盖src/widgets/pfsense/component.test.jsx其中两个关键用例印证了上述行为字段过滤测试当fields配置为[wanIP, disk]时页面只渲染这两个块load/memory/temp/wanStatus均不出现v2 渲染测试mocksystemv2与interfacev2的响应后验证cpu_load_avg显示为负载值、mem_usage: 12.3456被格式化为12.35、temp_c: 40渲染为温度、接口status: up显示为Up而未启用的wanIP/disk块不渲染。常见问题排查认证 401 / 认证失败检查是否同时配置了username/password与headers二者只能择一确认 pfsense-api 已正确安装且 Local Database 模式使用的是管理员账号。WAN 状态或 IP 不显示核对wan取值与 pfSenseInterfaces Assignments中的接口名是否完全一致如igb0。数据格式异常如内存/磁盘显示 0.12 而非 12%检查version是否与 pfsense-api 实际版本匹配。v1 返回小数Homepage 会自动换算若 v2 也按 v1 处理会导致数值异常反之亦然。字段显示不全确认fields数组长度不超过 4且wanIP、disk属于附加可选块受组件数量校验约束。无法连接确认url可被 Homepage 所在主机访问注意 pfSense 的防火墙规则与端口放行并可通过 pfSense 的System API页面直接验证 API 是否返回 JSON 数据。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Homepage 集成 pfSense 路由器监控小部件：pfsense-api 配置、认证模式与源码实现解析
Homepage 集成 pfSense 路由器监控小部件pfsense-api 配置、认证模式与源码实现解析【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage本文介绍如何在 Homepage 仪表盘中集成 pfSense 路由器监控小部件。作为一款高度可定制的主页/应用仪表盘Homepage 通过pfsense服务小部件读取 pfSense 路由器的负载、内存、温度、WAN 状态与磁盘使用情况。读完本文你将掌握 pfSense API 的安装与只读配置、两种认证模式Local Database 与 API Key/Token的选型、wan接口参数的设置方法以及 v1/v2 两代 pfSense API 的配置差异。前置条件安装 pfsense-api 并开启只读模式Homepage 的 pfSense 小部件不会直接读取 pfSense 的 Web GUI而是依赖一个第三方的 pfSense 扩展包pfsense-api。该扩展包为 pfSense 提供了一套 REST API供外部程序安全地读取路由器状态。在 pfSense 上安装 pfsense-api 后建议立即将 API 设置为只读模式配置入口为 pfSense Web 管理界面的System API Settings。由于仪表盘小部件仅需要读取系统状态数据只读模式足以满足需求同时可以最大限度地降低 API 凭据被滥用时的风险。两种认证模式Local Database 与 API Key / Tokenpfsense-api 目前支持两种认证方式Homepage 小部件均可适配具体使用哪一种取决于你的 pfsense-api 版本认证模式Homepage 配置方式适用版本Local Database本地数据库账号usernamepassword填写一个管理员账号的凭据通用API KeyAPI 密钥headers中的X-API-KeypfSense API v2API TokenAPI 令牌headers中的Authorization: client_id client_tokenpfSense API v1配置时需要注意以下约束username/password与headers二选一不要同时配置否则认证头会相互冲突使用 Local Database 模式时凭据必须来自一个管理员admin用户普通只读账号可能无法获得足够的 API 权限API Key / Token 的具体取值方式取决于 pfsense-api 的版本安装后可在 pfSense 的System API页面中生成和查看。从源码层面看Homepage 的通用代理处理器genericProxyHandler会在发起请求前组装认证头当小部件同时配置了username与password时会自动将其编码为 HTTP Basic Auth 的Authorization请求头src/utils/proxy/handlers/generic.js随后再合并headers中的自定义头。因此无论你选择哪种模式最终都是通过请求头把凭据交给 pfSense API 的。指定监控接口wan 参数wan参数用于指定需要监控的网络接口它的取值必须与 pfSense Web 管理界面Interfaces Assignments中显示的接口名完全一致例如igb0、wan0等。在 Homepage 的组件实现中接口数据通过该名称进行精确匹配定位。component.jsx中执行了如下过滤逻辑从接口列表中取出hwif字段等于widget.wan的那一项再读取其状态与 IP 地址用于渲染。若wan名称与 pfSense 中的接口分配名不一致WAN 状态与 WAN IP 将无法正确显示。可监控字段与已知限制小部件允许展示以下字段最多同时启用4 个[load, memory, temp, wanStatus, wanIP, disk]字段通过小部件配置中的fields数组启用未启用的字段不会渲染。各字段含义如下字段含义说明load系统负载平均值基于load_avg[0]v1或cpu_load_avg[0]v2memory内存使用率v1 返回小数0-1Homepage 会乘以 100 换算为百分比tempCPU 温度摄氏度取自temp_c字段wanStatusWAN 接口在线状态显示为Up/DownwanIPWAN 接口 IP 地址取自接口数据中的ipaddr字段disk磁盘使用率v1 同样需要乘以 100 换算为百分比需要注意一个官方文档明确指出的限制load负载字段取代了 CPU 利用率。这是因为 pfSense API 出于 CPU 利用率计算的复杂性当前不提供直接的 CPU 使用率指标Homepage 因而以系统负载平均值代替未来版本的 API 有可能开放这一指标。另外由于wanIP与disk属于可选附加块Homepage 在组件层面对其做了数量校验只有当fields中非wanIP/disk的字段数不超过 4 时这两个字段才会被渲染见component.jsx中的showWanIP与showDiskUsage判断。完整配置示例pfSense API v2推荐新安装用户widget: type: pfsense url: http://pfsense.host.or.ip:port username: user # optional, or API key password: pass # optional, or API key headers: # optional, or username/password X-API-Key: key wan: igb0 version: 2 # optional, defaults to 1 for api v1 fields: [load, memory, temp, wanStatus] # optionalpfSense API v1旧版本widget: type: pfsense url: http://pfsense.host.or.ip:port headers: # optional, or username/password Authorization: client_id client_token # obtained from pfSense API wan: igb0 version: 1 fields: [load, memory, temp, wanStatus]配置要点type必须为pfsenseurl填写 pfSense 的地址与端口如http://192.168.1.1若 API 使用非默认端口需显式指定version缺省值为1即默认按 pfSense API v1 的端点与数据格式请求使用 v2 时务必显式设置version: 2fields为可选项不配置时按源码逻辑仍会渲染load、memory、temp、wanStatus四个默认块。源码级实现解析API 端点映射小部件的后端请求定义在src/widgets/pfsense/widget.js中。它声明了统一的 API 模板{url}/api/{endpoint}并针对 v1/v2 定义了四组映射mappings: { system: { endpoint: v1/status/system, validate: [data] }, interface: { endpoint: v1/status/interface, validate: [data] }, systemv2: { endpoint: v2/status/system, validate: [data] }, interfacev2: { endpoint: v2/status/interfaces?limit0offset0, validate: [data] }, }可以看到 v2 的接口端点改为v2/status/interfaces并显式带上limit0offset0以获取完整的接口列表即不使用分页默认值。所有端点均要求响应体存在data字段这对应了validate: [data]的校验规则。小部件本身使用通用代理处理器genericProxyHandler完成请求转发无需为 pfSense 编写专用的代理逻辑。请求会经过src/utils/proxy/handlers/generic.js的如下流程拼接最终 URL → 合并认证头 → 通过httpProxy发起请求 → 使用validateWidgetData校验响应结构 → 将结果回传给前端。数据渲染与 v1/v2 差异前端渲染逻辑位于src/widgets/pfsense/component.jsx其核心流程如下读取widget.version缺省按1处理根据版本选择请求端点v1 请求system/interfacev2 请求systemv2/interfacev2两个请求任一失败时组件直接渲染错误容器Container error{...} /数据尚未就绪时先渲染带骨架动画的占位块animate-pulse数据就绪后开始取值渲染。v1 与 v2 的数据结构存在差异组件做了两处关键适配百分比换算v1 的mem_usage与disk_usage返回的是 0~1 之间的小数组件会乘以 100 再格式化为百分比v2 返回的已是百分数值无需换算负载字段名v1 使用load_avg[0]v2 使用cpu_load_avg[0]。WAN 状态渲染时组件判断wan.status up显示为Up否则显示为Down对应的界面文案定义在public/locales/en/common.json的pfsense键下。字段过滤机制fields过滤由通用的Container组件src/components/services/widget/container.jsx统一处理它会把fields数组与子块的label做匹配仅渲染匹配到的数据块。这也是为什么fields中最多只能配置 4 个字段——容器按配置精确裁剪显示内容超出默认块之外的可选字段wanIP、disk还额外受组件层数量校验的约束。测试验证仓库为 pfSense 小部件提供了完整的测试覆盖src/widgets/pfsense/component.test.jsx其中两个关键用例印证了上述行为字段过滤测试当fields配置为[wanIP, disk]时页面只渲染这两个块load/memory/temp/wanStatus均不出现v2 渲染测试mocksystemv2与interfacev2的响应后验证cpu_load_avg显示为负载值、mem_usage: 12.3456被格式化为12.35、temp_c: 40渲染为温度、接口status: up显示为Up而未启用的wanIP/disk块不渲染。常见问题排查认证 401 / 认证失败检查是否同时配置了username/password与headers二者只能择一确认 pfsense-api 已正确安装且 Local Database 模式使用的是管理员账号。WAN 状态或 IP 不显示核对wan取值与 pfSenseInterfaces Assignments中的接口名是否完全一致如igb0。数据格式异常如内存/磁盘显示 0.12 而非 12%检查version是否与 pfsense-api 实际版本匹配。v1 返回小数Homepage 会自动换算若 v2 也按 v1 处理会导致数值异常反之亦然。字段显示不全确认fields数组长度不超过 4且wanIP、disk属于附加可选块受组件数量校验约束。无法连接确认url可被 Homepage 所在主机访问注意 pfSense 的防火墙规则与端口放行并可通过 pfSense 的System API页面直接验证 API 是否返回 JSON 数据。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
