# 数据备份与恢复

> **中学成绩档案系统** · 备份目录默认 `/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`）

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

---

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

```bash
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. 执行：

```bash
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 或首页卡片 **修改** 中维护；首页卡片支持 **删除**。