admin/GPA_Monitoring

Fork 0

Files

ChuXun 4c41df3e39 创建完整使用文档.md

2026-01-29 04:45:15 +08:00

21 KiB

Raw Blame History

成绩监控系统 - 完整使用文档

最后更新： 2026-01-29
版本： v2.0 - 自动会话恢复版

📑 目录

服务器部署指南
快速更新指南
故障排查指南
常见问题解决
服务管理
历史BUG修复记录

服务器部署指南

📋 前置要求

Linux服务器（Debian/Ubuntu/CentOS等）
Python 3.7+
服务器能访问外网
SSH访问权限

📦 项目文件说明

必需文件（需要上传到服务器）

文件名	用途	何时使用
`monitor.py`	主程序	运行监控的核心文件
`config.ini`	配置文件	包含账号密码、邮箱配置（⚠️ 敏感文件）
`requirements.txt`	Python依赖列表	安装Python包时使用
`setup_python.sh`	环境安装脚本	首次部署时执行，安装所有依赖
`grade-monitor.service`	systemd服务配置	设置开机自启和后台运行

可选文件（参考文档）

文件名	用途
`config（模板）.ini`	配置文件模板，新用户参考
`README.md`	项目说明文档
`diagnose.sh`	故障诊断脚本

不需要的文件（不要上传）

venv/ - 虚拟环境（服务器上重新创建）
.git/ - Git仓库（可选）
.last_* - 运行时生成的缓存文件
monitor.log - 运行时生成的日志文件

🚀 部署步骤

第一步：准备文件

# 在本地打包必需文件（WSL或Git Bash）
cd /mnt/e/50425/Documents/Github/GPA_Monitoring

# 创建压缩包（只包含必需文件）
tar -czf gpa_monitor.tar.gz \
    monitor.py \
    config.ini \
    requirements.txt \
    setup_python.sh \
    diagnose.sh \
    grade-monitor.service \
    README.md

# 查看压缩包内容
tar -tzf gpa_monitor.tar.gz

第二步：上传到服务器

# 方法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
exit

第三步：在服务器上解压并安装

# 登录到服务器
ssh 用户名@服务器IP

# 解压文件
cd ~
tar -xzf gpa_monitor.tar.gz
cd grade_monitor  # 或者你解压到的目录

# 给脚本添加执行权限
chmod +x setup_python.sh diagnose.sh

# 运行安装脚本（会自动安装Python、创建虚拟环境、安装依赖）
./setup_python.sh

第四步：检查配置文件

# 编辑配置文件（如果需要修改）
nano config.ini

# 确认配置正确：
# - USERNAME 和 PASSWORD（学号和密码）
# - 邮箱配置（SENDER_EMAIL、SENDER_PASSWORD、RECEIVER_EMAIL）
# - CHECK_INTERVAL（建议120秒以上）

配置文件示例：

[login]
USERNAME = 你的学号
PASSWORD = 你的密码
LOGIN_URL = ...
GRADE_URL = ...

[email]
SENDER_EMAIL = your_email@163.com
SENDER_PASSWORD = SMTP授权码（不是邮箱密码！）
RECEIVER_EMAIL = 接收通知的邮箱

[monitor]
CHECK_INTERVAL = 120  # 建议120-300秒
REQUEST_DELAY = 5
MAX_RETRIES = 3
RETRY_DELAY = 10

第五步：测试运行

# 激活虚拟环境
source venv/bin/activate

# 测试运行（获取一次成绩，不进行监控）
python3 monitor.py --test

# 查看提取的成绩
cat .last_grade_content.txt

🔧 设置后台运行

方案A：使用 systemd（推荐，生产环境）

优点： 开机自启、崩溃自动重启、系统化管理

# 1. 编辑服务文件，修改用户名和路径
nano grade-monitor.service

# 确保这些路径正确：
# User=你的用户名
# WorkingDirectory=/home/你的用户名/grade_monitor
# ExecStart=/home/你的用户名/grade_monitor/venv/bin/python3 /home/你的用户名/grade_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 常用命令：

# 启动
sudo systemctl start grade-monitor

# 停止
sudo systemctl stop grade-monitor

# 重启
sudo systemctl restart grade-monitor

# 查看状态
sudo systemctl status grade-monitor

# 查看日志
sudo journalctl -u grade-monitor -f

