From 4c41df3e39a2c9992a9c04156447c293b007eeb5 Mon Sep 17 00:00:00 2001
From: ChuXun <70203584+ChuXunYu@users.noreply.github.com>
Date: Thu, 29 Jan 2026 04:45:15 +0800
Subject: [PATCH] =?UTF-8?q?=E5=88=9B=E5=BB=BA=20=E5=AE=8C=E6=95=B4?=
 =?UTF-8?q?=E4=BD=BF=E7=94=A8=E6=96=87=E6=A1=A3.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/完整使用文档.md | 996 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 996 insertions(+)
 create mode 100644 docs/完整使用文档.md

diff --git a/docs/完整使用文档.md b/docs/完整使用文档.md
new file mode 100644
index 0000000..3b96db3
--- /dev/null
+++ b/docs/完整使用文档.md
@@ -0,0 +1,996 @@
+# 成绩监控系统 - 完整使用文档
+
+> **最后更新：** 2026-01-29  
+> **版本：** v2.0 - 自动会话恢复版
+
+---
+
+## 📑 目录
+
+1. [服务器部署指南](#服务器部署指南)
+2. [快速更新指南](#快速更新指南)
+3. [故障排查指南](#故障排查指南)
+4. [常见问题解决](#常见问题解决)
+5. [服务管理](#服务管理)
+6. [历史BUG修复记录](#历史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` - 运行时生成的日志文件
+
+## 🚀 部署步骤
+
+### 第一步：准备文件
+
+```bash
+# 在本地打包必需文件（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
+```
+
+### 第二步：上传到服务器
+
+```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
+exit
+```
+
+### 第三步：在服务器上解压并安装
+
+```bash
+# 登录到服务器
+ssh 用户名@服务器IP
+
+# 解压文件
+cd ~
+tar -xzf gpa_monitor.tar.gz
+cd grade_monitor  # 或者你解压到的目录
+
+# 给脚本添加执行权限
+chmod +x setup_python.sh diagnose.sh
+
+# 运行安装脚本（会自动安装Python、创建虚拟环境、安装依赖）
+./setup_python.sh
+```
+
+### 第四步：检查配置文件
+
+```bash
+# 编辑配置文件（如果需要修改）
+nano config.ini
+
+# 确认配置正确：
+# - USERNAME 和 PASSWORD（学号和密码）
+# - 邮箱配置（SENDER_EMAIL、SENDER_PASSWORD、RECEIVER_EMAIL）
+# - CHECK_INTERVAL（建议120秒以上）
+```
+
+配置文件示例：
+```ini
+[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
+```
+
+### 第五步：测试运行
+
+```bash
+# 激活虚拟环境
+source venv/bin/activate
+
+# 测试运行（获取一次成绩，不进行监控）
+python3 monitor.py --test
+
+# 查看提取的成绩
+cat .last_grade_content.txt
+```
+
+## 🔧 设置后台运行
+
+### 方案A：使用 systemd（推荐，生产环境）
+
+**优点：** 开机自启、崩溃自动重启、系统化管理
+
+```bash
+# 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 常用命令：**
+```bash
+# 启动
+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（简单易用）
+
+**优点：** 简单、可随时查看输出、适合测试阶段
+
+```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
+
+# 6. 关闭会话
+tmux kill-session -t grade_monitor
+```
+
+### 方案C：使用 nohup（最简单）
+
+**优点：** 快速、无需额外工具
+
+```bash
+# 后台运行
+source venv/bin/activate
+nohup python3 monitor.py > output.log 2>&1 &
+
+# 查看进程
+ps aux | grep monitor.py
+
+# 停止程序
+pkill -f monitor.py
+```
+
+## 📊 监控和维护
+
+### 查看日志
+
+```bash
+# 查看监控日志（程序自己的日志）
+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"
+```
+
+### 检查运行状态
+
+```bash
+# 方法1：查看进程
+ps aux | grep monitor.py
+
+# 方法2：查看日志时间戳
+ls -lh ~/grade_monitor/monitor.log
+
+# 方法3：systemd状态（如果用systemd）
+sudo systemctl status 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
+```
+
+---
+
+# 快速更新指南
+
+## 🎯 本功能解决的问题
+
+**症状：** 程序运行几小时后出现：
+```
+[WARNING] 未能提取到成绩信息，返回原始文本
+[INFO] 成绩无变化（共 0 门课程）
+```
+
+**原因：** 登录会话过期，需要重新登录
+
+**解决：** ✅ 最新版本已自动检测并重新登录
+
+## 📦 更新方式
+
+### 方式1：完整更新（推荐）
+
+#### 在本地准备
+```bash
+# 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
+```
+
+#### 上传到服务器
+```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/
+
+# 在服务器上
+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. **定期检查日志**（每天1-2次即可）
+   ```bash
+   tail -n 50 ~/grade_monitor/monitor.log
+   ```
+
+2. **不要频繁重启服务**
+   - 新版本会自动处理会话过期
+   - 只在真正出问题时才重启
+
+3. **保留备份**
+   ```bash
+   # 每次更新前都会自动备份
+   ls -lh ~/grade_monitor/monitor.py.backup.*
+   ```
+
+4. **合理设置检查间隔**
+   - 建议 120-300 秒
+   - 避免触发学校系统限流
+
+---
+
+# 故障排查指南
+
+## 🚨 问题一："未能提取到成绩信息，共 0 门课程"
+
+### 症状
+日志中反复出现：
+```
+[WARNING] 未能提取到成绩信息，返回原始文本
+[INFO] 成绩无变化（共 0 门课程）
+```
+
+### 快速诊断
+
+#### 步骤1：运行诊断工具
+```bash
+cd ~/grade_monitor
+./diagnose.sh
+```
+
+诊断工具会自动：
+- 检查 BeautifulSoup 是否安装
+- 运行测试模式
+- 分析测试结果
+- 提供修复建议
+
+#### 步骤2：检查 BeautifulSoup 安装
+```bash
+python3 -c "import bs4; print('BeautifulSoup4 已安装')"
+```
+
+如果报错，安装依赖：
+```bash
+pip3 install beautifulsoup4
+# 或完整安装所有依赖
+pip3 install -r requirements.txt
+```
+
+#### 步骤3：使用调试模式
+```bash
+cd ~/grade_monitor
+python3 monitor.py --test --debug
+```
+
+查看输出中是否有：
+- ✅ "找到成绩表格"
+- ✅ "找到 X 行成绩数据"
+- ✅ "共解析到 X 门课程"
+
+#### 步骤4：检查是否登录失效
+```bash
+grep "登录页面\|LOGIN_REQUIRED" ~/grade_monitor/monitor.log
+```
+
+如果有，重启服务重新登录：
+```bash
+systemctl restart grade-monitor
+```
+
+#### 步骤5：查看调试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 行添加 --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：如果是会话过期**
+最新版本会自动处理！代码会：
+1. 检测到 "LOGIN_REQUIRED" 时自动重新登录
+2. 记录日志：`[WARNING] 检测到会话过期，尝试重新登录...`
+3. 重新登录后继续监控
+
+**方案4：如果是网页结构变化**
+程序会自动保存 HTML 到 `debug_page.html`，查看这个文件：
+```bash
+# 查看 HTML 内容，确认是否有成绩表格
+cat debug_page.html | grep -i "gridtable\|dataList" -A 10
+```
+
+当前支持的表格选择器：
+- `<table class="gridtable">`
+- `<table id="dataList">`
+- 任何包含"课程名称"或"成绩"关键词的表格
+
+## ⚠️ 问题二："请不要过快点击"错误
+
+### 问题原因
+学校WebVPN系统有严格的访问频率限制，短时间内多次访问会被拦截。
+
+### 解决方案
+
+#### 1. 停止手动测试至少5分钟
+```bash
+# 如果在服务器上运行，请先停止程序
+ps aux | grep monitor.py
+kill <进程ID>
+
+# 等待至少5分钟后再重新测试
+```
+
+#### 2. 修改配置文件增加间隔
+```bash
+nano 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-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：查看保存的成绩文件
+```bash
+cat ~/.last_grade_content.txt
+```
+
+如果文件包含完整的课程列表和GPA，说明系统工作正常。
+
+### 方法3：查看进程状态
+```bash
+ps aux | grep monitor.py
+```
+
+如果有进程在运行，说明程序正在监控中。
+
+## 📝 调试流程
+
+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 中的表格结构
+
+---
+
+# 常见问题解决
+
+## 💡 最佳实践
+
+### 测试阶段
+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
+```
+
+## 🔧 常见问题FAQ
+
+### 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秒）
+```
+
+### Q3: 如何在多台服务器部署？
+
+每台服务器重复部署步骤，注意：
+1. 每台服务器使用不同的监控账号（如果可能）
+2. 适当增加 CHECK_INTERVAL 避免同时访问
+3. 可以设置不同的邮件接收地址
+
+### Q4: 忘记 tmux 会话名怎么办？
+
+```bash
+# 列出所有会话
+tmux ls
+
+# 连接到第一个会话
+tmux attach
+```
+
+### Q5: 邮件发送失败怎么办？
+
+- 确认SMTP授权码正确（不是邮箱密码）
+- 检查服务器能否访问smtp.163.com（端口465）
+- 查看详细错误信息：`tail -f monitor.log`
+
+```bash
+# 测试网络连接
+telnet smtp.163.com 465
+# 或
+nc -zv smtp.163.com 465
+```
+
+### Q6: 权限不足怎么办？
+
+```bash
+# 修改文件所有者
+sudo chown -R username:username ~/grade_monitor
+
+# 修改执行权限
+chmod +x ~/grade_monitor/*.sh
+```
+
+## 💬 温馨提示
+
+1. **成绩更新频率不高**：学校不会每分钟更新成绩，建议CHECK_INTERVAL设为120-300秒
+2. **避免过度监控**：频繁访问可能被学校系统封禁IP
+3. **合理设置间隔**：既能及时发现新成绩，又不会触发限流
+4. **信任自动化**：部署后让程序自己运行，不需要频繁检查
+
+---
+
+# 服务管理
+
+## 🔄 重启服务
+
+### 使用 systemd
+
+```bash
+# 停止服务
+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
+
+```bash
+# 连接到会话
+tmux attach -t grade_monitor
+
+# 停止程序（Ctrl+C）
+
+# 重新运行
+source venv/bin/activate
+python3 monitor.py
+
+# 离开会话（Ctrl+B 然后 D）
+```
+
+### 使用 nohup
+
+```bash
+# 查找进程
+ps aux | grep monitor.py
+
+# 停止进程
+kill <进程ID>
+
+# 重新启动
+cd ~/grade_monitor
+source venv/bin/activate
+nohup python3 monitor.py > output.log 2>&1 &
+```
+
+## 📊 日志查看
+
+### 查看监控日志
+```bash
+# 实时查看
+tail -f ~/grade_monitor/monitor.log
+
+# 查看最后N行
+tail -n 50 ~/grade_monitor/monitor.log
+
+# 搜索关键词
+grep "新增课程\|错误\|warning" ~/grade_monitor/monitor.log
+```
+
+### 查看系统日志（systemd）
+```bash
+# 实时查看
+sudo journalctl -u grade-monitor -f
+
+# 查看最近1小时
+sudo journalctl -u grade-monitor --since "1 hour ago"
+
+# 查看今天的日志
+sudo journalctl -u grade-monitor --since today
+```
+
+## 🔍 状态检查
+
+```bash
+# 检查服务状态（systemd）
+sudo systemctl status grade-monitor
+
+# 检查进程
+ps aux | grep monitor.py
+
+# 检查最后一次检查时间
+ls -lh ~/grade_monitor/monitor.log
+
+# 查看保存的成绩
+cat ~/grade_monitor/.last_grade_content.txt
+```
+
+## 📦 完整更新流程
+
+```bash
+# 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++程序设计
+  - 体育(三) 乒乓球
+  - 概率论与数理统计
+
+### 根本原因
+
+代码逻辑错误：
+
+```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. 导致邮件中显示的课程与实际新增的课程不一致
+
+### 修复方案
+
+1. **修改函数签名**：返回元组 `(是否有变化: bool, 新增课程列表: list)`
+2. **返回新增课程列表**：`return (True, new_courses)`
+3. **更新调用代码**：使用真正的新增课程列表发送邮件
+
+### 修复效果
+
+**修复前：**
+```
+日志：检测到2门新增课程
+邮件：显示3门完全不同的课程 ❌
+```
+
+**修复后：**
+```
+日志：检测到2门新增课程
+邮件：准确显示这2门新增课程 ✅
+```
+
+---
+
+## 📞 获取帮助
+
+如果遇到问题：
+1. 先运行诊断工具：`./diagnose.sh`
+2. 查看本文档的故障排查部分
+3. 查看 `monitor.log` 了解详细错误
+4. 运行 `python3 monitor.py --test --debug` 测试
+5. 检查 `debug_page.html` 了解实际响应
+
+---
+
+## ✅ 部署检查清单
+
+- [ ] 文件已上传到服务器
+- [ ] config.ini配置正确（账号、密码、邮箱）
+- [ ] 运行setup_python.sh安装依赖
+- [ ] 测试模式运行成功
+- [ ] 成绩提取格式正确
+- [ ] 配置后台运行（systemd/tmux）
+- [ ] 服务正常启动
+- [ ] 日志输出正常
+- [ ] 收到测试邮件
+- [ ] 设置文件权限（chmod 600 config.ini）
+
+---
+
+**文档版本：** v2.0  
+**最后更新：** 2026-01-29  
+**维护者：** GitHub Copilot