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 体系，用于在服务卡片上展示防火墙的实时运行状态。它一共提供四个展示字段：

这些标签在 public/locales/en/common.json 中定义，并随 Homepage 的多语言体系自动翻译为对应语言。组件在加载时会先渲染占位块，数据就绪后填充真实数值，这一点可以通过 组件测试用例 中"加载时渲染 4 个占位块"的断言得到验证。

第一步：在 OPNSense 中生成 API 密钥

Homepage 通过 OPNSense 的 REST API 读取数据，因此必须先在防火墙的 Web UI 中创建一对 API 密钥。官方生成步骤如下：

1. 登录 OPNSense Web UI，进入System / Access / Users（系统 / 访问 / 用户）；

2. 创建一个新用户，务必勾选"Generate a scrambled password to prevent local database logins for this user"（生成混淆密码以防止该用户本地数据库登录）——这保证了该账号只能通过 API 访问，无法交互式登录防火墙；

3. 创建完成后，编辑该用户的effective privileges（生效权限），只授予以下两项最小权限：

   • Diagnostics: System Activity（系统活动诊断）
   • Status: Traffic Graph，对应 OPNSense 24.7.x 及更新版本中的Reporting: Traffic（流量统计）

   注意：OPNSense 24.7.x 起权限项名称从Status: Traffic Graph调整为Reporting: Traffic，请根据你的 OPNSense 版本选择对应名称。

4. 点击页面上的 "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

参数说明

关于 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声明：

组件渲染时通过useWidgetAPI同时请求这两个端点（见 component.jsx），任一请求失败都会显示错误界面，两个请求都成功后才渲染数据块。

代理转发与 Basic Auth

OPNSense 的 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")}`; }

即把配置中的username（key）与password（secret）拼接后做 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.js）：activity响应必须包含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 变化的原因之一。

常见问题与排查建议

1. 显示 "HTTP Error" 或认证失败：确认username/password填的是apikey.txt中的 key 与 secret，而不是 Web UI 登录账号密码；确认 OPNSense 用户勾选了"生成混淆密码"选项，且 API key 是在该用户下生成的。
2. 接口返回但无流量数据：检查wan参数是否与实际接口名匹配。默认值为wan，多 WAN 环境（如opt1）必须显式指定。
3. 权限不足导致 403：确认该用户的有效权限中同时包含Diagnostics: System Activity与流量统计权限（24.7.x 起为Reporting: Traffic）。两项权限分别对应activity与interface两个端点，缺一不可——而组件要求两个端点同时成功才渲染，所以任一权限缺失都会导致整个组件报错。
4. 数据校验失败：若响应结构不符合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