# 开机自启
sudo systemctl enable grade-monitor

# 禁用自启
sudo systemctl disable grade-monitor

方案B：使用 tmux（简单易用）

优点： 简单、可随时查看输出、适合测试阶段

# 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

# 6. 关闭会话
tmux kill-session -t grade_monitor

方案C：使用 nohup（最简单）

优点： 快速、无需额外工具

# 后台运行
source venv/bin/activate
nohup python3 monitor.py > output.log 2>&1 &

# 查看进程
ps aux | grep monitor.py

# 停止程序
pkill -f monitor.py

📊 监控和维护

查看日志

# 查看监控日志（程序自己的日志）
tail -f ~/grade_monitor/monitor.log

# 查看最后100行
tail -n 100 ~/grade_monitor/monitor.log

# 搜索关键词
grep "新增课程" ~/grade_monitor/monitor.log

# 查看系统日志（如果用systemd）
sudo journalctl -u grade-monitor -f
sudo journalctl -u grade-monitor --since "1 hour ago"

检查运行状态

# 方法1：查看进程
ps aux | grep monitor.py

# 方法2：查看日志时间戳
ls -lh ~/grade_monitor/monitor.log

# 方法3：systemd状态（如果用systemd）
sudo systemctl status grade-monitor

🔒 安全建议

1. 保护配置文件

# 设置文件权限（只有所有者可读写）
chmod 600 config.ini

# 查看权限
ls -l config.ini
# 应该显示：-rw------- 1 用户名 用户名

2. 不要上传敏感文件到 GitHub

在 .gitignore 中添加：

config.ini
*.log
.last_*
venv/

3. 定期检查日志

# 检查是否有异常
grep -i "error\|fail\|warning" monitor.log

# 检查登录情况
grep "登录" monitor.log | tail -20

快速更新指南

🎯 本功能解决的问题

症状： 程序运行几小时后出现：

[WARNING] 未能提取到成绩信息，返回原始文本
[INFO] 成绩无变化（共 0 门课程）

原因： 登录会话过期，需要重新登录

解决： ✅ 最新版本已自动检测并重新登录

📦 更新方式

方式1：完整更新（推荐）

在本地准备

# WSL或Git Bash中
cd /mnt/e/50425/Documents/Github/GPA_Monitoring

# 创建更新包
tar -czf gpa_monitor.tar.gz \
    monitor.py \
    config.ini \
    requirements.txt \
    setup_python.sh \
    diagnose.sh \
    grade-monitor.service

上传到服务器

scp gpa_monitor.tar.gz 用户名@服务器IP:~/

在服务器上更新

# 停止服务
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：

# 在本地（WSL）
cd /mnt/e/50425/Documents/Github/GPA_Monitoring
scp monitor.py 用户名@服务器IP:~/grade_monitor/

# 在服务器上
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] 重新登录成功，继续监控

💡 最佳实践

定期检查日志（每天1-2次即可）
```
tail -n 50 ~/grade_monitor/monitor.log
```
不要频繁重启服务
- 新版本会自动处理会话过期
- 只在真正出问题时才重启

保留备份

# 每次更新前都会自动备份
ls -lh ~/grade_monitor/monitor.py.backup.*

合理设置检查间隔
- 建议 120-300 秒
- 避免触发学校系统限流

故障排查指南

🚨 问题一："未能提取到成绩信息，共 0 门课程"

症状

日志中反复出现：

[WARNING] 未能提取到成绩信息，返回原始文本
[INFO] 成绩无变化（共 0 门课程）

快速诊断

步骤1：运行诊断工具

cd ~/grade_monitor
./diagnose.sh

诊断工具会自动：

检查 BeautifulSoup 是否安装
运行测试模式
分析测试结果
提供修复建议

步骤2：检查 BeautifulSoup 安装

python3 -c "import bs4; print('BeautifulSoup4 已安装')"

如果报错，安装依赖：

pip3 install beautifulsoup4
# 或完整安装所有依赖
pip3 install -r requirements.txt

步骤3：使用调试模式

cd ~/grade_monitor
python3 monitor.py --test --debug

查看输出中是否有：

✅ "找到成绩表格"
✅ "找到 X 行成绩数据"
✅ "共解析到 X 门课程"

步骤4：检查是否登录失效

grep "登录页面\|LOGIN_REQUIRED" ~/grade_monitor/monitor.log

