admin/GPA_Monitoring
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

1

Browse Source
This commit is contained in:
ChuXun
2026-01-29 04:44:49 +08:00
parent d1dc08a16d
commit 2e0e4ea8c6
11 changed files with 0 additions and 490 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
docs/BUG修复_邮件课程列表不正确.md Normal file
View File

@@ -0,0 +1,213 @@
# BUG修复：邮件通知课程列表不正确
## 问题描述
**症状：**
- 日志显示检测到2门新增课程：
- 马克思主义基本原理 (A3505000018)
- 软件需求分析与设计 (A0801050220)
- 但邮件通知显示的是3门**完全不同**的课程：
- C++程序设计
- 体育(三) 乒乓球
- 概率论与数理统计
## 根本原因
代码逻辑错误：
```python
# 错误的实现
if self.check_grade_changes(grade_info, grade_html):
courses_file = self.script_dir / '.last_courses.txt'
if courses_file.exists():
# ❌ 发送的是当前所有课程的前3门，而不是新增课程
self.send_email_notification(current_courses[:3])
```
### 问题分析
1. `check_grade_changes` 函数内部计算了新增课程列表 `new_courses`
2. 但函数只返回 `True/False`，**没有返回新增课程列表**
3. 主循环中使用了 `current_courses[:3]`（当前所有课程的前3门）
4. 导致邮件中显示的课程与实际新增的课程不一致
### 举例说明
**场景：**
- 之前有6门课程：A、B、C、D、E、F
- 新增2门课程：G、H
- 当前总共8门课程：A、B、C、D、E、F、G、H
**错误行为：**
- 日志显示：新增2门（G、H）✓ 正确
- 邮件显示：A、B、C（前3门）❌ 错误
**期望行为：**
- 邮件显示：G、H ✓ 正确
## 修复方案
### 1. 修改 `check_grade_changes` 函数签名
```python
# 修改前
def check_grade_changes(self, current_content: str, current_html: str = None) -> bool:
# 修改后
def check_grade_changes(self, current_content: str, current_html: str = None) -> tuple:
"""检查成绩是否有变化
Returns:
tuple: (是否有变化: bool, 新增课程列表: list)
"""
```
### 2. 返回新增课程列表
```python
# 修改前
if new_courses:
# ... 记录日志 ...
return True
# 修改后
if new_courses:
# ... 记录日志 ...
return (True, new_courses) # 返回元组
# 其他情况
return (False, []) # 无变化
return (True, []) # 有变化但无新增课程（成绩更新）
```
### 3. 更新调用代码
```python
# 修改前
if self.check_grade_changes(grade_info, grade_html):
self.send_email_notification(current_courses[:3]) # ❌ 错误
# 修改后
has_changes, new_courses = self.check_grade_changes(grade_info, grade_html)
if has_changes:
if new_courses:
# 有新增课程，发送真正的新增课程列表
self.send_email_notification(new_courses) # ✅ 正确
else:
# 没有新增课程但内容变化（成绩更新），发送通用通知
self.send_email_notification()
```
## 修复效果
### 修复前
```
日志：
[INFO] ✓ 检测到新增课程成绩！共 2 门
[INFO] 1. [2025-2026 秋季] 马克思主义基本原理 (A3505000018)
[INFO] 2. [2025-2026 秋季] 软件需求分析与设计 (A0801050220)
邮件：
新增课程（共3门）：
- 2025-2026 秋季 C++程序设计 ❌ 错误！
- 2025-2026 秋季 体育(三) 乒乓球 ❌ 错误！
- 2025-2026 秋季 概率论与数理统计 ❌ 错误！
```
### 修复后
```
日志：
[INFO] ✓ 检测到新增课程成绩！共 2 门
[INFO] 1. [2025-2026 秋季] 马克思主义基本原理 (A3505000018)
[INFO] 2. [2025-2026 秋季] 软件需求分析与设计 (A0801050220)
邮件：
新增课程（共2门）：
- 2025-2026 秋季 马克思主义基本原理 ✅ 正确！
- 2025-2026 秋季 软件需求分析与设计 ✅ 正确！
```
## 测试建议
### 1. 单元测试场景
**场景1：新增课程**
- 之前：3门课程
- 现在：5门课程（新增2门）
- 期望：邮件显示新增的2门
**场景2：成绩更新**
- 之前：5门课程
- 现在：5门课程（某门成绩变化）
- 期望：邮件显示通用通知
**场景3：无变化**
- 之前：5门课程
- 现在：5门课程（完全相同）
- 期望：不发送邮件
### 2. 集成测试
```bash
# 1. 删除历史记录（模拟首次运行）
cd ~/grade_monitor
rm .last_*
# 2. 运行测试
python3 monitor.py --test
# 3. 再次运行（模拟检测到变化）
# 手动编辑 .last_courses.txt，删除几行
python3 monitor.py --test
# 4. 检查邮件内容是否正确
```
## 影响评估
### 向后兼容性
- ✅ 完全兼容：函数返回元组，Python 会自动解包
- ✅ 不影响测试模式：test_fetch 不调用此函数
- ✅ 不影响旧版数据：历史文件格式不变
### 风险等级
- 🟢 **低风险**：仅修改返回值类型
- 🟢 所有调用点已更新
- 🟢 已通过语法检查
## 部署步骤
```bash
# 1. 本地打包
cd /mnt/e/50425/Documents/Github/GPA_Monitoring
./打包.sh
# 2. 上传到服务器
scp gpa_monitor.tar.gz user@server:~/
# 3. 服务器上更新
systemctl stop grade-monitor
cd ~/grade_monitor
cp monitor.py monitor.py.backup.$(date +%Y%m%d_%H%M%S)
tar -xzf ~/gpa_monitor.tar.gz
systemctl restart grade-monitor
# 4. 验证
tail -f monitor.log
```
## 后续优化建议
1. **添加单元测试** - 测试 `check_grade_changes` 函数
2. **记录邮件内容** - 在日志中记录发送的课程列表
3. **邮件确认机制** - 发送成功后记录一份副本
---
**BUG编号：** #001
**严重程度：** 高（数据不一致）
**修复日期：** 2026-01-21
**修复人员：** GitHub Copilot
**测试状态：** 待用户验证

