solax-summary-fetch

⚡ 光伏能源数据智能监控助手

基于 solax-cloud-api 封装,安全获取 Solax 逆变器实时数据并返回结构化 JSON,助力家庭能源监控与自动化。

收藏
4.2k
安装
1.2k
版本
latest
CLS 安全性认证2026-06-04
点击查看完整报告 >

使用说明

该 Skill 通过封装 npm 包 solax-cloud-api,为 Solax 光伏逆变器用户提供标准化的数据获取接口。用户需提供 Solax Cloud API Token(tokenId)和逆变器序列号(sn),Skill 将自动调用 Solax Cloud 的 getAPIData() 接口并转换为结构化的 SolaxSummary JSON 数据。支持通过环境变量或 CLI 参数传入凭证,输出直接面向标准输出流,便于与 Home Assistant、Node-RED 等自动化平台集成。

该 Skill 在安全设计方面表现突出:明确强制使用环境变量存储敏感凭证,内置 redact() 函数对 Token 进行脱敏显示(仅展示前后字符),并禁止在日志中输出完整密钥。工程实现上采用 TypeScript 类型定义(SolaxSummary 接口),提供结构化错误处理(返回 {ok:false, error:...} 而非崩溃),且依赖版本严格锁定(0.2.0),有效避免供应链攻击风险。部署方式轻量便捷,仅需 Node.js 环境,通过标准 npm install 即可安装,无需复杂配置。

主要限制在于数据来源单一且依赖第三方库:核心功能完全依赖 solax-cloud-api npm 包(v0.2.0),若该库停止维护或出现兼容性问题,Skill 将受影响。其次,功能范围较窄,仅支持获取"摘要数据"(Summary),无法获取历史详细数据或进行设备控制。此外,来源可信度为 T3 级别(个人开发者 allmightysauron),对于企业级高安全要求场景可能需要额外审计。网络层面,完全依赖 Solax Cloud 服务可用性,本地局域网直连功能缺失。

该 Skill 最适合拥有 Solax 品牌光伏逆变器的家庭用户和智能家居爱好者,特别是需要能源数据自动化采集的场景。适用于构建个人能源监控仪表板、自动化规则(如根据发电量控制家电)或进行长期的能源效率分析。对于开发者而言,可作为物联网数据接入的中间件,快速集成到现有的数据分析 pipeline 中。

使用过程中的常规风险包括:1)凭证管理风险,尽管 Skill 本身安全,但用户若误将 Token 提交至 Git 仓库或在不安全环境变量中存储,仍可能导致能源数据泄露;2)网络稳定性,Solax Cloud API 的响应延迟或故障将直接影响数据获取;3)依赖维护,npm 包的长期维护状态不确定,建议定期运行 npm audit 检查漏洞;4)速率限制,Solax Cloud 可能对 API 调用频率有限制,高频自动化场景需注意遵守平台限流策略。

安全解读

核心用法

solax-summary-fetch 是一个轻量级的 Node.js 技能,用于从 Solax Cloud API 获取光伏逆变器的实时汇总数据。用户需提供 Solax tokenId(API 令牌)和逆变器序列号(sn),即可返回结构化的 JSON 数据(SolaxSummary 类型),方便接入 Home Assistant、Grafana 等自动化平台或数据看板。

使用方式

  • 推荐方式:通过环境变量 SOLAX_TOKENID 和 SOLAX_SN 传入凭证,避免敏感信息泄露到 shell 历史记录
  • 备选方式:通过 --tokenId 和 --sn 命令行参数显式传递

执行命令后,脚本输出标准 JSON 至 stdout,可直接被下游程序解析。

---

显著优点

| 特性 | 说明 |
|------|------|
| 凭证安全机制 | 强制从环境变量读取敏感信息,禁止硬编码;内置 `redact()` 脱敏函数,日志仅显示 token 首尾 2 字符 |
| 结构化错误处理 | API 失败时返回 `{ok:false, error:"..."}` 格式,便于自动化系统捕获异常 |
| ESM/CJS 兼容 | 使用 `createRequire` 处理模块互操作,适应不同 Node.js 版本 |
| 输出类型安全 | 基于 TypeScript 接口 `SolaxSummary`,类型定义清晰 |

---

潜在缺点与局限性

1. 第三方依赖风险:核心功能依赖社区维护的 solax-cloud-api@0.2.0 包,非 Solax 官方出品,维护状态和长期安全性需持续关注
2. 无依赖锁定:SKILL.md 明确说明不使用 package-lock.json,存在供应链攻击风险(恶意包版本替换)

3. 版本滞后:依赖的 0.2.0 版本存在 ESM 入口问题,上游修复后需手动跟进升级

4. T3 来源级别:作者为个人开发者,无 GitHub 组织背书,建议审查依赖源码

---

适合人群

  • 智能家居爱好者:需要将 Solax 光伏数据接入 Home Assistant、Node-RED 等平台
  • 能源数据分析师:需要结构化逆变器数据用于本地分析或可视化
  • 自动化运维人员:具备 Node.js 基础,能配置环境变量和定期审计 npm 依赖

不适合:无技术背景、无法自行审查依赖包来源的纯终端用户。

---

常规风险

| 风险类别 | 等级 | 说明 |
|----------|------|------|
| 供应链攻击 | 中 | 无 lockfile,依赖包可能被篡改;建议手动添加 `package-lock.json` 并审计 |
| API 凭证泄露 | 低 | 实现正确,但用户若误用 CLI 参数方式,token 可能残留于 shell history |
| 依赖弃用 | 中 | `solax-cloud-api` 为个人项目,存在停更风险 |
| 网络中间人 | 极低 | API 调用通过 HTTPS,已加密传输 |

建议操作:部署后运行 npm audit,订阅 solax-cloud-api 仓库的 release 通知,定期重新扫描本技能。

solax-summary-fetch 内容

references文件夹
scripts文件夹
手动下载zip · 3.1 kB
solax-summary.d.tstext/plain
请选择文件