家庭日用电量监控系统¶

基于OCR识别、MySQL持久化、Prometheus指标采集、Grafana可视化的家庭用电量全链路监控系统

项目概述¶

本系统实现家庭日用电量的自动采集与可视化监控，完整链路包括：

图片扫描：自动扫描指定目录下的电费账单截图
OCR识别：通过火山方舟豆包多模态大模型提取用电量数据
数据持久化：MySQL存储每日用电量及阶梯电费计算结果
指标采集：Prometheus通过Electric Exporter抓取用电指标
可视化展示：Grafana监控大盘展示用电量趋势与阶梯电费分析

功能特性¶

功能模块	特性描述
图片扫描	支持按文件ctime排序，只处理最新N张未识别图片，避免重复API调用
OCR识别	集成火山方舟豆包多模态API，精准提取电费账单日期与用电量数据
阶梯电价计算	支持三档阶梯电价（≤2160度/2161-4800度/>4800度），跨年自动重置累计
数据持久化	MySQL存储每日用电量、各阶梯用电量、费用及年累计数据
指标采集	Electric Exporter实时暴露用电指标，Prometheus自动抓取
可视化展示	Grafana大盘展示用电量趋势、电费分析、阶梯使用率等多维度数据
定时任务	每日20:00自动执行数据采集任务

技术架构¶

┌─────────────────────────────────────────────────────────────────┐
│                        Grafana Dashboard                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│  │ 数据概览 │ │ 趋势曲线 │ │ 柱状对比 │ │ 阶梯分析 │ │ 使用说明│ │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │
└──────────────────────┬──────────────────────────────────────────┘
                       │ MySQL直查
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                        MySQL Database                           │
│              electric_daily_power 数据表                        │
└──────────────────────┬──────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│              Electric Exporter (k8s Deployment)                 │
│                    端口: 9105 /metrics                          │
└──────────────────────┬──────────────────────────────────────────┘
                       │ 指标暴露
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Prometheus Server                            │
│              通过ServiceMonitor自动抓取指标                       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    数据采集端 (定时任务)                          │
│  Pics目录 → file_scan_module → vision_ocr_module →             │
│  db_electric_module → MySQL                                     │
└─────────────────────────────────────────────────────────────────┘

技术栈¶

层级	技术	版本
语言	Python	3.10+
OCR识别	火山方舟豆包多模态API	-
数据库	MySQL	8.0+
指标采集	Prometheus	2.42+
可视化	Grafana	9.0+
容器编排	Kubernetes	1.25+
持久化	NFS	-

目录结构¶

electricity_monitoring/
├── entry_electric_task.py          # 定时任务入口脚本（主入口）
├── .env                            # 环境变量配置文件
├── requirements.txt                # Python依赖清单
├── grafana_dashboard.json          # Grafana监控大盘配置
├── README.md                       # 项目说明文档
├── .processed_img.txt              # 已处理图片记录文件（防重复识别）
├── logs/                           # 日志目录
│   └── ele_monitor.log             # 任务执行日志
├── Pics/                           # 电费账单截图目录
├── ops_lib/                        # 核心工具库
│   ├── logger_module/              # 日志模块
│   │   ├── __init__.py
│   │   └── ops_logger.py
│   ├── file_scan_module.py         # 图片扫描与防重复模块
│   ├── vision_ocr_module/          # OCR识别模块（火山方舟API）
│   │   ├── __init__.py
│   │   └── vision_ocr.py
│   ├── db_electric_module.py       # MySQL数据库操作模块（含阶梯电价计算）
│   └── electric_exporter.py        # Electric Exporter模块（Prometheus指标暴露）
├── k8s/                            # Kubernetes部署配置
│   ├── electric-exporter.yaml      # Electric Exporter部署（Deployment/Service/ServiceMonitor）
│   └── pv/                         # PersistentVolume配置
│       └── 03-prometheus-data-pv.yaml  # Prometheus NFS持久化PV/PVC
├── configs/                        # 配置文件目录
│   └── ele_config.yaml             # 系统配置
├── backups/                        # 运维备份目录（grafana升级等）
│   └── grafana_upgrade_*           # Grafana helm/values/manifest 备份
└── docs/                           # 文档目录
    ├── FAQ.md                      # 常见问题与解决方案
    ├── CHANGELOG.md                # 项目环境变更日志
    ├── sudo_nopasswd_troubleshooting_20260729.md  # sudo免密故障排查
    └── gitlab_force_push_guide_20260729.md        # GitLab强制推送操作