408
docs/Debian服务器部署指南.md Normal file
View File

@@ -0,0 +1,408 @@
# 成绩监控系统 - Debian服务器部署指南
## 📦 项目文件说明
### 必需文件（需要上传到服务器）
| 文件名 | 用途 | 何时使用 |
|--------|------|----------|
| `monitor.py` | **主程序** | 运行监控的核心文件 |
| `config.ini` | **配置文件** | 包含账号密码、邮箱配置（⚠️ 敏感文件） |
| `requirements.txt` | **Python依赖列表** | 安装Python包时使用 |
| `setup_python.sh` | **环境安装脚本** | 首次部署时执行，安装所有依赖 |
| `grade-monitor.service` | **systemd服务配置** | 设置开机自启和后台运行 |
### 可选文件（参考文档）
| 文件名 | 用途 |
|--------|------|
| `config（模板）.ini` | 配置文件模板，新用户参考 |
| `readme.md` | 项目说明文档 |
| `部署.md` | 详细部署步骤 |
| `常见问题解决.md` | 常见问题和解决方案 |
### 不需要的文件（不要上传）
- `venv/` - 虚拟环境（服务器上重新创建）
- `.git/` - Git仓库（可选）
- `.last_*` - 运行时生成的缓存文件
- `monitor.log` - 运行时生成的日志文件
---
## 🚀 Debian服务器部署步骤
### 第一步：准备文件
```bash
# 在本地打包必需文件
cd /mnt/e/50425/Documents/Github/GPA_Monitoring
# 创建压缩包（只包含必需文件）
tar -czf gpa_monitor.tar.gz \
monitor.py \
config.ini \
requirements.txt \
setup_python.sh \
grade-monitor.service \
readme.md
# 查看压缩包内容
tar -tzf gpa_monitor.tar.gz
```
### 第二步：上传到服务器
```bash
# 方法1：使用 scp
scp gpa_monitor.tar.gz 用户名@服务器IP:/home/用户名/
# 方法2：使用 rsync（推荐）
rsync -avz gpa_monitor.tar.gz 用户名@服务器IP:/home/用户名/
# 方法3：使用 sftp
sftp 用户名@服务器IP
put gpa_monitor.tar.gz
```
### 第三步：在服务器上解压并安装
```bash
# 登录到Debian服务器
ssh 用户名@服务器IP
# 解压文件
cd ~
tar -xzf gpa_monitor.tar.gz
cd gpa_monitor # 或者你解压到的目录
# 给脚本添加执行权限
chmod +x setup_python.sh
# 运行安装脚本（会自动安装Python、创建虚拟环境、安装依赖）
./setup_python.sh
```
### 第四步：检查配置文件
```bash
# 编辑配置文件（如果需要修改）
nano config.ini
# 确认配置正确：
# - USERNAME 和 PASSWORD（学号和密码）
# - 邮箱配置（SENDER_EMAIL、SENDER_PASSWORD、RECEIVER_EMAIL）
# - CHECK_INTERVAL（建议120秒以上）
```
### 第五步：测试运行
```bash
# 激活虚拟环境
source venv/bin/activate
# 测试运行（获取一次成绩，不进行监控）
python3 monitor.py --test
# 如果测试成功，运行正式监控
python3 monitor.py
# 按 Ctrl+C 停止
```
---
## 🔧 设置后台运行（三选一）
### 方案A：使用 tmux（推荐，简单易用）
```bash
# 1. 安装 tmux（如果没有）
sudo apt update
sudo apt install tmux
# 2. 创建会话并运行
tmux new -s grade_monitor
source venv/bin/activate
python3 monitor.py
# 3. 离开会话（程序继续运行）
# 按 Ctrl+B，然后按 D
# 4. 重新连接查看
tmux attach -t grade_monitor
# 5. 查看所有会话
tmux ls
```
**tmux 使用时机：**
- ✅ 测试阶段使用
- ✅ 需要随时查看程序输出
- ✅ 临时运行，不需要开机自启
---
### 方案B：使用 systemd 服务（推荐，生产环境）
**`grade-monitor.service` 文件用途：**
这是 systemd 服务配置文件，告诉系统如何启动、管理和自动重启你的程序。
```bash
# 1. 编辑服务文件，修改用户名和路径
nano grade-monitor.service
# 确保这些路径正确：
# User=你的用户名
# WorkingDirectory=/home/你的用户名/gpa_monitor
# ExecStart=/home/你的用户名/gpa_monitor/venv/bin/python3 /home/你的用户名/gpa_monitor/monitor.py
# 2. 复制服务文件到系统目录
sudo cp grade-monitor.service /etc/systemd/system/
# 3. 重新加载 systemd
sudo systemctl daemon-reload
# 4. 启动服务
sudo systemctl start grade-monitor
# 5. 查看状态
sudo systemctl status grade-monitor
# 6. 设置开机自启
sudo systemctl enable grade-monitor
```
**systemd 常用命令：**
```bash
# 启动
sudo systemctl start grade-monitor
# 停止
sudo systemctl stop grade-monitor
# 重启
sudo systemctl restart grade-monitor
# 查看状态
sudo systemctl status grade-monitor
# 查看日志
journalctl -u grade-monitor -f
# 开机自启
sudo systemctl enable grade-monitor
# 禁用自启
sudo systemctl disable grade-monitor
```
**systemd 使用时机：**
- ✅ 生产环境长期运行
- ✅ 需要开机自启动
- ✅ 程序崩溃后自动重启
- ✅ 系统化管理
---
### 方案C：使用 nohup（最简单，但不推荐）
```bash
# 后台运行
source venv/bin/activate
nohup python3 monitor.py > output.log 2>&1 &
# 查看进程
ps aux | grep monitor.py
# 停止程序
pkill -f monitor.py
```
**nohup 使用时机：**
- ✅ 临时快速运行
- ❌ 不适合长期运行
- ❌ 程序崩溃不会自动重启
---
## 📊 监控和维护
### 查看日志
```bash
# 查看监控日志（程序自己的日志）
tail -f ~/gpa_monitor/monitor.log
# 查看最后100行
tail -n 100 ~/gpa_monitor/monitor.log
# 搜索关键词
grep "新增课程" ~/gpa_monitor/monitor.log
# 查看系统日志（如果用systemd）
sudo journalctl -u grade-monitor -f
sudo journalctl -u grade-monitor --since "1 hour ago"
```
### 检查运行状态
```bash
# 方法1：查看进程
ps aux | grep monitor.py
# 方法2：查看日志时间戳
ls -lh ~/gpa_monitor/monitor.log
# 方法3：systemd状态（如果用systemd）
sudo systemctl status grade-monitor
```
### 更新程序
```bash
# 1. 停止程序
# tmux: Ctrl+C 或 tmux kill-session -t grade_monitor
# systemd: sudo systemctl stop grade-monitor
# 2. 备份配置
cp config.ini config.ini.backup
# 3. 上传新版本文件并解压
# 4. 恢复配置
cp config.ini.backup config.ini
# 5. 重启程序
# tmux: 重新运行
# systemd: sudo systemctl restart grade-monitor
```
---
## 🔒 安全建议
### 1. 保护配置文件
```bash
# 设置文件权限（只有所有者可读写）
chmod 600 config.ini
# 查看权限
ls -l config.ini
# 应该显示：-rw------- 1 用户名 用户名
```
### 2. 不要上传敏感文件到 GitHub
在 `.gitignore` 中添加：
```
config.ini
*.log
.last_*
venv/
```
### 3. 定期检查日志
```bash
# 检查是否有异常
grep -i "error\|fail\|warning" monitor.log
# 检查登录情况
grep "登录" monitor.log | tail -20
```
---
## ❓ 常见问题
### Q1: 如何确认程序在运行？
```bash
# 方法1：查看进程
ps aux | grep monitor.py
# 方法2：查看日志最后几行
tail monitor.log
# 方法3：查看文件修改时间
ls -lh monitor.log
```
### Q2: 程序报错"请不要过快点击"怎么办？
```bash
# 编辑配置文件，增加检查间隔
nano config.ini
# 修改 CHECK_INTERVAL 为更大的值（如300秒）
CHECK_INTERVAL = 300
# 重启程序
```
### Q3: 如何在多台服务器部署？
```bash
# 每台服务器重复部署步骤，注意：
# 1. 每台服务器使用不同的监控账号（如果可能）
# 2. 适当增加 CHECK_INTERVAL 避免同时访问
# 3. 可以设置不同的邮件接收地址
```
### Q4: 忘记 tmux 会话名怎么办？
```bash
# 列出所有会话
tmux ls
# 连接到第一个会话
tmux attach
```
---
## 📝 快速命令参考
```bash
# === 部署 ===
tar -xzf gpa_monitor.tar.gz
cd gpa_monitor
chmod +x setup_python.sh
./setup_python.sh
# === 运行 ===
# 测试
source venv/bin/activate && python3 monitor.py --test
# tmux运行
tmux new -s grade_monitor
source venv/bin/activate && python3 monitor.py
# systemd运行
sudo cp grade-monitor.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl start grade-monitor
sudo systemctl enable grade-monitor
# === 监控 ===
# 查看日志
tail -f monitor.log
# 查看状态
sudo systemctl status grade-monitor
# === 停止 ===
# tmux: Ctrl+C
# systemd: sudo systemctl stop grade-monitor
# nohup: pkill -f monitor.py
```
---
## 📞 获取帮助
- 查看项目 README: `cat readme.md`
- 查看常见问题: `cat 常见问题解决.md`
- 查看详细部署: `cat 部署.md`
- 查看程序帮助: `python3 monitor.py --help`

