1

docs/常见问题解决.md

@@ -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点）