Homepage 集成 OPNSense 防火墙监控组件API 密钥配置与数据解析原理详解【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage导读本文讲解如何在 Homepage 中通过 OPNSense 组件将防火墙的实时状态接入个人起始页/应用仪表盘展示 CPU 负载、活动内存、WAN 接口上传/下载流量四项核心指标。你将掌握 OPNSense API 密钥的完整生成流程、最小权限授予原则、services.yaml中的组件配置方法并从源码层面理解 Homepage 如何通过代理转发、Basic Auth 认证与响应数据解析来驱动这一组件。OPNSense 组件能做什么OPNSense 组件属于 Homepage 的 Service Widget 体系用于在服务卡片上展示防火墙的实时运行状态。它一共提供四个展示字段字段含义国际化标签cpuCPU 负载百分比CPU Loadmemory活动内存占用Active MemorywanUploadWAN 接口上传字节数WAN UploadwanDownloadWAN 接口下载字节数WAN Download这些标签在 public/locales/en/common.json 中定义并随 Homepage 的多语言体系自动翻译为对应语言。组件在加载时会先渲染占位块数据就绪后填充真实数值这一点可以通过 组件测试用例 中加载时渲染 4 个占位块的断言得到验证。第一步在 OPNSense 中生成 API 密钥Homepage 通过 OPNSense 的 REST API 读取数据因此必须先在防火墙的 Web UI 中创建一对 API 密钥。官方生成步骤如下登录 OPNSense Web UI进入System / Access / Users系统 / 访问 / 用户创建一个新用户务必勾选Generate a scrambled password to prevent local database logins for this user生成混淆密码以防止该用户本地数据库登录——这保证了该账号只能通过 API 访问无法交互式登录防火墙创建完成后编辑该用户的effective privileges生效权限只授予以下两项最小权限Diagnostics: System Activity系统活动诊断Status: Traffic Graph对应 OPNSense 24.7.x 及更新版本中的Reporting: Traffic流量统计注意OPNSense 24.7.x 起权限项名称从Status: Traffic Graph调整为Reporting: Traffic请根据你的 OPNSense 版本选择对应名称。点击页面上的 Create API key生成 API 密钥按钮浏览器会下载一个apikey.txt文件其中包含key和secret两个字符串。最小权限原则非常关键只授予Diagnostics: System Activity与流量统计权限意味着即使密钥泄露攻击者也无法通过该账号对防火墙配置做任何修改仅能读取系统活动与流量数据。第二步在 services.yaml 中配置组件将apikey.txt中的key 作为username字段、secret 作为password字段填入服务配置。以 官方组件文档 中的配置为基础- 网络设备: - OPNSense 防火墙: href: http://opnsense.host.or.ip description: 家庭网关 widget: type: opnsense url: http://opnsense.host.or.ip username: key # apikey.txt 中的 key password: secret # apikey.txt 中的 secret wan: opt1 # 可选指定要监控的 WAN 接口名默认 wan参数说明参数必填说明type是固定为opnsenseurl是OPNSense 的访问地址支持主机名或 IP如http://opnsense.lanusername是API key注意不是 Web UI 登录用户名password是API secret注意不是登录密码wan否要监控的 WAN 接口名称默认值为wan多 WAN 场景下可指定如opt1关于 wan 接口名wan参数决定组件读取哪个接口的流量数据。在 OPNSense 中除了默认的wan接口其它接口通常命名为opt1、opt2等。从 组件实现 可以看到其取值逻辑const wan widget.wan ? interfaceData.interfaces[widget.wan] : interfaceData.interfaces.wan;即配置了wan字段时从接口流量响应的interfaces对象中按该名称取值未配置时回退到interfaces.wan。如果你不确定接口名可在 OPNSense Web UI 的Interfaces / Overview接口 / 总览中查看实际接口标识。第三步数据从防火墙到页面的完整链路配置完成后Homepage 通过两条 API 调用获取数据这两条调用由 组件定义 中的mappings声明内部端点名OPNSense REST API 路径校验字段activityapi/diagnostics/activity/getActivityheadersinterfaceapi/diagnostics/traffic/interfaceinterfaces组件渲染时通过useWidgetAPI同时请求这两个端点见 component.jsx任一请求失败都会显示错误界面两个请求都成功后才渲染数据块。代理转发与 Basic AuthOPNSense 的 REST API 使用 HTTP Basic 认证。组件本身不直接向防火墙发请求而是交给通用代理处理器genericProxyHandler完成。在 src/utils/proxy/handlers/generic.js 中可以看到认证头的构造逻辑if (widget.username widget.password) { headers.Authorization Basic ${Buffer.from(${widget.username}:${widget.password}).toString(base64)}; }即把配置中的usernamekey与passwordsecret拼接后做 Base64 编码作为Authorization: Basic ...头发送到 OPNSense。这也是为什么 key/secret 必须分别填入这两个字段——它们共同组成 API 的认证凭据。请求 URL 则由formatApiCall依据模板{url}/api/{endpoint}拼装widget.js、api-helpers.js其中{url}会去除末尾斜杠{endpoint}替换为上文映射表中的 API 路径。因此实际请求形如GET http://opnsense.host.or.ip/api/diagnostics/activity/getActivity GET http://opnsense.host.or.ip/api/diagnostics/traffic/interface响应数据校验代理层拿到响应后还会依据映射表中声明的validate字段做结构校验validate-widget-data.jsactivity响应必须包含headers字段interface响应必须包含interfaces字段否则视为无效数据并返回错误。这保证了前端解析时不会因数据结构不符而崩溃。数据解析从原始响应到展示数值前端拿到两个端点的 JSON 数据后在 component.jsx 中完成关键解析const cpuIdle activityData.headers[2].match(/ ([0-9.])% idle/)[1]; const cpu 100 - parseFloat(cpuIdle); const memory activityData.headers[3].match(/Mem: (.) Active,/)[1]; const wan widget.wan ? interfaceData.interfaces[widget.wan] : interfaceData.interfaces.wan;解析逻辑要点CPU 负载OPNSense 的getActivity接口返回的headers数组第 3 个元素形如CPU: 75.00% idle组件用正则提取空闲百分比再用100 - idle换算为实际负载。例如空闲 75% 时显示 CPU 负载 25.00%见 测试用例 的断言。活动内存headers数组第 4 个元素形如Mem: 123M Active, 456M Inact, 789M Wired正则提取Active值如123M直接展示单位由 OPNSense 返回M/G 等。WAN 流量interfaces响应中包含各接口的字节计数组件读取bytes transmitted上传与bytes received下载再通过国际化格式common.bytes将其格式化为易读的字节单位见 component.jsx。上传/下载值同样经过highlightValue标记便于主题样式区分高低负载。从源码结构看headers数组的元素位置索引 2、3依赖 OPNSensegetActivity接口的输出格式不同 OPNSense 大版本若调整该输出顺序组件解析可能需要同步适配——这也是文档中强调权限项名称随 24.7.x 变化的原因之一。常见问题与排查建议显示 HTTP Error 或认证失败确认username/password填的是apikey.txt中的 key 与 secret而不是 Web UI 登录账号密码确认 OPNSense 用户勾选了生成混淆密码选项且 API key 是在该用户下生成的。接口返回但无流量数据检查wan参数是否与实际接口名匹配。默认值为wan多 WAN 环境如opt1必须显式指定。权限不足导致 403确认该用户的有效权限中同时包含Diagnostics: System Activity与流量统计权限24.7.x 起为Reporting: Traffic。两项权限分别对应activity与interface两个端点缺一不可——而组件要求两个端点同时成功才渲染所以任一权限缺失都会导致整个组件报错。数据校验失败若响应结构不符合headers/interfaces字段校验Homepage 会返回 Invalid data 错误可检查 OPNSense 版本是否过旧、接口路径是否有变动。总结OPNSense 组件是 Homepage 服务集成体系中的一个典型范例在防火墙侧以最小权限创建 API 专用账号并生成密钥在services.yaml中通过type: opnsense一行配置接入随后由通用代理处理器完成 Basic Auth 认证与数据校验前端组件完成 CPU/内存/流量的解析与格式化。掌握该组件的配置流程也就掌握了 Homepage 中所有基于 OPNSense 风格 REST API 的组件如 pfsense、unifi-controller 等的接入套路。更多组件编写与代理机制可参考 组件开发指南 与 代理实现文档。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Homepage 集成 OPNSense 防火墙监控组件：API 密钥配置与数据解析原理详解
Homepage 集成 OPNSense 防火墙监控组件API 密钥配置与数据解析原理详解【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage导读本文讲解如何在 Homepage 中通过 OPNSense 组件将防火墙的实时状态接入个人起始页/应用仪表盘展示 CPU 负载、活动内存、WAN 接口上传/下载流量四项核心指标。你将掌握 OPNSense API 密钥的完整生成流程、最小权限授予原则、services.yaml中的组件配置方法并从源码层面理解 Homepage 如何通过代理转发、Basic Auth 认证与响应数据解析来驱动这一组件。OPNSense 组件能做什么OPNSense 组件属于 Homepage 的 Service Widget 体系用于在服务卡片上展示防火墙的实时运行状态。它一共提供四个展示字段字段含义国际化标签cpuCPU 负载百分比CPU Loadmemory活动内存占用Active MemorywanUploadWAN 接口上传字节数WAN UploadwanDownloadWAN 接口下载字节数WAN Download这些标签在 public/locales/en/common.json 中定义并随 Homepage 的多语言体系自动翻译为对应语言。组件在加载时会先渲染占位块数据就绪后填充真实数值这一点可以通过 组件测试用例 中加载时渲染 4 个占位块的断言得到验证。第一步在 OPNSense 中生成 API 密钥Homepage 通过 OPNSense 的 REST API 读取数据因此必须先在防火墙的 Web UI 中创建一对 API 密钥。官方生成步骤如下登录 OPNSense Web UI进入System / Access / Users系统 / 访问 / 用户创建一个新用户务必勾选Generate a scrambled password to prevent local database logins for this user生成混淆密码以防止该用户本地数据库登录——这保证了该账号只能通过 API 访问无法交互式登录防火墙创建完成后编辑该用户的effective privileges生效权限只授予以下两项最小权限Diagnostics: System Activity系统活动诊断Status: Traffic Graph对应 OPNSense 24.7.x 及更新版本中的Reporting: Traffic流量统计注意OPNSense 24.7.x 起权限项名称从Status: Traffic Graph调整为Reporting: Traffic请根据你的 OPNSense 版本选择对应名称。点击页面上的 Create API key生成 API 密钥按钮浏览器会下载一个apikey.txt文件其中包含key和secret两个字符串。最小权限原则非常关键只授予Diagnostics: System Activity与流量统计权限意味着即使密钥泄露攻击者也无法通过该账号对防火墙配置做任何修改仅能读取系统活动与流量数据。第二步在 services.yaml 中配置组件将apikey.txt中的key 作为username字段、secret 作为password字段填入服务配置。以 官方组件文档 中的配置为基础- 网络设备: - OPNSense 防火墙: href: http://opnsense.host.or.ip description: 家庭网关 widget: type: opnsense url: http://opnsense.host.or.ip username: key # apikey.txt 中的 key password: secret # apikey.txt 中的 secret wan: opt1 # 可选指定要监控的 WAN 接口名默认 wan参数说明参数必填说明type是固定为opnsenseurl是OPNSense 的访问地址支持主机名或 IP如http://opnsense.lanusername是API key注意不是 Web UI 登录用户名password是API secret注意不是登录密码wan否要监控的 WAN 接口名称默认值为wan多 WAN 场景下可指定如opt1关于 wan 接口名wan参数决定组件读取哪个接口的流量数据。在 OPNSense 中除了默认的wan接口其它接口通常命名为opt1、opt2等。从 组件实现 可以看到其取值逻辑const wan widget.wan ? interfaceData.interfaces[widget.wan] : interfaceData.interfaces.wan;即配置了wan字段时从接口流量响应的interfaces对象中按该名称取值未配置时回退到interfaces.wan。如果你不确定接口名可在 OPNSense Web UI 的Interfaces / Overview接口 / 总览中查看实际接口标识。第三步数据从防火墙到页面的完整链路配置完成后Homepage 通过两条 API 调用获取数据这两条调用由 组件定义 中的mappings声明内部端点名OPNSense REST API 路径校验字段activityapi/diagnostics/activity/getActivityheadersinterfaceapi/diagnostics/traffic/interfaceinterfaces组件渲染时通过useWidgetAPI同时请求这两个端点见 component.jsx任一请求失败都会显示错误界面两个请求都成功后才渲染数据块。代理转发与 Basic AuthOPNSense 的 REST API 使用 HTTP Basic 认证。组件本身不直接向防火墙发请求而是交给通用代理处理器genericProxyHandler完成。在 src/utils/proxy/handlers/generic.js 中可以看到认证头的构造逻辑if (widget.username widget.password) { headers.Authorization Basic ${Buffer.from(${widget.username}:${widget.password}).toString(base64)}; }即把配置中的usernamekey与passwordsecret拼接后做 Base64 编码作为Authorization: Basic ...头发送到 OPNSense。这也是为什么 key/secret 必须分别填入这两个字段——它们共同组成 API 的认证凭据。请求 URL 则由formatApiCall依据模板{url}/api/{endpoint}拼装widget.js、api-helpers.js其中{url}会去除末尾斜杠{endpoint}替换为上文映射表中的 API 路径。因此实际请求形如GET http://opnsense.host.or.ip/api/diagnostics/activity/getActivity GET http://opnsense.host.or.ip/api/diagnostics/traffic/interface响应数据校验代理层拿到响应后还会依据映射表中声明的validate字段做结构校验validate-widget-data.jsactivity响应必须包含headers字段interface响应必须包含interfaces字段否则视为无效数据并返回错误。这保证了前端解析时不会因数据结构不符而崩溃。数据解析从原始响应到展示数值前端拿到两个端点的 JSON 数据后在 component.jsx 中完成关键解析const cpuIdle activityData.headers[2].match(/ ([0-9.])% idle/)[1]; const cpu 100 - parseFloat(cpuIdle); const memory activityData.headers[3].match(/Mem: (.) Active,/)[1]; const wan widget.wan ? interfaceData.interfaces[widget.wan] : interfaceData.interfaces.wan;解析逻辑要点CPU 负载OPNSense 的getActivity接口返回的headers数组第 3 个元素形如CPU: 75.00% idle组件用正则提取空闲百分比再用100 - idle换算为实际负载。例如空闲 75% 时显示 CPU 负载 25.00%见 测试用例 的断言。活动内存headers数组第 4 个元素形如Mem: 123M Active, 456M Inact, 789M Wired正则提取Active值如123M直接展示单位由 OPNSense 返回M/G 等。WAN 流量interfaces响应中包含各接口的字节计数组件读取bytes transmitted上传与bytes received下载再通过国际化格式common.bytes将其格式化为易读的字节单位见 component.jsx。上传/下载值同样经过highlightValue标记便于主题样式区分高低负载。从源码结构看headers数组的元素位置索引 2、3依赖 OPNSensegetActivity接口的输出格式不同 OPNSense 大版本若调整该输出顺序组件解析可能需要同步适配——这也是文档中强调权限项名称随 24.7.x 变化的原因之一。常见问题与排查建议显示 HTTP Error 或认证失败确认username/password填的是apikey.txt中的 key 与 secret而不是 Web UI 登录账号密码确认 OPNSense 用户勾选了生成混淆密码选项且 API key 是在该用户下生成的。接口返回但无流量数据检查wan参数是否与实际接口名匹配。默认值为wan多 WAN 环境如opt1必须显式指定。权限不足导致 403确认该用户的有效权限中同时包含Diagnostics: System Activity与流量统计权限24.7.x 起为Reporting: Traffic。两项权限分别对应activity与interface两个端点缺一不可——而组件要求两个端点同时成功才渲染所以任一权限缺失都会导致整个组件报错。数据校验失败若响应结构不符合headers/interfaces字段校验Homepage 会返回 Invalid data 错误可检查 OPNSense 版本是否过旧、接口路径是否有变动。总结OPNSense 组件是 Homepage 服务集成体系中的一个典型范例在防火墙侧以最小权限创建 API 专用账号并生成密钥在services.yaml中通过type: opnsense一行配置接入随后由通用代理处理器完成 Basic Auth 认证与数据校验前端组件完成 CPU/内存/流量的解析与格式化。掌握该组件的配置流程也就掌握了 Homepage 中所有基于 OPNSense 风格 REST API 的组件如 pfsense、unifi-controller 等的接入套路。更多组件编写与代理机制可参考 组件开发指南 与 代理实现文档。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考