239
docs/常见问题解决.md Normal file
View File

@@ -0,0 +1,239 @@
# 常见问题解决方案
## 🚨 "未能提取到成绩信息，共 0 门课程" 错误
### 问题症状
日志中反复出现：
```
[WARNING] 未能提取到成绩信息，返回原始文本
[INFO] 成绩无变化（共 0 门课程）
```
### 快速诊断
#### 1. 检查 BeautifulSoup 是否安装
```bash
python3 -c "import bs4; print('BeautifulSoup4 已安装')"
```
如果报错，安装依赖：
```bash
pip3 install beautifulsoup4
# 或完整安装所有依赖
pip3 install -r requirements.txt
```
#### 2. 使用调试模式查看详细信息
```bash
cd ~/grade_monitor
python3 monitor.py --test --debug
```
查看输出中是否有：
- ✅ "找到成绩表格"
- ✅ "找到 X 行成绩数据"
- ✅ "共解析到 X 门课程"
如果都没有，继续下一步。
#### 3. 检查是否登录失效
查看日志是否有 "检测到登录页面" 错误：
```bash
grep "登录页面\|LOGIN_REQUIRED" ~/grade_monitor/monitor.log
```
如果有，重启服务重新登录：
```bash
systemctl restart grade-monitor
```
#### 4. 查看调试HTML文件
程序会自动保存问题页面到 `debug_page.html`：
```bash
cd ~/grade_monitor
# 检查文件是否存在
ls -lh debug_page.html
# 查看是否包含成绩表格
grep -i "gridtable\|课程名称\|成绩" debug_page.html | head -5
```
### 解决方案
**方案1：重新安装依赖并重启**
```bash
cd ~/grade_monitor
pip3 install -r requirements.txt
systemctl restart grade-monitor
tail -f monitor.log
```
**方案2：启用调试模式监控**
编辑服务配置：
```bash
sudo nano /etc/systemd/system/grade-monitor.service
```
修改 ExecStart 行：
```ini
ExecStart=/usr/bin/python3 /home/yourusername/grade_monitor/monitor.py --debug
```
重新加载并重启：
```bash
sudo systemctl daemon-reload
sudo systemctl restart grade-monitor
tail -f ~/grade_monitor/monitor.log
```
**方案3：如果是网页结构变化**
查看详细排查指南：
```bash
cat ~/grade_monitor/故障排查指南.md
```
---
## ⚠️ "请不要过快点击" 错误
### 问题原因
学校WebVPN系统有严格的访问频率限制，短时间内多次访问会被拦截。
### 解决方案
#### 1. 停止手动测试至少5分钟
```bash
# 如果在服务器上运行，请先停止程序
ps aux | grep monitor.py
kill <进程ID>
# 等待至少5分钟后再重新测试
```
#### 2. 修改配置文件增加间隔
编辑 `config.ini`：
```ini
[monitor]
# 将检查间隔改为5分钟（300秒）或更长
CHECK_INTERVAL = 300
# 增加请求延迟
REQUEST_DELAY = 15
# 增加重试间隔
RETRY_DELAY = 60
```
#### 3. 使用正确的测试方式
```bash
# 测试前确保距离上次测试至少5分钟
python3 monitor.py --test
# 如果还是被拦截，等10分钟后再试
```
#### 4. 部署后不要频繁测试
```bash
# 部署systemd服务后，让它自动运行
sudo systemctl start grade-monitor
# 只通过日志查看运行情况
tail -f monitor.log
# 不要反复启停服务或手动测试
```
## 🔍 如何判断系统正常工作
### 方法1：查看日志
```bash
tail -f ~/grade_monitor/monitor.log
```
正常日志应该类似：
```
2026-01-17 10:00:00 - INFO - 开始检查成绩变化...
2026-01-17 10:00:05 - INFO - 登录成功！
2026-01-17 10:00:10 - INFO - 成功获取成绩页面
2026-01-17 10:00:12 - INFO - 未发现新课程
2026-01-17 10:02:00 - INFO - 等待下次检查...
```
### 方法2：查看保存的成绩文件
```bash
cat ~/.last_grade_content.txt
```
如果文件包含完整的课程列表和GPA，说明系统工作正常。
### 方法3：查看进程状态
```bash
ps aux | grep monitor.py
```
如果有进程在运行，说明程序正在监控中。
## 📝 最佳实践
### 测试阶段
1. **首次测试**：运行 `python3 monitor.py --test`
2. **等待5分钟**
3. **再次测试**：确认能正常获取成绩
4. **等待10分钟**
5. **部署服务**：配置systemd或使用tmux
### 运行阶段
1. **设置CHECK_INTERVAL为120秒或更长**
2. **让程序自动运行，不要手动干预**
3. **每天查看一次日志即可**
4. **不要频繁重启服务**
### 如果被持续拦截
1. **停止所有监控程序**
2. **等待至少30分钟**
3. **将CHECK_INTERVAL改为600秒（10分钟）**
4. **重新启动，让它慢慢运行**
5. **确认稳定后，再逐步减少间隔**
## 🛠️ 调试技巧
### 查看实际响应内容
```bash
cat ~/grade_monitor/.debug_response.html
```
如果文件包含"请不要过快点击"，说明请求被拦截。
### 检查登录状态
```bash
# 运行测试模式
python3 monitor.py --test
# 查看是否成功登录
grep "登录成功" monitor.log
```
### 测试网络连接
```bash
# 测试是否能访问学校网站
curl -I https://webvpn.neu.edu.cn
# 测试SMTP邮件服务器
nc -zv smtp.163.com 465
```
## 💡 温馨提示
1. **成绩更新频率不高**：学校不会每分钟更新成绩，建议CHECK_INTERVAL设为120-300秒
2. **避免过度监控**：频繁访问可能被学校系统封禁IP
3. **合理设置间隔**：既能及时发现新成绩，又不会触发限流
4. **信任自动化**：部署后让程序自己运行，不需要频繁检查
## 📞 仍然无法解决？
1. 检查配置文件中的账号密码是否正确
2. 确认能在浏览器中正常登录学校系统
3. 查看 `.debug_response.html` 了解实际响应
4. 将CHECK_INTERVAL增加到600秒（10分钟）
5. 考虑只在特定时间段运行（如每天上午10点和下午3点）