如果有，重启服务重新登录：

systemctl restart grade-monitor

步骤5：查看调试HTML文件

cd ~/grade_monitor

# 检查文件是否存在
ls -lh debug_page.html

# 查看是否包含成绩表格
grep -i "gridtable\|课程名称\|成绩" debug_page.html | head -5

解决方案

方案1：重新安装依赖并重启

cd ~/grade_monitor
pip3 install -r requirements.txt
systemctl restart grade-monitor
tail -f monitor.log

方案2：启用调试模式监控

# 编辑服务配置
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

方案3：如果是会话过期 最新版本会自动处理！代码会：

检测到 "LOGIN_REQUIRED" 时自动重新登录
记录日志：[WARNING] 检测到会话过期，尝试重新登录...
重新登录后继续监控

方案4：如果是网页结构变化 程序会自动保存 HTML 到 debug_page.html，查看这个文件：

# 查看 HTML 内容，确认是否有成绩表格
cat debug_page.html | grep -i "gridtable\|dataList" -A 10

当前支持的表格选择器：

<table class="gridtable">
<table id="dataList">
任何包含"课程名称"或"成绩"关键词的表格

⚠️ 问题二："请不要过快点击"错误

问题原因

学校WebVPN系统有严格的访问频率限制，短时间内多次访问会被拦截。

解决方案

1. 停止手动测试至少5分钟

# 如果在服务器上运行，请先停止程序
ps aux | grep monitor.py
kill <进程ID>

# 等待至少5分钟后再重新测试

2. 修改配置文件增加间隔

nano config.ini

修改为：

[monitor]
# 将检查间隔改为5分钟（300秒）或更长
CHECK_INTERVAL = 300

# 增加请求延迟
REQUEST_DELAY = 15

# 增加重试间隔
RETRY_DELAY = 60

3. 使用正确的测试方式

# 测试前确保距离上次测试至少5分钟
python3 monitor.py --test

# 如果还是被拦截，等10分钟后再试

4. 部署后不要频繁测试

# 部署systemd服务后，让它自动运行
sudo systemctl start grade-monitor

# 只通过日志查看运行情况
tail -f monitor.log

# 不要反复启停服务或手动测试

🔍 如何判断系统正常工作

方法1：查看日志

tail -f ~/grade_monitor/monitor.log

正常日志应该类似：

2026-01-29 10:00:00 - INFO - 开始检查成绩变化...
2026-01-29 10:00:05 - INFO - 登录成功！
2026-01-29 10:00:10 - INFO - 成功获取成绩页面
2026-01-29 10:00:12 - INFO - 未发现新课程
2026-01-29 10:02:00 - INFO - 等待下次检查...

方法2：查看保存的成绩文件

cat ~/.last_grade_content.txt

如果文件包含完整的课程列表和GPA，说明系统工作正常。

方法3：查看进程状态

ps aux | grep monitor.py

如果有进程在运行，说明程序正在监控中。

📝 调试流程

启用调试模式运行一次测试：

cd ~/grade_monitor
python3 monitor.py --test --debug

查看输出信息：
- 是否显示 "找到成绩表格"？
- 是否显示 "找到 X 行成绩数据"？
- 是否显示 "共解析到 X 门课程"？

检查保存的文件：

# 如果生成了 debug_page.html
ls -lh debug_page.html

# 查看是否包含成绩表格
grep -A 5 "gridtable\|dataList" debug_page.html

如果是网页结构问题：
- 将 debug_page.html 发给开发者
- 或者自己检查 HTML 中的表格结构

常见问题解决

💡 最佳实践

测试阶段

首次测试：运行 python3 monitor.py --test
等待5分钟
再次测试：确认能正常获取成绩
等待10分钟
部署服务：配置systemd或使用tmux

运行阶段

设置CHECK_INTERVAL为120秒或更长
让程序自动运行，不要手动干预
每天查看一次日志即可
不要频繁重启服务

如果被持续拦截

停止所有监控程序
等待至少30分钟
将CHECK_INTERVAL改为600秒（10分钟）
重新启动，让它慢慢运行
确认稳定后，再逐步减少间隔

🛠️ 调试技巧

查看实际响应内容

cat ~/grade_monitor/.debug_response.html

如果文件包含"请不要过快点击"，说明请求被拦截。

检查登录状态

