项目简介
宿舍电费监控系统是一个自动化监控工具,定期检测校园宿舍剩余电量并在电量不足时发送邮件提醒。 系统提供 Web 管理界面（仪表盘/配置/扫码登录），支持多账号（多 source）轮询，并在 Cookie 失效或低电量时自动邮件告警。
适用场景: 适合需要实时掌握宿舍电费状态的学生,避免突然断电影响学习生活。
功能特性
自动化监控
定时自动检测电量,无需手动操作
邮件提醒
低电量告警 + Cookie 失效修复提醒（含扫码链接）
响应式界面
支持手机/平板/电脑访问
多账号/多宿舍（source）
按 source 独立保存 Cookie 与 UA，统一合并展示数据
管理员权限
配置/暂停监控等操作走管理员 Token 鉴权
告警防轰炸
低电量告警带冷却时间，网络故障自动退避重试
快速开始
本项目支持 Docker 容器部署（推荐） 与 Python 直接运行。建议使用 Docker Compose 以获得更稳定的运行环境。
1上传代码与进入目录
将项目压缩包上传至服务器，解压后进入目录：
cd 代码目录
2准备配置文件
复制示例配置并修改（包含敏感信息，勿提交到Git）：
cp config.example.ini config.ini
3启动服务
使用 Docker Compose 一键构建并启动：
docker compose up -d --build
常用运维命令：
# 查看日志
docker logs -f dorm_monitor
# 重启服务
docker restart dorm_monitor
# 停止并删除容器
docker compose down
4打开仪表盘与扫码页
-
仪表盘：
http://<服务器IP>:5000/ -
帮助页：
http://<服务器IP>:5000/help -
扫码登录：
http://<服务器IP>:5000/login
5首次设置管理员 Token（推荐）
配置接口（如读取/保存邮件参数、阈值、sources 等）需要管理员 Token。你可以在仪表盘右上角点击管理员按钮登录/设置。
6配置邮件与阈值
进入“配置”页，建议至少完成：
- SMTP 邮箱：
[notify].smtp_*、[notify].from - 收件人：
[notify].to（或更精细的 rooms/sources 映射） - 低电量阈值：
[system].low_power_threshold
7登录系统（配置 Cookie）
有两种方式配置 Cookie：
- 扫码登录(推荐): 打开
/login，使用微信扫码后系统自动保存JSESSIONID - 手动输入: 通过仪表盘的“手动输入 Cookie”（后端走
/api/manual-cookie）
8发送测试邮件
点击"发送测试邮件"按钮,确认邮件配置正常。如果收到测试邮件,说明系统配置成功。
Cookie获取教程
方式一 扫码自动获取 (推荐)
优先推荐：直接使用系统自带的扫码页 /login 获取 Cookie（无需手动抓包）。
- 默认扫码：
/login - 指定某个账号(source)的扫码：
/login?source=xxx - 二维码卡住/失效：
/login?force=1或/login-restart
扫码登录前提: 必须已绑定微信
扫码功能依赖微信授权。如果不确定是否已绑定，请先访问学校的 统一身份认证页面 尝试扫码登录。若在官方页面无法扫码登录，说明未绑定微信，此时本系统也无法使用扫码功能（只能使用下面的 Cookie 提取法）。
方式二 手动提取 Cookie
系统抓取页面依赖业务站点的会话 Cookie（核心是 JSESSIONID）。
Cookie 失效时，监控线程会在连续失败且判定为“需要重新登录”后，自动发送“修复邮件”，邮件里会带上可点击的扫码链接（链接由 [system].server_ip + web_port 生成）。
重要提示: 请勿将Cookie分享给他人，这是你的登录凭证!
电脑端
方法1: 提取链接后缀 (推荐)
-
使用浏览器访问 统一身份认证 进行登录。
-
成功登录后的界面如下：
-
复制地址栏中的
JSESSIONID=xxxxxxxxx部分。
方法2: 使用开发者工具
- 参考方法一进行登录。
-
按 F12 打开开发者工具。
-
切换到 Network (网络) 选项卡。
- 刷新页面 (F5)。
-
点击任意请求，在右侧找到 Request Headers (请求头)，找到
Cookie:字段，复制其中的JSESSIONID=xxxxxxxxx部分。
手机端
建议使用 电脑端的方法一 获取，因为手机端浏览器通常无法方便地使用开发者工具查看 Cookie。
格式说明: Cookie 格式为 JSESSIONID=一串字母数字，
如果只复制了后面的值，系统会自动补全前缀。
配置说明
所有配置存放在项目根目录的 config.ini。
系统支持多 source：每个 source 对应独立的 [auth.<source>] 段（独立 Cookie/UA），监控线程会按 [system].auth_sources 轮询并合并结果。
1) system（运行参数）
| 键 | 作用 | 示例/推荐 |
|---|---|---|
| interval | 监控抓取间隔（秒）。网络/服务器故障时会自动退避（更快重试）。 | 900（15 分钟） |
| web_port | Web 服务监听端口。 | 5000 |
| server_ip | 用于生成“修复邮件”里的扫码链接（必须是收件人能访问到的地址）。 | 同局域网：192.168.x.x；本机：127.0.0.1 |
| low_power_threshold | 低电量阈值（度），低于该值发送告警邮件。 | 15 |
| low_power_alert_cooldown_seconds | 同一房间低电量告警冷却时间（秒），防止轰炸。 | 21600（6 小时） |
| auth_sources | 要轮询的 source 列表（逗号/分号/换行分隔）。 | x3-721a,x3-721b,x3-721k |
2) auth（Cookie/UA）与多 source
[auth]：旧版单账号段（兼容）。[auth.<source>]：推荐使用的多账号段，每个 source 单独保存cookie与user_agent。- 如果未设置
auth_sources且只配置了[auth].cookie，系统会进入 legacy 单源模式，避免重复轮询同一 Cookie。
[auth.x3-721b]\ncookie = JSESSIONID=...\nuser_agent = Mozilla/5.0 ...
3) notify（邮件）与收件人策略
系统支持三层收件人优先级（从高到低）：
- 按房间：
[notify.rooms] - 按 source 默认：
[notify.sources] - 回退到默认：
[notify].to（以及兼容旧模式的 group_a/group_b/group_k）
[notify]\nsmtp_server = smtp.qq.com\nsmtp_port = 465\nsmtp_tls = ssl\nsmtp_username = your_email@qq.com\nsmtp_password = your_smtp_password\nfrom = your_email@qq.com\nto = a@example.com,b@example.com\n\n[notify.sources]\nx3-721b = a@example.com,b@example.com\n\n[notify.rooms]\n3-721B空调 = a@example.com
4) admin（管理员 Token）
管理员 Token 用于保护配置/测试邮件/暂停监控等接口，后端通过请求头 X-Admin-Token 校验。
[admin]\nadmin_token = your_token_here
5) auth.labels（source 显示名称）
用于把 source 显示成更易懂的中文名（仪表盘展示时更友好）：
[auth.labels]\nx3-721a = 琇3-721A\nx3-721b = 琇3-721B
常见问题/排障
Q: Cookie多久会失效?
A: 通常几天到一周,失效后系统会发邮件提醒,重新扫码即可。
Q: 运行 python main.py 直接退出(Exit Code 1)怎么办?
A: 常见原因与处理：
- 依赖缺失：先执行 pip install -r requirements.txt
- Python 环境不一致：确认运行的是同一个 Python（建议在虚拟环境中安装依赖）
- 端口被占用：修改 config.ini 中 [system].web_port
Q: 为什么没收到邮件通知?
A: 请检查:
- 收件人邮箱是否正确
- 检查垃圾邮件箱
- 点击"发送测试邮件"验证配置
- QQ邮箱等需要使用“SMTP授权码”，不是邮箱登录密码
- 如果配置了 [notify.rooms]/[notify.sources]，收件人可能被更高优先级覆盖
Q: 可以监控多个房间吗?
A: 可以!如果你的账号绑定了多个房间,系统会自动显示所有房间的电量。
Q: 什么是 source? 为什么要配置多个?
A: source 是“账号/宿舍”的逻辑标识。每个 source 对应一份 Cookie/UA（例如 [auth.x3-721b]）。系统会按 [system].auth_sources 轮询抓取并合并展示。
Q: 手动输入Cookie后没反应?
A: Cookie 保存后会“请求立即刷新”，一般很快生效；如果仍无数据：
- 确认 Cookie 只需要 JSESSIONID=...
- 确认对应 source 正确（多 source 场景尤其常见）
- 学校系统可能短暂 502/超时，稍后重试即可
Q: 显示"Cookie已失效"怎么办?
A: 点击"扫码登录"或"手动输入"重新设置Cookie即可。
Q: 扫码页不出二维码 / 一直失败?
A: 这是 Selenium/Chrome 环境问题居多：
- 确认本机已安装 Chrome；或换用非精简系统环境
- 公司/校园网可能拦截 webdriver 下载；可手动放置 chromedriver.exe 到项目目录
- 二维码可能已过期：用 /login?force=1 重新生成
API接口
系统提供以 /api 为前缀的 JSON 接口。部分接口需要管理员 Token：在请求头里带 X-Admin-Token: <token>。
公开接口
GET /api/status：系统状态（监控是否运行、上次数据、sources 状态等）GET /api/login-state：扫码登录状态（不含二维码图片）
管理员接口（需要 X-Admin-Token）
GET /api/config：读取配置（含敏感项，必须鉴权）POST /api/config：保存配置（interval/threshold/cooldown/收件人映射/auth_sources/auth_labels 等）POST /api/test-email：发送测试邮件（可选指定 to）POST /api/toggle-monitoring：暂停/恢复监控（body: {enabled: true/false}）GET /api/admin/check：是否已设置管理员 TokenPOST /api/admin/setup：首次设置管理员 TokenPOST /api/admin/login：管理员登录
Cookie 相关接口
POST /api/manual-cookie：手动设置某个 source 的 Cookie（body: {source, cookie, user_agent}）
curl -H "X-Admin-Token: your_token" http://127.0.0.1:5000/api/config
技术栈
Python 3.8+
Flask
Requests
Selenium
BeautifulSoup4
Alpine.js
Tailwind CSS
需要帮助?
如果遇到问题,建议先查看运行日志（终端输出）并确认配置是否生效
# 安装依赖（首次）
pip install -r requirements.txt
# 启动服务
python main.py