179
docs/快速更新指南.md Normal file
View File

@@ -0,0 +1,179 @@
# 快速更新指南 - 修复会话过期问题
## 🎯 本次更新解决的问题
**症状：** 程序运行几小时后出现：
```
[WARNING] 未能提取到成绩信息，返回原始文本
[INFO] 成绩无变化（共 0 门课程）
```
**原因：** 登录会话过期，需要重新登录
**解决：** ✅ 自动检测并重新登录
---
## 📦 方式1：快速更新（推荐）
### 在本地打包
```bash
cd /mnt/e/50425/Documents/Github/GPA_Monitoring
chmod +x 打包.sh
./打包.sh
```
### 上传到服务器
```bash
scp gpa_monitor.tar.gz 用户名@服务器IP:~/
```
### 在服务器上更新
```bash
# 停止服务
systemctl stop grade-monitor
# 备份
cd ~/grade_monitor
cp monitor.py monitor.py.backup.$(date +%Y%m%d)
# 解压更新
tar -xzf ~/gpa_monitor.tar.gz -C ~/grade_monitor
# 赋予权限
chmod +x diagnose.sh
# 重启服务
systemctl restart grade-monitor
# 查看日志（确认自动重新登录功能）
tail -f monitor.log
```
---
## 🔧 方式2：仅更新 monitor.py
如果只想更新主程序文件：
### 在本地
```bash
# WSL中
cd /mnt/e/50425/Documents/Github/GPA_Monitoring
scp monitor.py 用户名@服务器IP:~/grade_monitor/
```
### 在服务器上
```bash
systemctl stop grade-monitor
systemctl start grade-monitor
tail -f ~/grade_monitor/monitor.log
```
---
## ✅ 验证更新成功
查看日志，应该能看到：
### 正常运行
```
[INFO] 开始新一轮检查
[INFO] 获取成绩页面...
[DEBUG] 找到成绩表格
[INFO] 成功提取成绩信息，共 17 行
[INFO] 共解析到 15 门课程
[INFO] 成绩无变化（共 15 门课程）
```
### 会话过期时自动处理
```
[WARNING] 检测到会话过期，尝试重新登录...
[INFO] 开始登录统一身份认证...
[INFO] 登录成功！成功访问成绩页面
[INFO] 重新登录成功，继续监控
```
---
## 🔍 故障诊断
如果更新后仍有问题：
```bash
cd ~/grade_monitor
# 运行诊断工具
./diagnose.sh
# 或手动测试
python3 monitor.py --test --debug
# 查看生成的调试文件
ls -lh debug_page.html
cat .last_grade_content.txt
```
---
## 📋 更新内容详细列表
1. **会话过期自动重新登录** (monitor.py 第697-718行)
- 检测 `LOGIN_REQUIRED` 状态
- 自动调用 `login()` 重新登录
- 记录详细日志
2. **改进成绩提取** (monitor.py 第286-370行)
- 检测登录页面
- 支持多种表格选择器
- 自动保存 debug_page.html
- 添加详细调试日志
3. **改进课程解析** (monitor.py 第375-405行)
- 检测登录失效
- 识别未解析的HTML
- 统计课程数量
4. **新增调试模式**
- `python3 monitor.py --debug`
- 显示详细运行信息
5. **新增诊断工具**
- `diagnose.sh` - 自动检测并给出建议
- `故障排查指南.md` - 详细排查步骤
---
## 💡 最佳实践
1. **定期检查日志**（每天1-2次即可）
```bash
tail -n 50 ~/grade_monitor/monitor.log
```
2. **不要频繁重启服务**
- 新版本会自动处理会话过期
- 只在真正出问题时才重启
3. **保留备份**
```bash
# 每次更新前都会自动备份
ls -lh ~/grade_monitor/monitor.py.backup.*
```
4. **合理设置检查间隔**
- 建议 120-300 秒
- 避免触发学校系统限流
---
## 🆘 需要帮助？
1. 先运行诊断工具：`./diagnose.sh`
2. 查看故障排查指南：`cat 故障排查指南.md`
3. 查看详细修复说明：`cat 修复说明_2026-01-21.md`
---
**更新日期：** 2026-01-21
**版本：** v2.0 - 自动会话恢复版

