Bro-Stat_HA by 哥哥科技（GBNPA Router Sync）

本项目不可独立使用！请参考针对路由器品牌的适配插件联合使用！点我查看更多脚本

English | 简体中文

Bro-Stat & GBNPA-Router-Sync 是由 哥哥科技 开发的一套网络数据遥测与多端转发解决方案。

路由器 × 全屋智能家居平台联动接入插件：Home Assistant 极客集成、UI增强，硬路由NPU最佳伴侣、无需刷机！设备列表平铺化，大屏可视化一点通，你所要的，都在这里，无需频繁切换页面…

本自定义集成通过“脚本截留 + Webhook 异步推送”的组合架构，在不破坏官方原有拓扑、不触发中兴路由器“Web 后台单会话互踢”机制的前提下，将路由器底层的高精度流量数据与设备状态无缝接入 Home Assistant。为网络工程人员提供长周期的流量统计与全局态势观测能力。

配合前端脚本猫插件 ZTE-Stat_Max，将浏览器端抓取到的高精度网络流量数据，通过 Webhook 推送到 Home Assistant 中枢进行持久化存储与展示。

无论是全屋大盘的上下行总流量，还是单台设备的实时吞吐状态，都已被解耦并整合至 HA 的标准设备卡片中。无需频繁登录路由器后台，即可在任意移动端或桌面端实时掌控局域网网络状态。

采用被动数据接收架构，HA 不会主动向路由器发起 HTTP 轮询请求，避免对家庭网络管理业务的干扰。

该项目包含两个相互配合的子组件：

主项目

ZTE-Stat_Max（双 JS 脚本）：运行于浏览器前端，负责接管中兴路由器后台的数据流并优化本地 UI 展示。
GBNPA-Router-Sync（HA 集成）：运行于 Home Assistant 服务器，实现状态的多端无限转发与图表记录。

📖 设计初衷与痛点解决

中兴路由器的硬件转发性能优异，但其官方 Web 管理后台在多终端登录和数据展示上存在一些限制：

单会话限制：官方固件开启了单会话保护，一旦从外网（通过 WG 隧道或公网 IP）登录 Web 后台，家里常亮的本地内网会话就会被强行踢下线，导致 Token 失效。
数据层级较深：实时的设备网速与历史累积流量被隐藏在二级或三级菜单中，无法在同一个全局列表中进行直观的跨设备对比。

✨ 功能特性 (Features)

Local Push 本地推送架构：基于 Webhook 的单向推送机制。Home Assistant 仅作为数据接收方，无主动轮询，无 API 并发冲突，符合 HA 生态最优的数据同步规范。
设备动态发现：根据前端脚本上传的数据，自动解析 MAC 地址并在 HA 中注册独立的设备卡片。
数据读写分离与无限分发：突破官方后台的单设备登录限制。由 HA 作为消息总线进行数据广播，实现多用户、多终端并发观测，且互不干扰。
高精度长周期统计：底层严格保留 bit/Byte 原始精度，与 HA 历史数据库（Statistics）无缝对接。UI 前端利用 HA 渲染引擎实现智能自适应单位换算（MB/GB）。
UI 栅格重构与智能去重：采用 HA 现代实体命名规范（has_entity_name），自动处理全局唯一 ID 与 UI 卡片前缀去重，设备列表平铺化，界面清爽直观。
离线防回流机制 🛡️：内置双重容错与防御逻辑，精准区分“网络抖动导致的数据空缺”与“设备真实的流量重置”，防止因路由器 10 分钟机制导致的数据虚假翻倍。
配置流接入 (Config Flow) 🖥️：原生支持 HA 现代化的图形界面安装，无需手动修改 configuration.yaml，即插即用。

🚀 安装指南 (Installation)

本系统分为 HA 接收端 与 JS 采集端 两部分，请依次完成部署。

阶段一：Home Assistant 端部署

将本项目目录下的 custom_components/gbnpa_router 文件夹完整复制到你的 Home Assistant 的 config/custom_components/ 目录下。
重启 Home Assistant 服务。
进入 HA 面板，点击 设置 -> 设备与服务 -> 添加集成。
搜索 GBNPA 并点击添加，系统将自动完成 Webhook 监听端口的初始化注册。

[!TIP]

通过 HACS 安装

此方法须确保 HAOS 具有良好的网络环境，否则请按前述方法手动安装即可。

打开 Home Assistant，转到“HACS”面板，点击右上角的 ⋮ ，选择 Custom repositories

Type 选择 🧩 Integration，地址输入（可复制）：ucxn/ZTE-Stat_HA

阶段二：数据采集端部署

确保有某台 7×24 主机（Home Server）的浏览器上已安装 脚本猫 (ScriptCat) 插件。
导入本项目提供的采集端 JS 脚本。
在脚本代码顶部的配置区，将 Webhook URL 指向你的 HA 地址：

const WEBHOOK_URL = "http://[HA可访问IP]:8123/api/webhook/gbnpa_router_webhook";

登录路由器 Web 后台并保持该页面在后台运行，数据即可开始实时推送。

⚙️ 架构说明与目录结构 (Architecture)

项目包含以下核心组件：

态势感知探针.js：运行于浏览器前端，负责高频采样、数据清洗与 JSON 打包。
__init__.py：HA 集成入口，负责注册 Webhook、管理全局内存字典与分发更新信号。
sensor.py：实体生成引擎，负责动态发现内网新节点、创建流量传感器并定义数据保护策略。

⚠️ 注意事项 (Notes)

本方案属于纯被动数据监听与重组工具，不涉及对中兴路由器底层固件的修改，不产生任何安全风险。
脚本抓取的 MAC 地址会在 HA 底层自动清洗（移除冒号并转小写）以符合系统规范，但在设备卡片中仍可保留原始信息用于跨插件链路聚合（Connections）。
建议在路由器中为关键设备分配静态 IP，以便 HA 面板中能够更稳定地展示设备标识。

哥哥科技 硬路由增强组件 米家同步（Bro-Stat）