告别每天开App查电费!Home Assistant 接入网上国网保姆级教程:从零部署、验证码避坑到全自动低额预警(附三端一键脚本)
每个折腾智能家居的玩家,大概都有过这样的烦恼:夏天全屋空调开足马力、冬天踢脚线电暖气通宵轰鸣,心里总免不了犯嘀咕——这个月电费到底花了多少?余额还剩几块钱?
按以前的笨办法,我们只能每天掏出手机,在繁琐的商业 App 列表里翻出「网上国网」,经历开屏广告、漫长的加载等待,最后查到一个冷冰冰的数字。更惨的是,遇到忘记充值导致半夜突然跳闸停电,冰箱里的昂贵食材全部化水,才追悔莫及。
智能家居的核心意义,从来不是「把遥控器搬进手机」,而是让一切关键生活指标自动为你服务。如果能在家里的智能大屏上、在手机负一屏里,一抬眼就能看到「昨日用电度数」「实时电费余额」「上月账单对比」,甚至当电费余额低于 50 元时,客厅的小爱同学自动温柔提醒,企业微信或手机 App 自动弹窗催充值——这才是真正省心优雅的科技生活。
这篇文章就是为你量身定做的保姆级实操全指南:无论你是刚装好 Home Assistant 的萌新小白,还是曾经被「重启后找不到实体」「验证码死活通不过」折磨退坑的老玩家,跟着本文步步操作,只需 15 分钟,就能零门槛搞定网上国网的完美接入,并彻底筑牢长期持久化的护栏。

图 1:本文原创题图。全景展示从极速接入、避开暗坑到自动化联动的完整交付链路。
认识三大角色:网上国网接入的底层原理
在正式敲键盘配置之前,我们先花 2 分钟用小学生都能听懂的大白话,搞清楚数据到底是怎么一步步从国家电网跑到你的 Home Assistant 界面上的。
智能家居新手最常犯的一个思维误区,就是把「网上国网接入」想象成「电表在每秒钟向 HA 无线发射数字」。实际上,这完全是两码事。整个接入架构由三个各司其职的角色组成:

图 2:小学生秒懂比方。网上国网(总账本)、采集插件(代递员)与 Home Assistant(大管家)的职责边界。
-
角色一:网上国网(电力局的中央总账本) 你家楼道里的智能电表通过电力专网定时向省电力公司汇总数据。电力局的中央数据库每天凌晨对千家万户的电表数据进行汇总批处理,生成你昨天的日用电度数和当前的账户余额。这个总账本属于公网云端服务,并不提供直接的本地局域网接口。
-
角色二:SGCC 采集插件(准时出发的代递抄表员) 为了把云端总账本的数字搬回家,开源社区开发了非常出色的加载项工具(如 ARC-MX/sgcc_electricity_new)。它就像一个勤劳的代递员:每天按照你设定的时间(比如早晨 7 点),自动模拟登录网上国网、越过图形验证码、查询你的户号账单,然后骑着自行车把数据送回你家门前。
-
角色三:Home Assistant(家庭智能大管家) 代递员把数字送达后,通过 Home Assistant 的 REST API 敲门递交数据。大管家接过数据,在 Lovelace 仪表盘上贴出漂亮的卡片,并在发现余额告警时呼叫音箱和推送服务。
搞清楚这三者的分工,遇到任何问题你都能秒级定位:如果是登录失败,找代递员;如果是卡片变红,找大管家;如果数据日期滞后,那是因为电力局的总账本还没结账。
图 3:真实运行环境截图。经过规范持久化配置后,家庭大屏概览稳定呈现电费余额、昨日用电、月度汇总与历史记录(户号与敏感读数已做不透明脱敏遮蔽)。
动手前的准备清单:磨刀不误砍柴工
在开始安装之前,请准备好以下 4 项材料,确保后续流程畅通无阻:
-
网上国网绑定与户号确认: 在手机应用商店下载「网上国网」官方 App,确认已经成功绑定你家的用电户号(通常是 10 位数字)。请务必先在 App 里人工查询一次,确保能正常看到户号、户名、当前余额与昨日用电记录。
[!NOTE] 本教程适用于国家电网覆盖省份(华北、华东、华中、东北、西北各省市);若你在广东、广西、云南、贵州、海南,供电部门为南方电网,需采用对应的南网适配方案。
-
Home Assistant 运行环境辨识:
- HA OS / Supervised 用户(强烈推荐新手采用):自带 Supervisor 加载项商店(Add-on Store),全界面化点击安装,最省心;
- HA Container / Docker 用户:需按照开源仓库说明通过 Docker Compose 独立运行采集容器,两者底层数据格式完全一致。
-
获取 Home Assistant 长期访问令牌 (Long-Lived Access Token):
- 打开 Home Assistant 网页控制台,点击左下角的个人头像;
- 滚动到页面最底部的「长期访问令牌」区域,点击「创建令牌」;
- 命名为「SGCC-Collector」,复制生成的那一大串加密字符串(妥善保存在记事本中,它只显示一次)。这个令牌就像一把钥匙,专门供采集插件向 HA 汇报数据。
-
验证码识别 API 准备(关键避坑!): 网上国网登录时必须通过点选或滑动验证码。目前采集插件全面支持调用兼容 OpenAI 格式的大语言模型视觉接口(Vision API)。你可以使用任何支持图片理解的 API 服务(例如各大厂商的免费/低成本图文大模型)。
保姆级实操步骤:从零部署采集插件
步骤一:加载项商店添加 Gitee 镜像仓库
由于众所周知的原因,国内网络访问 GitHub 经常遭遇连接中断或超时,导致很多新手在加载项商店里添加仓库时不停转圈报错。
聪明的社区开发者在 Gitee 上建立了完备的国内镜像源。我们直接使用 Gitee 仓库,速度快且从不抽风:
- 打开 Home Assistant,依次点击左侧侧边栏的「设置」→「加载项」;
- 点击右下角的「加载项商店」;
- 点击右上角的「三个点」菜单,选择「仓库」;
- 在弹出的输入框中粘贴以下 Gitee 镜像地址并点击「添加」:
https://gitee.com/ARC-MX/sgcc_electricity_new - 关闭窗口并刷新页面,在加载项商店列表最下方,你就能看到名为「SGCC Electricity」的新插件。点击进入并点击「安装」,通常 10 秒左右即可下载完成。
步骤二:详细配置采集插件参数
安装完成后,先不要急着启动!点击顶部的「配置」选项卡,逐项填写核心参数:
图 4:真实源码截图。采集器内置了 republish() 缓存重推机制,在免去频繁登录的同时保障数据可用。
- HASS_URL:填写你 Home Assistant 的内网访问地址。
例如你的 HA 本地局域网地址为
http://homeassistant.local:8123(注意协议头http://与端口号一定要写全); - HASS_TOKEN:粘贴刚才在前文步骤生成的「长期访问令牌」;
- PHONE / PASSWORD:填写你登录网上国网 App 所使用的手机号与服务密码;
- USER_ID:你绑定的电费户号(10 位数字)。如果你名下有多套房子(如父母家、自住房),可以用英文逗号隔开填入多个户号(例如
3100211120,3101345701); - CRON / 采集时间:默认推荐每天早晨
06:50或07:00采集一次。因为国家电网出账通常在半夜,早晨 7 点正好能抓到最新的昨日用电。切记不要设置成每分钟都去登录抓取,否则会被电网系统识别为恶意爬虫限制登录! - VISION 验证码配置:
LLM_BASE_URL:你的视觉模型 API 端点地址(例如https://api.your-model-gateway.com/v1);LLM_KEY:模型密钥;LLM_MODEL:模型名称(重点看下一节的避坑指南!)。
新手踩坑实录:为什么思考大模型会被验证码卡死?
这是几乎 90% 的新手在接入网上国网时都会摔得头破血流的最大暗坑!
很多人为了追求高成功率,特意给验证码配置了当前最火爆的推理大模型(比如带深思能力的思考模型)。结果启动日志里疯狂报错:
Captcha recognition failed, response is empty!
换了账号不行,重新安装还是不行。

图 5:原创踩坑深度拆解。50 Token 预算极限制约下的模型选择黄金法则。
这背后的真实技术根因非常戏剧化:
在插件源码的点击验证码识别函数中,为了防止模型胡言乱语消耗过多费用,作者在 API 请求体中写死了一个极度严苛的参数:max_tokens: 50!也就是说,模型被限制最多只能说 50 个词。
打个生活中的比方: 老师让全班同学抢答「黑板上的红苹果在哪个位置?请直接报坐标数字」。
- 普通轻量图文模型(如 glm-5.3-flash 等):像个爽快利落的小学生,眼睛一看,脱口而出
(120, 85)。回答只用了 5 个字符,耗时 200 毫秒,验证码秒级通过! - 深度思考/推理大模型:像个学霸做奥数题,非要在草稿纸上洋洋洒洒写下心路历程:「嗯,首先我看到了一张 300x150 像素的图片,背景有噪点,左上角似乎有一只小鸟,让我仔细思考一下物体的几何中心与阴影角度……」 结果「思考过程」刚输出了前 30 个字,50 个 Token 的额度瞬间见底,系统直接一刀切断!最终的坐标答案根本还没来得及说出来,程序收到的有效结果就是一个大写的空字符串!
[!IMPORTANT] 新手选型黄金铁律: 验证码识别请务必选择轻量、快速、直接输出结果的非推理多模态模型(如
glm-5.3-flash或各大厂商的 mini 视觉版)。切勿迷信带长思考链(Reasoning/Thinking)的超大模型!
新手四大认知陷阱与避坑指南
配置保存并点击启动后,在「日志」里看到 Login success 和 Push state success,代表代递员已经把数据送进 HA 了。
但在这个阶段,新手往往会产生四大经典困惑。我们提前打好预防针:
陷阱一:为什么刚接进去,看不到「今天」的电费?
这是被提问频率最高的问题:「我今天开了一整天 24 度空调,为什么 HA 里的日用电量只显示前天的,今天怎么是空的?」

图 6:原创生活大比方。理清用电发生日、电网结算出账日与数据接收日的先后逻辑。
请务必分清收快递的三个日期:
- 周一(用电发生日):你在网上点击「下单买书」(你家开空调耗电);
- 周二(电网出账日):商家在仓库配货打包并打印出运单(电网凌晨系统跑批,汇总前一天的总电量);
- 周三(HA 收到日):顺丰快递把包裹送到你家门口,你签收快递(插件采集并推送到 HA)。
你绝不能因为快递是在周三签收的,就认定这本新书是你周三买的!网上国网公布的日用电量具有天然的 T+1 甚至 T+2 滞后性。今天早晨看到的,永远是昨天(甚至前天)整整 24 小时的总账。等待出账是正常物理规律,绝不是你的集成坏了。
陷阱二:实时功率 (W) 与用电度数 (kWh) 绝不能混为一谈
很多小白看到电费卡片,就想把它直接接入智能开关当即时功率看。
- 功率(单位 W 或 kW):相当于水龙头此时此刻的水流流速(水流急不急、开关开得大不大);
- 用电量(单位 kWh,即俗称的「度」):相当于水桶里累计接了多少升水(流速乘上时间)。
网上国网提供的是「计费电量」,想要看当前全屋实时功率,需要配备智能电表互感器(如计量插座或总闸电流互感采集器)。
陷阱三:为什么不能给日用电量随手加上 total_increasing?
Home Assistant 的 Energy(能源)仪表盘要求被统计的传感器具备 state_class: total_increasing(单调递增)。
很多新手自作聪明,心想:「我把每天的日用电量改成递增,不就能进 Energy 仪表盘了吗?」 大错特错! 递增标签的意思是「电表刻度只会往上涨,永远不回头」。而每天的日用电量是每日份额:前天用了 12 度,昨天节约只用了 5 度,今天用了 8 度。系统一看到数值从 12 跌到 5,就会误以为电表发生了「被盗换表」或「表计归零」,在后台统计中引发剧烈的负数异常。
陷阱四:多户号后缀混淆
如果你同时给父母家和自己家采集电费,插件会自动在实体名称后追加户号后 4 位(例如 _0310 和 _1720)。新手在写卡片代码时,经常复制了别人的模板却忘了改后缀,导致屏幕上一直显示别家的电费甚至红字报错。
终极顽疾:为什么重启 Home Assistant 后实体会消失?
好不容易配齐了所有卡片,界面精致华丽。结果当你因为安装了别的插件随手点了一次「重新启动 Home Assistant Core」——惊悚的事情发生了: 刚才还好好的电费余额、上月账单、今年总用电卡片,瞬间全部变成了刺眼的暗红色「找不到实体」!
小白在这一刻往往当场崩溃,以为整个插件被自己搞坏了。

图 7:原创粉笔字与笔记本比方。深度揭秘 REST 内存状态在系统重启时的擦除与自愈原理。
根因深度剖析:黑板粉笔字 vs 学生的私家笔记本
要理解这个现象,我们翻开 Home Assistant 官方的底层架构手册:
图 8:官方文档真实快照。POST /api/states/<entity_id> 接口的实际职责是创建或替换运行时状态,并不向实体注册表写入永久自启动定义。
采集插件向 Home Assistant 传递数据时,调用的是官方的 POST /api/states/<entity_id> 接口。
这就像代递员每天早晨来到教室,拿起一根粉笔,在教室前方的黑板上写下了「电费余额:128.5 元」。在老师上课期间,大家抬头看黑板,数字一清二楚。
但是,一旦你重启 Home Assistant Core,就相当于保洁阿姨在放学后把整块黑板用湿抹布彻底擦得干干净净! 因为通过 REST 接口写入的状态只保存在内存中,系统在启动时根本不知道这个实体该怎么凭空生出来。必须苦苦等到插件下一次定时采集或者缓存重推(通常要干等 60 分钟),黑板上才会被重新写上字。在这 60 分钟的空窗期里,你看到的就是「找不到实体」。
破局之道:官方 Trigger-Based Template 模板镜像
怎么彻底根治这个顽疾?答案就是给管家配一个带硬壳封面的私家记事本!
图 9:官方文档明确说明。触发式模板(Trigger-based Template)实体的状态与属性天然具备跨重启自动持久化恢复能力。
在 Home Assistant 中,触发式模板传感器(Trigger-based Template Sensor)拥有神级特性:它的值由事件或状态触发写入,并且底层会被自动序列化写入磁盘存储。当 Core 重启时,系统会自动从硬盘里把上次的值读出来恢复,毫秒不差!
代码的核心逻辑美轮美奂:
template:
- triggers:
- trigger: state
entity_id: sensor.electricity_charge_balance_xxxx
sensor:
- name: "网上国网电费余额"
unique_id: sgcc_mirror_balance_xxxx
unit_of_measurement: "元"
device_class: monetary
state: >-
{% set v = states('sensor.electricity_charge_balance_xxxx') %}
{{ v if is_number(v) else this.state }}
看懂最后一行 {{ v if is_number(v) else this.state }} 了吗?
- 当代递员送来合法的新数字时,记事本记下新数字;
- 当系统重启、黑板被擦空(来源实体变成
unavailable或unknown)时,记事本坚守原则:立刻返回this.state(上次记录的有效值)! 这样一来,无论你一天重启 100 次 Home Assistant,大屏上的电费卡片永远稳定常驻,彻底告别红色报错!
高清大屏与极速报警:让智能电费真正服务生活
打造高颜值 Lovelace 用电看板
有了稳定的持久化镜像实体,我们在概览页配置一组赏心悦目的卡片。
代码范例直接采用 Home Assistant 原生卡片网格,新手直接复制粘贴即可使用:
type: vertical-stack
title: ⚡ 家庭电力与电费监控
cards:
- type: glance
show_name: true
show_icon: true
show_state: true
entities:
- entity: sensor.sgcc_mirror_balance_xxxx
name: 当前电费余额
icon: mdi:wallet-outline
- entity: sensor.sgcc_mirror_daily_xxxx
name: 最近一日用电
icon: mdi:lightning-bolt-circle
- entity: sensor.sgcc_mirror_month_charge_xxxx
name: 上月账单金额
icon: mdi:receipt-text-outline
- type: entities
title: 📊 年度统计与历史明细
entities:
- entity: sensor.sgcc_mirror_year_usage_xxxx
name: 今年累计用电量
- entity: sensor.sgcc_mirror_year_charge_xxxx
name: 今年累计总电费
- type: attribute
entity: sensor.sgcc_mirror_daily_xxxx
attribute: data_date
name: 数据对应业务日期
图 10:真实长期统计图表。每月用电度数与出账金额柱状走势一目了然。
实战自动化:电费余额不足 50 元极速报警
这是智能家居最体现价值的一环。当电费余额降至 50 元以下时,主动通知,彻底防止欠费停电:
automation:
- id: alert_power_balance_low
alias: "家庭提醒:电费余额不足 50 元"
trigger:
- trigger: numeric_state
entity_id: sensor.sgcc_mirror_balance_xxxx
below: 50.00
condition:
- condition: template
value_template: "{{ trigger.from_state.state not in ['unknown', 'unavailable'] }}"
action:
# 方式一:向手机 App 发送推送通知
- action: notify.notify
data:
title: "⚠️ 电费余额预警"
message: "您家的当前电费余额仅剩 {{ states('sensor.sgcc_mirror_balance_xxxx') }} 元,请及时在网上国网 App 充值!"
# 方式二:在白天允许音箱播报(夜间安静不打扰)
- condition: time
after: "08:00:00"
before: "21:00:00"
- action: tts.speak
target:
entity_id: media_player.living_room_speaker
data:
media_player_entity_id: media_player.living_room_speaker
message: "温馨提示,家里电费余额已不足 50 元,请记得充值缴费。"
注意上面的条件过滤:trigger.from_state.state not in [‘unknown’, ‘unavailable’],可以完美避开系统刚刚开机时从空白跳到正常数值的误报,只有当真实电费从 50 元以上真正跌破 50 元时才会触发一次,精准而优雅。
三端一键自动化工具箱:告别手工配置代码
如果你觉得手动去写 YAML、配置 packages 目录和对齐各个实体太繁琐,为了真正实现「面向新手的保姆级体验」,我把全套经过生产环境检验的镜像模板生成、配置安全校验与回滚逻辑,打包成了一个完全开源、零第三方依赖的跨平台工具箱:

图 11:原创工具流水线。探针探测、快照备份、模板注入、语法校验与秒级恢复五步闭环。
工具箱下载地址:SGCC 新手一键持久化套件压缩包 (ZIP),内附完整代码与文档。
工具箱设计原则
- 纯本地执行:核心脚本基于 Python 3 标准库,无需通过 pip 安装任何乱七八糟的第三方库,拒绝任何依赖冲突;
- 绝对零泄露:密码和密钥只留在你本地,网络请求仅针对你自己的 Home Assistant 局域网地址;
- 安全快照与回滚:在修改任何文件前,自动创建带时间戳的全量备份;一旦调用官方 API 校验发现语法有误,立刻自动无损回滚,绝不破坏现有配置。
方法一:人工一键全自动执行指南
无论是 Windows、Ubuntu 还是 macOS,均有一键封装脚本可用:
Windows 11(PowerShell 7 / Windows PowerShell)
# 1. 解压工具包并进入目录,复制模板生成自己的映射文件
Copy-Item mapping.example.json mapping.local.json
# 打开 mapping.local.json 填入你插件生成的来源实体名
# 2. 在当前 PowerShell 窗口设置临时连接参数(关闭窗口后自动销毁)
$env:HOME_ASSISTANT_URL = "http://homeassistant.local:8123"
$env:HOME_ASSISTANT_TOKEN = "你的HA长期访问令牌"
$env:HA_CONFIG_DIR = "Z:\config" # 你通过 Samba 挂载的 HA 配置目录
# 3. 三步走:预览 -> 校验 -> 安全写入
.\windows-11.ps1 plan # 只读模式,预览生成的 package YAML 文件
.\windows-11.ps1 check # 检查 HA 连通性与来源实体有效性
.\windows-11.ps1 apply --restart # 自动备份、写入配置、调用 API 校验并安全重启生效
Ubuntu 26.04 LTS(Bash)
# 1. 配置映射文件与环境变量
cp mapping.example.json mapping.local.json
# 编辑 mapping.local.json 填入自己的实体 ID
export HOME_ASSISTANT_URL="http://homeassistant.local:8123"
export HOME_ASSISTANT_TOKEN="你的HA长期访问令牌"
export HA_CONFIG_DIR="/mnt/homeassistant_config"
# 2. 执行一键生成与生效
bash ubuntu-26.04.sh plan
bash ubuntu-26.04.sh check
bash ubuntu-26.04.sh apply --restart
macOS 27(Zsh)
# 1. 配置映射文件与环境变量
cp mapping.example.json mapping.local.json
# 编辑 mapping.local.json 填入自己的实体 ID
export HOME_ASSISTANT_URL="http://homeassistant.local:8123"
export HOME_ASSISTANT_TOKEN="你的HA长期访问令牌"
export HA_CONFIG_DIR="/Volumes/config"
# 2. 一键校验并应用
bash macos-27.sh plan
bash macos-27.sh check
bash macos-27.sh apply --restart
方法二:交给你的 AI 运维 Agent 自动配置
如果你习惯使用各类本地 Agent 编程助手,可以直接将以下提示词委托给它,让 Agent 全自动帮你完成标准对接:
你现在是我的 Home Assistant 专属自动化运维专家。
请帮我将已成功采集的网上国网数据转换为高可用、防重启丢失的持久化镜像:
1. 检查已有的采集插件实体,识别户号后缀,读取当前各传感器状态;
2. 下载并解压 sgcc-beginner-toolkit,基于当前的实体命名生成 mapping.local.json;
3. 执行 plan 预览生成的 packages/sgcc_electricity.yaml 模板;
4. 确保在修改任何 HA 原生配置前,打全量时间戳备份;
5. 调用 HA Core 的 /api/config/core/check_config 接口执行严格语法校验;
6. 仅在校验结果为 valid 的前提下,执行 apply 并重载模板;
7. 验证 6 个镜像实体的状态已正确接受当前读数,且已设置 this.state 兜底自愈保护;
8. 整个过程中严禁在控制台打印我的令牌与个人隐私密码。
新手常见高频问题深度 Q&A
Q1:为什么我的网上国网账号被提示「今日登录次数超限」?
网上国网官方系统为了防刷,严格限制了单个账号每天的登录失败次数与并发请求。
- 绝不要把定时采集设置成几分钟一次;
- 推荐的健康设置是:每天定时采集 1 次(如早晨 06:50)。插件平时会每隔 60 分钟自动从本地缓存进行重推,既保证了 Home Assistant 实时有数据,又完全不会触发云端登录计数。
Q2:我在电费卡片里看到了负数余额,是数据出错了吗?
很多地区在预存电费或后付费结算期间,余额显示机制不同(有些地方负数代表欠费应缴金额,有些地方负数代表账户发生代扣借记)。我们的工具箱在代码逻辑中专门对负数做了合规兼容,切勿在模板里盲目使用「大于零」去过滤数值,否则一欠费卡片就会直接消失。
Q3:为什么我在 Home Assistant 官方 Energy(能源)面板里添加不进电费?
图 12:官方文档真实截图。长期统计体系对传感器的设备类型、计量单位以及状态类别有着严谨要求。
官方 Energy 仪表盘要求:
- 电量统计:必须是
unit_of_measurement: kWh且具备递增特性的总表; - 电费金额:货币类型(
device_class: monetary)在 Home Assistant 规范中只允许使用state_class: total,绝对不允许配置为total_increasing! 如果配置项类型不匹配,Energy 面板在下拉菜单里就会过滤掉该实体。使用本文提供的持久化工具箱,会自动为你生成符合官方标准的规范属性。
Q4:这种接入方式安全吗?家里内网会不会被入侵?
完全安全。整个系统由你完全掌控:
- 采集插件运行在你自己的本地机器内部;
- 所有的电费数据仅通过局域网 REST API 传输,不经过任何第三方云端代理服务器;
- 你所创建的长期访问令牌仅保存在本地,随时可以在 Home Assistant 用户设置中一键撤销作废。
参考资料与开源致谢
- ARC-MX / sgcc_electricity_new 开源仓库:优秀的国家电网数据采集加载项核心项目
- Home Assistant 官方文档:REST API 状态规范
- Home Assistant 官方文档:触发式模板实体与持久化自愈机制
- Home Assistant 官方文档:长期统计系统与数据分桶规则
- 国家电网 95598 网上营业厅官方平台
文中的 Home Assistant 界面标志与名称归属于其官方开源基金会。文内全部图表均为本文原创矢量绘制,界面截图均来自本次真实的接入实操环境,所有账号标识、内网 IP 与个人用能数值已严格做不透明脱敏遮蔽。