143
docs/故障排查指南.md Normal file
View File

@@ -0,0 +1,143 @@
# 故障排查指南
## 问题：未能提取到成绩信息，共 0 门课程
### 症状
日志中出现以下警告信息：
```
[WARNING] 未能提取到成绩信息，返回原始文本
[INFO] 成绩无变化（共 0 门课程）
```
### 可能的原因和解决方案
#### 1. BeautifulSoup 未安装
**检查方法：**
```bash
python3 -c "import bs4; print('BeautifulSoup4 已安装')"
```
**解决方案：**
```bash
pip3 install beautifulsoup4
# 或
pip3 install -r requirements.txt
```
#### 2. 登录会话失效
**症状：** 日志中可能出现 "检测到登录页面" 的错误
**解决方案：**
```bash
# 停止服务
systemctl stop grade-monitor
# 重新启动服务（会重新登录）
systemctl start grade-monitor
```
#### 3. 网页结构变化
**检查方法：**
程序会自动保存 HTML 到 `debug_page.html`，查看这个文件：
```bash
# 查看 debug_page.html 是否存在
ls -la ~/grade_monitor/debug_page.html
# 查看 HTML 内容，确认是否有成绩表格
grep -i "gridtable\|课程名称\|成绩" ~/grade_monitor/debug_page.html
```
**解决方案：**
如果网页结构变化，可能需要修改 `monitor.py` 中的 `extract_grade_info` 函数。
当前支持的表格选择器：
- `<table class="gridtable">`
- `<table id="dataList">`
- 任何包含"课程名称"或"成绩"关键词的表格
#### 4. 启用调试模式排查
**临时测试（手动运行）：**
```bash
cd ~/grade_monitor
python3 monitor.py --test --debug
```
**查看详细日志：**
```bash
# 启用调试模式修改服务配置
sudo nano /etc/systemd/system/grade-monitor.service
# 在 ExecStart 行添加 --debug 参数
ExecStart=/usr/bin/python3 /home/yourusername/grade_monitor/monitor.py --debug
# 重新加载并重启
sudo systemctl daemon-reload
sudo systemctl restart grade-monitor
# 查看详细日志
tail -f ~/grade_monitor/monitor.log
```
#### 5. 检查保存的文件
```bash
cd ~/grade_monitor
# 查看上次提取的成绩内容
cat .last_grade_content.txt
# 查看上次保存的 HTML（如果存在）
cat .last_grade_page.html | head -50
# 查看调试 HTML（出错时自动保存）
cat debug_page.html | head -50
```
### 调试流程
1. **启用调试模式运行一次测试：**
```bash
cd ~/grade_monitor
python3 monitor.py --test --debug
```
2. **查看输出信息：**
- 是否显示 "找到成绩表格"？
- 是否显示 "找到 X 行成绩数据"？
- 是否显示 "共解析到 X 门课程"？
3. **检查保存的文件：**
```bash
# 如果生成了 debug_page.html
ls -lh debug_page.html
# 查看是否包含成绩表格
grep -A 5 "gridtable\|dataList" debug_page.html
```
4. **如果是网页结构问题：**
- 将 `debug_page.html` 发给开发者
- 或者自己检查 HTML 中的表格结构
- 修改 `extract_grade_info` 函数中的选择器
### 常见问题
**Q: 日志显示"未找到成绩表格"**
A: 网页结构可能变化，需要查看 debug_page.html 确认实际的表格结构
**Q: 日志显示"找到 0 行成绩数据"**
A: 表格找到了但是为空，可能是：
- 登录失效，返回的是空表格
- 实际就是没有成绩数据
**Q: 日志显示"检测到未解析的HTML内容"**
A: BeautifulSoup 解析失败，返回了原始 HTML。检查：
1. BeautifulSoup 是否正确安装
2. HTML 格式是否正确（查看 debug_page.html）
### 联系支持
如果以上方法都无法解决问题，请提供：
1. `monitor.log` 的最后 50 行
2. `debug_page.html` 文件（如果存在）
3. `.last_grade_content.txt` 文件内容
4. 是否能手动登录并看到成绩页面