# 运行测试模式
python3 monitor.py --test

# 查看是否成功登录
grep "登录成功" monitor.log

测试网络连接

# 测试是否能访问学校网站
curl -I https://webvpn.neu.edu.cn

# 测试SMTP邮件服务器
nc -zv smtp.163.com 465

🔧 常见问题FAQ

Q1: 如何确认程序在运行？

# 方法1：查看进程
ps aux | grep monitor.py

# 方法2：查看日志最后几行
tail monitor.log

# 方法3：查看文件修改时间
ls -lh monitor.log

Q2: 程序报错"请不要过快点击"怎么办？

编辑配置文件，增加检查间隔：

nano config.ini
# 修改 CHECK_INTERVAL 为更大的值（如300秒）

Q3: 如何在多台服务器部署？

每台服务器重复部署步骤，注意：

每台服务器使用不同的监控账号（如果可能）
适当增加 CHECK_INTERVAL 避免同时访问
可以设置不同的邮件接收地址

Q4: 忘记 tmux 会话名怎么办？

# 列出所有会话
tmux ls

# 连接到第一个会话
tmux attach

Q5: 邮件发送失败怎么办？

确认SMTP授权码正确（不是邮箱密码）
检查服务器能否访问smtp.163.com（端口465）
查看详细错误信息：tail -f monitor.log

# 测试网络连接
telnet smtp.163.com 465
# 或
nc -zv smtp.163.com 465

Q6: 权限不足怎么办？

# 修改文件所有者
sudo chown -R username:username ~/grade_monitor