安装与配置¶

1. 环境依赖¶

# 安装Python依赖
pip3 install -r requirements.txt

2. 环境变量配置¶

复制 .env 文件并修改配置：

# 数据库配置
DB_HOST=192.168.0.2
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_DATABASE=electric_monitor

# 火山方舟API配置
ARK_API_KEY=your_api_key
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
ARK_MODEL=doubao-seed-2-0-mini-260428

# 图片扫描配置
PICS_DIR=./Pics
MAX_SCAN_COUNT=1

# 阶梯电价基线（年初至数据库最早记录日期的累计用电量）
YEAR_CUMULATIVE_BASE=1973.56

3. 数据库初始化¶

CREATE DATABASE IF NOT EXISTS electric_monitor CHARACTER SET utf8mb4;

USE electric_monitor;

CREATE TABLE IF NOT EXISTS electric_daily_power (
    record_date DATE PRIMARY KEY COMMENT '记录日期',
    power_kwh FLOAT NOT NULL COMMENT '日用电量(kWh)',
    total_cost FLOAT NOT NULL DEFAULT 0 COMMENT '日电费(元)',
    step1_kwh FLOAT NOT NULL DEFAULT 0 COMMENT '第一阶梯用电量(kWh)',
    step2_kwh FLOAT NOT NULL DEFAULT 0 COMMENT '第二阶梯用电量(kWh)',
    step3_kwh FLOAT NOT NULL DEFAULT 0 COMMENT '第三阶梯用电量(kWh)',
    step1_cost FLOAT NOT NULL DEFAULT 0 COMMENT '第一阶梯费用(元)',
    step2_cost FLOAT NOT NULL DEFAULT 0 COMMENT '第二阶梯费用(元)',
    step3_cost FLOAT NOT NULL DEFAULT 0 COMMENT '第三阶梯费用(元)',
    year_cumulative_kwh FLOAT NOT NULL DEFAULT 0 COMMENT '年累计用电量(kWh)',
    year_cumulative_cost FLOAT NOT NULL DEFAULT 0 COMMENT '年累计电费(元)',
    create_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    update_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='日用电量数据表';

使用方法¶

手动执行数据采集¶

cd /home/rian/Documents/electricity_monitoring
python3 entry_electric_task.py

查看日志¶

tail -f /home/rian/Documents/electricity_monitoring/logs/ele_monitor.log

检查Electric Exporter指标¶

curl http://localhost:9105/metrics

Kubernetes部署¶

1. 部署Electric Exporter¶

kubectl apply -f k8s/electric-exporter.yaml -n monitoring

2. 部署NFS持久化存储¶

# MySQL持久化
kubectl apply -f pv/02-mysql-data-pv.yaml

# Prometheus持久化
kubectl apply -f pv/03-prometheus-data-pv.yaml

3. 配置Grafana数据源¶

通过Grafana UI添加MySQL数据源： - 名称：MySQL-Electric - Host：mysql-svc.server.svc.cluster.local:3306 - Database：electric_monitor - User：root - Password：your_password

4. 导入监控大盘¶

curl -X POST http://grafana-host/api/dashboards/db \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -d @grafana_dashboard.json

定时任务配置¶

系统使用Linux crontab设置每日定时任务：

# 添加定时任务（每天20:00执行）
(crontab -l 2>/dev/null; echo "0 20 * * * cd /home/rian/Documents/electricity_monitoring && python3 entry_electric_task.py >> /home/rian/Documents/electricity_monitoring/logs/ele_monitor.log 2>&1") | crontab -

# 查看定时任务
crontab -l

阶梯电价计算规则¶

阶梯档位	年累计用电量	单价(元/度)
第一阶梯	≤2160度	0.558
第二阶梯	2161~4800度	0.608
第三阶梯	>4800度	0.858

计算逻辑： - 每日用电量根据年累计用电量自动分档计费 - 年累计用电量在每年1月1日自动重置为0 - 支持设置年初累计基线（YEAR_CUMULATIVE_BASE）

监控大盘展示¶

Grafana监控大盘包含以下面板：

面板组	面板名称	显示内容
数据概览	当月累计用电量(度)	当月用电量统计
数据概览	当月累计电费(元)	当月电费统计
数据概览	最大日用电量(度)	当月最大用电量
数据概览	平均日用电量(度)	当月平均用电量
数据概览	当年累计用电量(度)	当年累计用电量
数据概览	当年累计电费(元)	当年累计电费
月度趋势	每日用电量趋势(度)	用电量趋势折线图
月度趋势	每日电费趋势(元)	电费趋势折线图
月度趋势	每日用电量对比(度)	用电量柱状图
月度趋势	每日电费对比(元)	电费柱状图
阶梯分析	第一阶梯使用率	阶梯一使用百分比
阶梯分析	第二阶梯使用率	阶梯二使用百分比
阶梯分析	当月阶梯用电分布(度)	各阶梯用电量饼图

配置参考¶

`.env` 文件参数说明¶

参数	说明	默认值
`DB_HOST`	MySQL数据库主机	-
`DB_PORT`	MySQL数据库端口	3306
`DB_USER`	MySQL用户名	root
`DB_PASSWORD`	MySQL密码	-
`DB_DATABASE`	数据库名称	electric_monitor
`ARK_API_KEY`	火山方舟API密钥	-
`ARK_BASE_URL`	火山方舟API地址	https://ark.cn-beijing.volces.com/api/v3
`ARK_MODEL`	豆包多模态模型名称	doubao-seed-2-0-mini-260428
`PICS_DIR`	图片扫描目录	./Pics
`MAX_SCAN_COUNT`	每次扫描最大图片数	1
`YEAR_CUMULATIVE_BASE`	年初累计用电量基线	0

故障排查¶

常见问题¶

问题	原因	解决方案
OCR识别失败	API密钥错误或模型未开通	检查ARK_API_KEY，在火山方舟控制台开通模型
MySQL连接失败	网络不通或权限错误	检查DB_HOST配置，确保数据库可访问
数据重复入库	未记录已处理图片	检查`.processed_img.txt`文件
Grafana显示No data	MySQL数据源未配置	确认MySQL数据源连接正常
阶梯电费计算错误	基线配置不正确	重新计算并设置YEAR_CUMULATIVE_BASE

日志查看¶

# 任务执行日志
tail -f logs/ele_monitor.log

# Electric Exporter日志
kubectl logs -l app=electric-exporter -n monitoring -f

# Prometheus日志
kubectl logs -l app=prometheus -n monitoring -f

代码规范¶

Python代码遵循PEP8规范
所有异常必须使用try-except捕获并记录日志
代码添加详细中文注释
配置信息通过环境变量管理，禁止硬编码敏感信息

许可证¶

本项目仅供个人学习和家庭使用。

贡献¶

欢迎提交Issue和Pull Request。

项目文件清单¶

以下是项目清理后保留的所有文件及其作用说明：

根目录文件¶

文件	作用
`entry_electric_task.py`	定时任务主入口脚本，串联完整业务流程（扫描→OCR→数据库）
`.env`	环境变量配置文件（数据库连接、API密钥、图片路径等）
`requirements.txt`	Python依赖清单
`README.md`	项目说明文档
`.processed_img.txt`	已处理图片记录文件，防止重复识别
`grafana_dashboard.json`	Grafana监控大盘配置，包含14个面板

核心工具库（ops_lib/）¶

文件/目录	作用
`ops_lib/db_electric_module.py`	MySQL数据库操作模块，含阶梯电价计算逻辑
`ops_lib/file_scan_module.py`	图片扫描与防重复模块，只处理ctime最新的图片
`ops_lib/electric_exporter.py`	Electric Exporter模块，从MySQL暴露Prometheus指标
`ops_lib/vision_ocr_module/`	OCR识别模块，调用火山方舟豆包API提取用电量数据
`ops_lib/logger_module/`	统一日志工具模块，支持文件滚动和控制台输出

Kubernetes部署配置（k8s/）¶

文件	作用
`k8s/electric-exporter.yaml`	Electric Exporter的Deployment、Service、ServiceMonitor配置
`k8s/pv/02-mysql-data-pv.yaml`	MySQL NFS持久化PV/PVC配置
`k8s/pv/03-prometheus-data-pv.yaml`	Prometheus NFS持久化PV/PVC配置

配置文件（configs/）¶

文件	作用
`configs/ele_config.yaml`	系统配置文件

文档目录（docs/）¶

文件	作用
`docs/FAQ.md`	常见问题与解决方案
`docs/CHANGELOG.md`	项目环境变更日志

运行时目录¶

目录	作用
`logs/`	任务执行日志目录
`Pics/`	电费账单截图目录

项目版本：v1.0 最后更新：2026年7月

来源：/home/rain/Documents/electricity_monitoring/README.md ｜最后更新：2026-08-27 17:39（由 build/sync.py 同步，请勿在站点侧修改）