516
docs/部署.md Normal file
View File

@@ -0,0 +1,516 @@
# 服务器部署指南
本文档详细说明如何将成绩监控系统部署到Linux服务器上。
## 📋 前置要求
- Linux服务器（Debian/Ubuntu/CentOS等）
- Python 3.7+
- 服务器能访问外网
- SSH访问权限
## 📦 准备文件
### 需要上传的文件
```
grade_monitor/
├── monitor.py # 主程序（必需）
├── config.ini # 配置文件（必需）
├── requirements.txt # Python依赖（必需）
├── setup_python.sh # 安装脚本（必需）
└── readme.md # 说明文档（可选）
```
### 打包文件
在Windows本地执行：
```powershell
# 方法1：使用tar（需要WSL或Git Bash）
tar -czf grade_monitor.tar.gz monitor.py config.ini requirements.txt setup_python.sh readme.md
# 方法2：使用7-Zip或WinRAR手动打包
```
## 🚀 部署步骤
### 步骤1：修改配置文件
**在上传前**，确保 `config.ini` 中填入了正确的信息：
```ini
[login]
USERNAME = 你的学号
PASSWORD = 你的密码
LOGIN_URL = ...
GRADE_URL = ...
[email]
SENDER_EMAIL = your_email@163.com
SENDER_PASSWORD = SMTP授权码
RECEIVER_EMAIL = 接收通知的邮箱
[monitor]
CHECK_INTERVAL = 60
REQUEST_DELAY = 5
MAX_RETRIES = 3
RETRY_DELAY = 10
```
### 步骤2：上传到服务器
#### 方法A：使用SCP上传
```bash
# 上传打包文件
scp grade_monitor.tar.gz username@server-ip:/home/username/
# 或直接上传文件
scp monitor.py config.ini requirements.txt setup_python.sh username@server-ip:/home/username/grade_monitor/
```
#### 方法B：使用SFTP上传
```bash
sftp username@server-ip
put grade_monitor.tar.gz
exit
```
#### 方法C：使用FTP客户端
使用FileZilla、WinSCP等工具上传文件。
### 步骤3：连接到服务器
```bash
ssh username@server-ip
```
### 步骤4：解压和安装
```bash
# 创建工作目录
mkdir -p ~/grade_monitor
cd ~/grade_monitor
# 添加执行权限
chmod +x setup_python.sh
# 运行安装脚本
./setup_python.sh
```
安装脚本会自动：
- 更新apt包列表
- 安装Python3和pip
- 创建虚拟环境
- 安装所需的Python包（requests、beautifulsoup4）
### 步骤5：测试运行
```bash
# 激活虚拟环境
source venv/bin/activate
# 测试模式运行
python3 monitor.py --test
```
**检查输出：**
- 是否成功登录
- 是否获取到成绩页面
- 查看提取的成绩内容
```bash
# 查看提取的成绩
cat .last_grade_content.txt
# 应该看到类似这样的内容：
# ============================================================
# 总平均绩点：4.3471
# ============================================================
#
# 学年学期 | 课程代码 | 课程序号 | 课程名称 | ...
# --------------------------------------------------------
# 2025-2026 秋季 | A0801051020 | A095478 | C++程序设计 | ...
```
## 🔄 后台运行方案
### 方案A：使用systemd（推荐，适合长期运行）
#### 1. 创建服务文件
```bash
sudo nano /etc/systemd/system/grade-monitor.service
```
#### 2. 填入以下内容
```ini
[Unit]
Description=Grade Monitoring Service
After=network.target
[Service]
Type=simple
User=你的用户名
WorkingDirectory=/home/你的用户名/grade_monitor
ExecStart=/home/你的用户名/grade_monitor/venv/bin/python3 /home/你的用户名/grade_monitor/monitor.py
Restart=always
RestartSec=30
StandardOutput=append:/home/你的用户名/grade_monitor/monitor.log
StandardError=append:/home/你的用户名/grade_monitor/monitor.log
[Install]
WantedBy=multi-user.target
```
**注意：** 将上面的"你的用户名"替换为实际的Linux用户名
#### 3. 启动服务
```bash
# 重载systemd配置
sudo systemctl daemon-reload
# 启用开机自启
sudo systemctl enable grade-monitor
# 启动服务
sudo systemctl start grade-monitor
# 查看服务状态
sudo systemctl status grade-monitor
```
#### 4. 管理服务
```bash
# 查看日志
sudo journalctl -u grade-monitor -f
# 停止服务
sudo systemctl stop grade-monitor
# 重启服务
sudo systemctl restart grade-monitor
# 禁用开机自启
sudo systemctl disable grade-monitor
```
### 方案B：使用tmux（简单，适合临时运行）
#### 1. 安装tmux
```bash
# Debian/Ubuntu
sudo apt install tmux
# CentOS/RHEL
sudo yum install tmux
```
#### 2. 创建会话并运行
```bash
# 创建新的tmux会话
tmux new -s grade_monitor
# 激活虚拟环境
source venv/bin/activate
# 运行程序
python3 monitor.py
```
#### 3. 离开和重连会话
```bash
# 离开会话（程序继续运行）
# 按键：Ctrl+B，然后按 D
# 重新连接到会话
tmux attach -t grade_monitor
# 查看所有会话
tmux ls
# 关闭会话
tmux kill-session -t grade_monitor
```
### 方案C：使用screen
```bash
# 安装screen
sudo apt install screen
# 创建新会话
screen -S grade_monitor
# 激活环境并运行
source venv/bin/activate
python3 monitor.py
# 离开会话：Ctrl+A，然后按 D
# 重新连接
screen -r grade_monitor
# 查看所有会话
screen -ls
```
### 方案D：使用nohup（最简单）
```bash
# 激活虚拟环境
source venv/bin/activate
# 后台运行
nohup python3 monitor.py > monitor.log 2>&1 &
# 查看进程
ps aux | grep monitor.py
# 停止进程
kill <进程ID>
```
## 📊 监控和维护
### 查看运行状态
```bash
# 方法1：查看日志文件
tail -f ~/grade_monitor/monitor.log
# 方法2：查看systemd日志（如果使用systemd）
sudo journalctl -u grade-monitor -n 50 -f
# 方法3：查看进程
ps aux | grep monitor.py
```
### 查看当前成绩
```bash
cd ~/grade_monitor
cat .last_grade_content.txt
```
### 手动触发测试
```bash
cd ~/grade_monitor
source venv/bin/activate
python3 monitor.py --test
```
## 🔧 常见问题
### 问题1：连接服务器失败
**可能原因：**
- SSH端口被防火墙拦截
- 服务器IP或用户名错误
- SSH密钥配置问题
**解决方法：**
```bash
# 指定端口
ssh -p 端口号 username@server-ip
# 使用密钥
ssh -i /path/to/key.pem username@server-ip
```
### 问题2：无法访问学校网站
**可能原因：**
- 服务器在校外，需要VPN
- 防火墙拦截
**解决方法：**
- 使用校内服务器
- 配置代理
- 联系网络管理员
### 问题3：pip安装失败
**解决方法：**
```bash
# 更新pip
pip install --upgrade pip
# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或使用清华源
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
```
### 问题4：权限不足
**解决方法：**
```bash
# 修改文件所有者
sudo chown -R username:username ~/grade_monitor
# 修改执行权限
chmod +x ~/grade_monitor/*.sh
```
### 问题5：邮件发送失败
**解决方法：**
- 确认SMTP授权码正确（不是邮箱密码）
- 检查服务器能否访问smtp.163.com（端口465）
- 查看详细错误信息：`tail -f monitor.log`
```bash
# 测试网络连接
telnet smtp.163.com 465
# 或
nc -zv smtp.163.com 465
```
## 🔐 安全建议
### 1. 保护配置文件
```bash
# 限制config.ini权限
chmod 600 ~/grade_monitor/config.ini
# 确保只有自己能访问
ls -la ~/grade_monitor/config.ini
# 应显示：-rw------- 1 username username
```
### 2. 使用环境变量（可选）
不在配置文件中存储明文密码，而是使用环境变量：
```bash
# 设置环境变量
export GRADE_USERNAME="你的学号"
export GRADE_PASSWORD="你的密码"
export EMAIL_PASSWORD="SMTP授权码"
# 添加到.bashrc使其永久生效
echo 'export GRADE_USERNAME="你的学号"' >> ~/.bashrc
echo 'export GRADE_PASSWORD="你的密码"' >> ~/.bashrc
echo 'export EMAIL_PASSWORD="SMTP授权码"' >> ~/.bashrc
```
### 3. 定期更新
```bash
# 更新系统
sudo apt update && sudo apt upgrade
# 更新Python包
cd ~/grade_monitor
source venv/bin/activate
pip install --upgrade requests beautifulsoup4
```
## 📱 监控建议
### 设置监控脚本
创建一个检查脚本 `check_status.sh`：
```bash
#!/bin/bash
# 检查进程是否运行
if pgrep -f "monitor.py" > /dev/null; then
echo "✓ 监控程序正在运行"
else
echo "✗ 监控程序未运行！"
# 可以在这里添加重启逻辑
# systemctl start grade-monitor
fi
# 检查最近的日志
echo ""
echo "最近的日志："
tail -n 5 ~/grade_monitor/monitor.log
```
### 定期检查（使用cron）
```bash
# 编辑crontab
crontab -e
# 添加以下行（每天检查一次）
0 12 * * * /home/username/grade_monitor/check_status.sh
```
## 🎯 完整部署示例
```bash
# === 本地操作（Windows/WSL） ===
cd E:\50425\Documents\Github\GPA_Monitoring
tar -czf grade_monitor.tar.gz monitor.py config.ini requirements.txt setup_python.sh readme.md
scp grade_monitor.tar.gz user@server.com:~/
# === 服务器操作 ===
ssh user@server.com
# 解压和安装
mkdir -p ~/grade_monitor
cd ~/grade_monitor
tar -xzf ../grade_monitor.tar.gz
chmod +x setup_python.sh
./setup_python.sh
# 测试
source venv/bin/activate
python3 monitor.py --test
cat .last_grade_content.txt
# 配置systemd服务
sudo nano /etc/systemd/system/grade-monitor.service
# （填入服务配置）
sudo systemctl daemon-reload
sudo systemctl enable grade-monitor
sudo systemctl start grade-monitor
sudo systemctl status grade-monitor
# 查看日志
sudo journalctl -u grade-monitor -f
```
## ✅ 部署检查清单
- [ ] 文件已上传到服务器
- [ ] config.ini配置正确（账号、密码、邮箱）
- [ ] 运行setup_python.sh安装依赖
- [ ] 测试模式运行成功
- [ ] 成绩提取格式正确
- [ ] 配置后台运行（systemd/tmux/screen）
- [ ] 服务正常启动
- [ ] 日志输出正常
- [ ] 收到测试邮件
- [ ] 设置文件权限（chmod 600 config.ini）
## 📞 获取帮助
如果遇到问题：
1. 查看 `monitor.log` 了解详细错误
2. 运行 `python3 monitor.py --test` 测试
3. 检查 `.debug_response.html` 了解实际响应
4. 查看 `readme.md` 了解更多功能说明
---
部署完成后，系统将自动监控成绩变化，有新课程成绩时会立即发送邮件通知！