# 修改执行权限
chmod +x ~/grade_monitor/*.sh

💬 温馨提示

成绩更新频率不高：学校不会每分钟更新成绩，建议CHECK_INTERVAL设为120-300秒
避免过度监控：频繁访问可能被学校系统封禁IP
合理设置间隔：既能及时发现新成绩，又不会触发限流
信任自动化：部署后让程序自己运行，不需要频繁检查

服务管理

🔄 重启服务

使用 systemd

# 停止服务
systemctl stop grade-monitor

# 备份旧文件
cd ~/grade_monitor
cp monitor.py monitor.py.backup

# 如果需要更新文件
# tar -xzf ~/gpa_monitor.tar.gz -C ~/grade_monitor

# 重启服务
systemctl restart grade-monitor

# 查看实时日志
tail -f monitor.log

# 或查看最近的日志（包含完整上下文）
tail -n 100 monitor.log

使用 tmux

# 连接到会话
tmux attach -t grade_monitor

# 停止程序（Ctrl+C）

# 重新运行
source venv/bin/activate
python3 monitor.py

# 离开会话（Ctrl+B 然后 D）

使用 nohup

# 查找进程
ps aux | grep monitor.py

# 停止进程
kill <进程ID>

# 重新启动
cd ~/grade_monitor
source venv/bin/activate
nohup python3 monitor.py > output.log 2>&1 &

📊 日志查看

查看监控日志

# 实时查看
tail -f ~/grade_monitor/monitor.log

# 查看最后N行
tail -n 50 ~/grade_monitor/monitor.log

# 搜索关键词
grep "新增课程\|错误\|warning" ~/grade_monitor/monitor.log

查看系统日志（systemd）

# 实时查看
sudo journalctl -u grade-monitor -f

# 查看最近1小时
sudo journalctl -u grade-monitor --since "1 hour ago"

# 查看今天的日志
sudo journalctl -u grade-monitor --since today

🔍 状态检查

# 检查服务状态（systemd）
sudo systemctl status grade-monitor

# 检查进程
ps aux | grep monitor.py

# 检查最后一次检查时间
ls -lh ~/grade_monitor/monitor.log

# 查看保存的成绩
cat ~/grade_monitor/.last_grade_content.txt

📦 完整更新流程

# 1. 在本地打包
cd /mnt/e/50425/Documents/Github/GPA_Monitoring
tar -czf gpa_monitor.tar.gz monitor.py config.ini requirements.txt setup_python.sh

# 2. 上传到服务器
scp gpa_monitor.tar.gz user@server:~/

# 3. 在服务器上更新
ssh user@server
systemctl stop grade-monitor
cd ~/grade_monitor
cp monitor.py monitor.py.backup.$(date +%Y%m%d)
tar -xzf ~/gpa_monitor.tar.gz
systemctl restart grade-monitor

# 4. 验证
tail -f monitor.log

历史BUG修复记录

BUG #001: 邮件通知课程列表不正确

修复日期： 2026-01-21
严重程度： 高（数据不一致）
修复状态： ✅ 已修复

问题描述

症状：

日志显示检测到2门新增课程：
- 马克思主义基本原理 (A3505000018)
- 软件需求分析与设计 (A0801050220)
但邮件通知显示的是3门完全不同的课程：
- C++程序设计
- 体育(三) 乒乓球
- 概率论与数理统计

根本原因

代码逻辑错误：

# 错误的实现
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])

问题分析：

check_grade_changes 函数内部计算了新增课程列表 new_courses
但函数只返回 True/False，没有返回新增课程列表
主循环中使用了 current_courses[:3]（当前所有课程的前3门）
导致邮件中显示的课程与实际新增的课程不一致

修复方案

修改函数签名：返回元组 (是否有变化: bool, 新增课程列表: list)
返回新增课程列表：return (True, new_courses)
更新调用代码：使用真正的新增课程列表发送邮件

修复效果

修复前：

日志：检测到2门新增课程
邮件：显示3门完全不同的课程 ❌

修复后：

日志：检测到2门新增课程
邮件：准确显示这2门新增课程 ✅

📞 获取帮助

如果遇到问题：

先运行诊断工具：./diagnose.sh
查看本文档的故障排查部分
查看 monitor.log 了解详细错误
运行 python3 monitor.py --test --debug 测试
检查 debug_page.html 了解实际响应

✅ 部署检查清单

文件已上传到服务器
config.ini配置正确（账号、密码、邮箱）
运行setup_python.sh安装依赖
测试模式运行成功
成绩提取格式正确
配置后台运行（systemd/tmux）
服务正常启动
日志输出正常
收到测试邮件
设置文件权限（chmod 600 config.ini）

文档版本： v2.0
最后更新： 2026-01-29
维护者： GitHub Copilot

21 KiB Raw Blame History Unescape Escape

成绩监控系统 - 完整使用文档

📑 目录

服务器部署指南

📋 前置要求

📦 项目文件说明

必需文件（需要上传到服务器）

可选文件（参考文档）

不需要的文件（不要上传）

🚀 部署步骤

第一步：准备文件

第二步：上传到服务器

第三步：在服务器上解压并安装

第四步：检查配置文件

第五步：测试运行

🔧 设置后台运行

方案A：使用 systemd（推荐，生产环境）

方案B：使用 tmux（简单易用）

方案C：使用 nohup（最简单）

📊 监控和维护

查看日志

检查运行状态

🔒 安全建议

1. 保护配置文件

2. 不要上传敏感文件到 GitHub

3. 定期检查日志

快速更新指南

🎯 本功能解决的问题

📦 更新方式

方式1：完整更新（推荐）

在本地准备

上传到服务器

在服务器上更新

方式2：仅更新主程序

✅ 验证更新成功

正常运行

会话过期时自动处理

💡 最佳实践

故障排查指南

🚨 问题一："未能提取到成绩信息，共 0 门课程"

症状

快速诊断

步骤1：运行诊断工具

步骤2：检查 BeautifulSoup 安装

步骤3：使用调试模式

步骤4：检查是否登录失效

步骤5：查看调试HTML文件

解决方案

⚠️ 问题二："请不要过快点击"错误

问题原因

解决方案

1. 停止手动测试至少5分钟

2. 修改配置文件增加间隔

3. 使用正确的测试方式

4. 部署后不要频繁测试

🔍 如何判断系统正常工作

方法1：查看日志

方法2：查看保存的成绩文件

方法3：查看进程状态

📝 调试流程

常见问题解决

💡 最佳实践

测试阶段

运行阶段

如果被持续拦截

🛠️ 调试技巧

查看实际响应内容

检查登录状态

测试网络连接

🔧 常见问题FAQ

Q1: 如何确认程序在运行？

Q2: 程序报错"请不要过快点击"怎么办？

Q3: 如何在多台服务器部署？

Q4: 忘记 tmux 会话名怎么办？

Q5: 邮件发送失败怎么办？

Q6: 权限不足怎么办？

💬 温馨提示

服务管理

🔄 重启服务

使用 systemd

21 KiB

Raw Blame History