郑州大学宿舍电量监控:ZZU-Dorm-Electricity-Balance

郑州大学宿舍电量监控:ZZU-Dorm-Electricity-Balance
Elykia碎碎念
终于考完了期末考试,这段时间真是因考试忙得不可开交,根本没时间更新博客。前几天,晚上11点宿舍突然因为欠费停电,而逆天郑州大学移动校园平台晚上又无法充值电费,只能等到白天处理。这次半夜断电的事件让我深刻意识到,自动化查询和预警的必要性。于是,我决定写一个工具来监测电费余额,提前预警,避免再次遇到这种尴尬的情况。
研发过程
我在 GitHub 上看到了 TorCroft 学长的 ZZU-Electricity 项目,但可惜大佬已经毕业,项目不再维护。而且项目中内置的 ZZU-API 也由于年代久远,无人维护,经常报错。正当我一筹莫展时,看到了 Illustar0 同学的 ZZU.Py 项目,它封装了郑州大学移动校园 APP 的 API,更加高效简洁。于是,我尝试将原项目中的 ZZU-API 替换为 ZZU.Py,最终取得了很好的效果。除此之外,我还仿照 ZZU-Electricity 的监控逻辑,完善了展示网页,并将通知方式改为通过 Server 酱 、 Telegram 和 邮件(新增) 发送通知,最终完成了本项目elykia-cn/ZZU-Dorm-Electricity-Balance: 郑州大学宿舍用电记录,达到了我的目的。感谢 @Illustar0 和 @SirTamago 的帮助。
部署教程
详细的部署过程可以参考筱荷同学的教程 郑州大学宿舍电量监控部署方法。
项目介绍
核心功能
- 实时电量监控:通过 ZZU.Py 实时获取宿舍电量余额,监控照明和空调设备的用电情况。
- 智能提醒:当电量低于设定阈值时,自动通过 Server 酱,邮件 和 Telegram 发送通知,确保用户及时充值。
- 历史记录:记录每月电量使用数据,支持查看和分析历史用电情况,帮助用户更好地管理电量。
- 多平台通知:支持 Server 酱和 Telegram 两种通知方式,满足不同用户的需求。
- 数据版本控制:电量数据会自动保存到新的 Git 分支中,以便查看历史记录并进行版本控制。
技术亮点
- 基于 ZZU.Py 实现高效、稳定的电量数据获取。
- 结合 ZZU-Electricity 的监控逻辑,实现电量余额的实时监控与提醒。
- 支持Server 酱和 Telegram 等多平台通知,确保用户不会错过重要提醒。
- 电量数据会根据设定的定时任务自动生成更新,并提交到新的 Git 分支。
功能
- 每隔一段时间获取宿舍照明和空调的电量余额。
- 自动判断电量状态,并根据设定的阈值(默认为5.0)发送警告通知。
- 通过 Server 酱,邮件 和 Telegram 通知宿舍住户电量状态。
- 提供一个简单的前端页面,显示电量数据和图表。
技术栈
- Python:主要用于数据采集、处理和发送通知。
- ZZUPy:郑州大学移动校园的 Python API 封装。
- Telegram Bot API:通过 Telegram 发送通知。
- Server 酱:通过 Server 酱发送通知。
- 邮箱:测试QQ邮箱能用,其他自行测试。
- ECharts:用于前端展示电量数据图表。
- GitHub Actions:用于自动化构建和部署,自动检查更新并部署到 GitHub Pages。
配置
- Repository Secrets:需要在GitHub Secrets中添加以下变量:
环境变量 | 描述 |
---|---|
ACCOUNT |
郑州大学移动校园登录账户 |
PASSWORD |
郑州大学移动校园登录密码 |
lt_room |
照明电量账户 |
ac_room |
空调电量账户 |
TELEGRAM_BOT_TOKEN |
Telegram Bot Token |
TELEGRAM_CHAT_ID |
Telegram Chat ID |
SERVERCHAN_KEY |
Server 酱 API 密钥 |
SERVERCHAN_KEY2 |
多个Server 酱 API 密钥 |
SERVERCHAN_KEY3 |
多个Server 酱 API 密钥 |
EMAIL |
发送邮件和接收邮件 |
SMTP_CODE |
邮箱 SMTP 的 授权码 |
SMTP_SERVER |
邮箱的 SMTP 服务器地址 |
- 创建数据存储文件夹:该项目会将数据保存在
./page/data
文件夹下,请确保该文件夹存在。
自动化工作流
该项目使用 GitHub Actions 进行自动化管理。工作流触发时会:
- 定时触发:工作流通过
cron
表达式每天在 北京时间 12:00、15:00、18:00、21:00、24:00 自动运行。 - 手动触发:也可以通过 GitHub 界面手动触发工作流执行。
工作流步骤
- Checkout:拉取项目代码,确保获取最新的提交记录,深度为 2,以便能够查看历史提交。
- 设置 Python 环境:使用
actions/setup-python@v5
配置 Python 3.12 环境,确保运行 Python 脚本所需的环境准备好。 - 安装依赖:通过
pip
安装项目所需的 Python 依赖,确保requirements.txt
中列出的所有依赖都被安装。 - 克隆页面分支:从 GitHub 仓库克隆最新的
page
分支,并将data
文件夹的内容复制到目标目录,确保页面数据更新。 - 运行 Python 脚本:执行
index.py
和markdown.py
脚本,处理项目中的数据并生成更新内容,同时将脚本的输出添加到 GitHub Actions 的步骤摘要中。 - Git 配置:配置 Git 用户名和邮箱,确保提交使用正确的身份。
- 提交更改:如果有更新,创建新的分支并提交更改,推送到 GitHub 仓库的
page
分支,提交信息包含当前的时间戳,标明这是定时更新。 - 设置 GitHub Pages:配置 GitHub Pages 环境,准备将更新的页面文件上传到 GitHub Pages 上。
- 上传构建的页面:将生成的页面文件(如
index.html
、style.css
、data
等)上传,以便在 GitHub Pages 上部署。 - 删除旧的工作流运行:使用
Mattraks/delete-workflow-runs@v2
清理 30 天前的工作流记录,确保保持工作流历史的整洁,同时保留至少 6 次的工作流运行记录。 - 部署到 GitHub Pages:在
deploy
阶段,使用actions/deploy-pages@v4
将更新后的页面文件部署到 GitHub Pages 上,确保页面展示的是最新的内容。 - 保持活跃工作流:使用
gautamkrishnar/keepalive-workflow@v2
插件,确保即使没有实际变动,工作流也会保持活跃,避免由于长时间未执行而导致工作流被停止。
示例通知
电量充足:
🏠宿舍电量通报🏠
💡 照明剩余电量:25.0 度(充足)
❄️ 空调剩余电量:50.0 度(充足)电量不足:
⚠️宿舍电量预警⚠️
💡 照明剩余电量:4.5 度(⚠️警告)
❄️ 空调剩余电量:3.0 度(⚠️警告)
⚠️ 电量不足,请尽快充电!
常见问题
1. 登录失败怎么办?
请确保您提供的账号和密码正确,并且 ZZUPy
的 API 接口正常工作。如果仍然无法登录,请检查网络连接或参考 ZZUPy
的文档)。
2. Telegram 通知无法发送?
请确保您设置了正确的 Telegram Bot Token 和 Chat ID,并且 Telegram Bot 有权向该 Chat ID 发送消息。
3. Server 酱 通知无法发送?
因 Server 酱 每日发送数量的限制较为严格,仅为5条/天,故设置为只有 电量不足 预警时才会发送消息,Telegram Bot 无此限制,每次运行 GitHub Actions 都会发送电量消息。
4. 数据没有更新?
请确保程序能正常读取 ./page/data
文件夹中的 JSON 文件。如果该文件夹没有数据,请先运行程序获取初始数据。
结语
希望 ZZU-Dorm-Electricity-Balance 能为同学们的校园生活带来便利。本人也是 门外汉,非计算机相关专业,代码可能非常简陋,欢迎提交 Issue 或 Pull Request。如果你有任何建议或问题,欢迎在 GitHub 上提交 Issue 或 Pull Request。