56
docs/重启服务.md Normal file
View File

@@ -0,0 +1,56 @@
# 停止服务
systemctl stop grade-monitor
# 备份旧文件
cp monitor.py monitor.py.backup
# 解压新文件（会覆盖）
tar -xzf ~/gpa_monitor.tar.gz -C ~/grade_monitor --strip-components=0
# 或者只替换 monitor.py
# 你可以直接编辑：
nano monitor.py
# 重启服务
systemctl restart grade-monitor
# 查看实时日志
tail -f monitor.log
# 或查看最近的日志（包含完整上下文）
tail -n 100 monitor.log
---
## 常见问题：会话过期
如果日志显示：
```
[WARNING] 未能提取到成绩信息，返回原始文本
[INFO] 成绩无变化（共 0 门课程）
```
**原因：** 登录会话几小时后自动过期
**解决：** 最新版本已自动处理！代码会：
1. 检测到 "LOGIN_REQUIRED" 时自动重新登录
2. 记录日志：`[WARNING] 检测到会话过期，尝试重新登录...`
3. 重新登录后继续监控
**手动重启（如果需要）：**
```bash
systemctl restart grade-monitor
tail -f monitor.log
```
**调试模式（查看详细信息）：**
```bash
# 手动测试
python3 monitor.py --test --debug
# 或修改服务启用调试
sudo nano /etc/systemd/system/grade-monitor.service
# 在 ExecStart 添加 --debug 参数
sudo systemctl daemon-reload
sudo systemctl restart grade-monitor
```