secondary-school-grade-archive/docs/BACKUP.md

数据备份与恢复

中学成绩档案系统 · 备份目录默认 /root/grade-archive-backups

---

1. 备份内容

每次备份生成一个压缩包 grade-archive_YYYYMMDD_HHMMSS.tar.gz，包含：

文件/目录	说明
database.sql	PostgreSQL 全库导出（含 --clean，可覆盖恢复）
uploads/	错题图片、学生头像等上传文件
manifest.json	备份元信息（时间、库名）

---

2. 自动备份

• 目录：/root/grade-archive-backups（可通过 .env 中 BACKUP_DIR 修改）
• 频率：应用启动后每 24 小时自动备份一次（AUTO_BACKUP_INTERVAL_HOURS=24）
• 保留：默认保留最近 30 天（BACKUP_RETENTION_DAYS=30）
• 系统 cron（可选，安装脚本会写入）：每天凌晨 3:00 执行 deploy/backup.sh

环境变量（.env）

BACKUP_DIR=/root/grade-archive-backups
BACKUP_RETENTION_DAYS=30
AUTO_BACKUP_INTERVAL_HOURS=24

---

3. 手动备份（服务器命令行）

sudo BACKUP_DIR=/root/grade-archive-backups \
  bash /opt/secondary-school-grade-archive/deploy/backup.sh

备份文件位于 /root/grade-archive-backups/。

---

4. 系统设置中下载备份

1. 使用超级管理员登录
2. 进入 系统设置 → 数据备份
3. 点击 立即备份 或等待自动备份
4. 在列表中点击 下载 保存 .tar.gz 到本地

---

5. 更换服务器 — 数据恢复

方式 A：Web 界面（推荐）

1. 在新服务器完成 deploy/install.sh 并 git pull 到最新版本
2. 超级管理员登录 → 系统设置 → 数据备份
3. 在「数据恢复」区域上传旧服务器下载的 grade-archive_*.tar.gz
4. 恢复成功后建议执行：sudo systemctl restart grade-archive

方式 B：命令行

1. 将备份包复制到新服务器，例如 /root/grade-archive_20260628_030000.tar.gz
2. 执行：

sudo bash /opt/secondary-school-grade-archive/deploy/restore.sh \
  /root/grade-archive_20260628_030000.tar.gz

3. 按提示确认后，脚本会恢复数据库与 uploads/，并尝试重启服务

---

6. 迁移检查清单

• 旧服务器下载最新备份包
• 新服务器安装系统（install.sh）并配置 Ollama / OCR 地址
• 上传备份并恢复
• 验证学生资料、成绩、错题图片、头像是否正常
• 确认 .env 中 OLLAMA_BASE_URL、OCR_SERVICE_URL 符合新环境

---

7. 注意事项

• 恢复会覆盖当前数据库与 uploads 目录，操作前请先备份当前数据
• 备份与恢复需要服务器已安装 pg_dump / psql（安装脚本已包含 PostgreSQL）
• 备份目录在 /root 下，仅 root 可读写；应用以 systemd 运行时需确保 BACKUP_DIR 对运行用户可写，或保持默认由 root cron / 管理员 API 触发
• 学生头像、学校、年级等资料保存在数据库 students 表中，随数据库一并备份

---

8. 学生资料字段说明

字段	说明
姓名	必填
学校	可选，显示在卡片与详情
学段	初中 / 高中
年级	初一～初三 或 高一～高三（带明确标识）
班级	如 3 或 3班
头像	保存在 uploads/{用户ID}/avatars/{学生ID}.jpg

在学生详情页 设置 Tab 或首页卡片 修改 中维护；首页卡片支持 删除。