NextEdu/docs/dr/dr-runbook.md

灾备操作手册 (DR Runbook)

文档版本: 1.0 最后更新: 2026-06-17 适用场景: 生产环境故障处理

---

概述

本手册提供常见故障场景的诊断和处理步骤。每个场景包含:症状、诊断、处理步骤、验证方法。

紧急联系: 参见 docs/dr/dr-plan.md 第 6 节联系人列表

---

场景 1: 数据库故障

1.1 数据库不可达

症状

• 应用报错: ECONNREFUSED 或 Connection refused
• 健康检查 database 状态为 fail
• 用户无法登录、查询数据

诊断

# 1. 检查数据库连接
mysql -h <DB_HOST> -P <DB_PORT> -u <DB_USER> -p -e "SELECT 1;"

# 2. 检查数据库进程
systemctl status mysql
# 或 Docker 环境
docker ps | grep mysql

# 3. 检查端口
telnet <DB_HOST> <DB_PORT>
# 或
nc -zv <DB_HOST> <DB_PORT>

# 4. 查看数据库日志
tail -100 /var/log/mysql/error.log
# 或 Docker
docker logs <mysql_container> --tail 100

处理步骤

情况 A: 数据库服务停止

# 重启数据库服务
sudo systemctl restart mysql
# 或 Docker
docker restart <mysql_container>

# 等待启动完成
sleep 10
mysql -h <DB_HOST> -P <DB_PORT> -u <DB_USER> -p -e "SELECT 1;"

情况 B: 数据库无法启动

# 1. 检查磁盘空间
df -h

# 2. 检查配置文件
mysql --verbose --help | head -20

# 3. 如果磁盘满,清理空间
sudo find /var/log -type f -name "*.log" -mtime +7 -delete

# 4. 如果配置错误,恢复备份配置
sudo cp /etc/mysql/my.cnf.bak /etc/mysql/my.cnf
sudo systemctl restart mysql

情况 C: 数据库损坏,需要从备份恢复

# 1. 获取最新备份
LATEST_BACKUP=$(ls -t backups/db_backup_*.sql.gz | head -1)
echo "Using backup: $LATEST_BACKUP"

# 2. 校验备份
./scripts/backup-verify.sh "$LATEST_BACKUP"

# 3. 恢复数据库
./scripts/restore-db.sh "$LATEST_BACKUP"

# 4. 重启应用
docker restart nextjs-app

情况 D: 主库故障,需要切换到备库

# 1. 执行故障切换(手动模式)
./scripts/failover.sh

# 2. 或半自动模式
./scripts/failover.sh --auto

# 3. 验证切换结果
./scripts/health-check.sh

验证

# 1. 运行健康检查
./scripts/health-check.sh

# 2. 验证应用功能
curl -f http://localhost:8015

# 3. 验证数据库查询
mysql -h <DB_HOST> -P <DB_PORT> -u <DB_USER> -p -e "SELECT COUNT(*) FROM users;"

# 4. 运行灾备演练验证数据完整性
./scripts/dr-drill.sh

---

1.2 数据库性能问题

症状

• 应用响应缓慢
• 查询超时
• CPU/内存使用率高

诊断

# 1. 查看当前连接
mysql -e "SHOW PROCESSLIST;"

# 2. 查看慢查询
mysql -e "SHOW VARIABLES LIKE 'slow_query%';"
tail -100 /var/log/mysql/slow.log

# 3. 查看系统资源
top
iostat -x 1

处理步骤

# 1. 终止长时间运行的查询
mysql -e "KILL <process_id>;"

# 2. 优化表
mysql -e "OPTIMIZE TABLE <table_name>;"

# 3. 重启数据库(如果必要)
sudo systemctl restart mysql

验证

# 监控性能指标
mysql -e "SHOW STATUS LIKE 'Threads%';"
mysql -e "SHOW STATUS LIKE 'Slow_queries';"

---

场景 2: 应用故障

2.1 应用不可达

症状

• HTTP 502/503 错误
• 页面无法访问
• 健康检查 app 状态为 fail

诊断

# 1. 检查应用容器
docker ps | grep nextjs-app

# 2. 查看应用日志
docker logs nextjs-app --tail 100

# 3. 检查端口
netstat -tlnp | grep 8015

# 4. 检查健康端点
curl -v http://localhost:8015

处理步骤

情况 A: 容器停止

# 启动容器
docker start nextjs-app

# 等待启动
sleep 10
curl -f http://localhost:8015

情况 B: 容器崩溃,需要重启

# 重启容器
docker restart nextjs-app

# 如果重启失败,重新部署
docker stop nextjs-app || true
docker rm nextjs-app || true
# 重新运行部署流程(参见 CI/CD)

情况 C: 应用配置错误

# 1. 检查环境变量
docker exec nextjs-app env | grep DATABASE_URL

# 2. 检查 .env.local
cat .env.local

# 3. 修正配置后重启
docker restart nextjs-app

验证

# 1. 健康检查
./scripts/health-check.sh

# 2. 功能测试
curl -f http://localhost:8015
curl -f http://localhost:8015/api/auth/providers

# 3. 查看日志确认无错误
docker logs nextjs-app --tail 20

---

2.2 应用 OOM(内存不足)

症状

• 容器被 OOM Killer 终止
• 日志中出现 JavaScript heap out of memory

诊断

# 1. 查看容器状态
docker inspect nextjs-app | grep -A 5 "State"

# 2. 查看内存使用
docker stats nextjs-app

# 3. 查看系统日志
dmesg | grep -i "oom"

处理步骤

# 1. 增加 Node.js 内存限制
docker stop nextjs-app
docker rm nextjs-app
docker run -d \
  --init \
  -p 8015:3000 \
  --restart unless-stopped \
  --name nextjs-app \
  --network 1panel-network \
  -e NODE_OPTIONS="--max-old-space-size=2048" \
  -e NODE_ENV=production \
  -e DATABASE_URL=$DATABASE_URL \
  -e NEXTAUTH_SECRET=$NEXTAUTH_SECRET \
  -e NEXTAUTH_URL=$NEXTAUTH_URL \
  nextjs-app

# 2. 或增加容器内存限制
docker run -d --memory=2g ...

验证

# 监控内存使用
docker stats nextjs-app

# 确认应用正常
curl -f http://localhost:8015

---

场景 3: 备份失败

3.1 定时备份未执行

症状

• 健康检查 backup 状态为 fail(备份超过 24 小时)
• ./backups/ 目录无新文件
• CI 中 scheduled-backup job 失败

诊断

# 1. 检查最新备份
ls -lt backups/db_backup_*.sql.gz | head -5

# 2. 检查 CI 运行记录
# 访问 Gitea Actions 页面查看 scheduled-backup job

# 3. 手动运行备份测试
./scripts/backup-db.sh

# 4. 检查磁盘空间
df -h

处理步骤

情况 A: 磁盘空间不足

# 1. 清理旧备份
find backups/ -name "db_backup_*.sql.gz" -mtime +30 -delete

# 2. 清理其他临时文件
find /tmp -type f -mtime +7 -delete

# 3. 重新运行备份
./scripts/backup-db.sh

情况 B: 数据库连接问题

# 1. 验证数据库连接
mysql -h <DB_HOST> -P <DB_PORT> -u <DB_USER> -p -e "SELECT 1;"

# 2. 检查 DATABASE_URL 环境变量
echo $DATABASE_URL

# 3. 修正配置后重新备份
export DATABASE_URL="mysql://correct_url"
./scripts/backup-db.sh

情况 C: mysqldump 权限问题

# 1. 检查用户权限
mysql -u <DB_USER> -p -e "SHOW GRANTS;"

# 2. 授予必要权限
mysql -u root -p -e "GRANT SELECT, LOCK TABLES, SHOW VIEW, EVENT, TRIGGER ON *.* TO '<DB_USER>'@'%';"
FLUSH PRIVILEGES;

# 3. 重新备份
./scripts/backup-db.sh

验证

# 1. 确认新备份存在
ls -lt backups/db_backup_*.sql.gz | head -1

# 2. 校验备份完整性
./scripts/backup-verify.sh

# 3. 运行健康检查
./scripts/health-check.sh

---

3.2 备份文件损坏

症状

• backup-verify.sh 校验失败
• gzip 解压失败
• SQL 文件内容异常

诊断

# 1. 运行校验脚本
./scripts/backup-verify.sh backups/db_backup_YYYYMMDD_HHMMSS.sql.gz

# 2. 手动检查 gzip
gunzip -t backups/db_backup_YYYYMMDD_HHMMSS.sql.gz

# 3. 检查文件大小
ls -lh backups/db_backup_*.sql.gz

处理步骤

# 1. 删除损坏的备份
rm backups/db_backup_YYYYMMDD_HHMMSS.sql.gz

# 2. 重新执行备份
./scripts/backup-db.sh

# 3. 校验新备份
./scripts/backup-verify.sh

# 4. 如果新备份也损坏,检查数据库完整性
mysql -e "CHECK TABLE users; CHECK TABLE schools;"

验证

# 1. 校验新备份
./scripts/backup-verify.sh

# 2. 运行灾备演练
./scripts/dr-drill.sh

---

场景 4: 异地同步失败

4.1 S3/OSS 同步失败

症状

• backup-offsite-sync.sh 失败
• CI 中 "Sync backup to offsite storage" 步骤失败
• 异地存储缺少最新备份

诊断

# 1. 检查后端配置
echo $BACKUP_OFFSITE_BACKEND
echo $BACKUP_OFFSITE_REMOTE
echo $BACKUP_OFFSITE_BUCKET

# 2. 检查凭证
echo $BACKUP_OFFSITE_ACCESS_KEY
echo $BACKUP_OFFSITE_SECRET_KEY

# 3. 测试连接
aws s3 ls s3://$BACKUP_OFFSITE_BUCKET/  # S3
# 或
ossutil ls oss://$BACKUP_OFFSITE_BUCKET/  # OSS

# 4. 手动运行同步
./scripts/backup-offsite-sync.sh

处理步骤

情况 A: 凭证错误

# 1. 更新凭证
export BACKUP_OFFSITE_ACCESS_KEY="new_access_key"
export BACKUP_OFFSITE_SECRET_KEY="new_secret_key"

# 2. 更新 Gitea Secrets
# 访问仓库 Settings > Secrets 更新对应 secret

# 3. 重新同步
./scripts/backup-offsite-sync.sh

情况 B: 网络问题

# 1. 测试网络连通性
ping s3.amazonaws.com  # S3
ping oss-cn-beijing.aliyuncs.com  # OSS

# 2. 检查代理设置
echo $http_proxy
echo $https_proxy

# 3. 配置代理后重试
export http_proxy=http://proxy:port
export https_proxy=http://proxy:port
./scripts/backup-offsite-sync.sh

情况 C: 工具未安装

# 1. 安装 aws-cli
pip install awscli
# 或
apt-get install -y awscli

# 2. 安装 rclone
curl https://rclone.org/install.sh | sudo bash

# 3. 重新同步
./scripts/backup-offsite-sync.sh

验证

# 1. 列出远程文件
aws s3 ls s3://$BACKUP_OFFSITE_BUCKET/backups/
# 或
rclone lsf $BACKUP_OFFSITE_REMOTE

# 2. 对比本地和远程文件数量
LOCAL_COUNT=$(ls backups/db_backup_*.sql.gz | wc -l)
REMOTE_COUNT=$(aws s3 ls s3://$BACKUP_OFFSITE_BUCKET/backups/ | grep -c "db_backup")
echo "Local: $LOCAL_COUNT, Remote: $REMOTE_COUNT"

---

4.2 NFS 同步失败

症状

• backup-offsite-sync.sh NFS 后端失败
• NFS 目录不可写

诊断

# 1. 检查 NFS 挂载
mount | grep nfs

# 2. 检查目录权限
ls -la $BACKUP_OFFSITE_REMOTE

# 3. 测试写入
touch $BACKUP_OFFSITE_REMOTE/test && rm $BACKUP_OFFSITE_REMOTE/test

处理步骤

# 1. 重新挂载 NFS
sudo umount /mnt/nfs
sudo mount -t nfs <nfs_server>:/path /mnt/nfs

# 2. 检查权限
sudo chown -R $USER:$USER /mnt/nfs/backups

# 3. 重新同步
./scripts/backup-offsite-sync.sh

---

场景 5: 灾备演练失败

5.1 演练恢复失败

症状

• dr-drill.sh 步骤 3(恢复)失败
• 测试数据库创建成功但恢复失败

诊断

# 1. 查看演练报告
cat docs/dr/reports/dr_drill_*.md

# 2. 手动测试恢复
mysql -h <DB_HOST> -u <DB_USER> -p -e "CREATE DATABASE test_manual;"
gunzip -c backups/db_backup_*.sql.gz | mysql -h <DB_HOST> -u <DB_USER> -p test_manual

# 3. 检查备份文件
./scripts/backup-verify.sh

处理步骤

# 1. 清理失败的测试数据库
mysql -h <DB_HOST> -u <DB_USER> -p -e "DROP DATABASE IF EXISTS next_edu_dr_drill;"

# 2. 校验备份
./scripts/backup-verify.sh

# 3. 如果备份损坏,重新备份
./scripts/backup-db.sh

# 4. 重新运行演练
./scripts/dr-drill.sh

---

5.2 演练后测试数据库未清理

症状

• next_edu_dr_drill 数据库残留
• 磁盘空间异常增长

诊断

# 1. 检查测试数据库
mysql -e "SHOW DATABASES LIKE 'next_edu_dr_drill';"

# 2. 检查数据库大小
mysql -e "SELECT table_schema, SUM(data_length + index_length) / 1024 / 1024 AS size_mb FROM information_schema.tables WHERE table_schema = 'next_edu_dr_drill' GROUP BY table_schema;"

处理步骤

# 1. 手动删除测试数据库
mysql -h <DB_HOST> -u <DB_USER> -p -e "DROP DATABASE IF EXISTS next_edu_dr_drill;"

# 2. 验证已删除
mysql -e "SHOW DATABASES LIKE 'next_edu_dr_drill';"

---

场景 6: 磁盘空间不足

症状

• 健康检查 disk 状态为 fail
• 应用或数据库写入失败
• 系统响应缓慢

诊断

# 1. 检查磁盘使用
df -h

# 2. 查找大文件
du -sh /* 2>/dev/null | sort -rh | head -10
du -sh /var/* 2>/dev/null | sort -rh | head -10

# 3. 查找大日志文件
find /var/log -type f -size +100M -exec ls -lh {} \;

处理步骤

# 1. 清理旧备份
find backups/ -name "db_backup_*.sql.gz" -mtime +30 -delete

# 2. 清理日志
sudo find /var/log -type f -name "*.log" -mtime +7 -delete
sudo journalctl --vacuum-time=7d

# 3. 清理 Docker 资源
docker system prune -a --volumes
# 注意: 这会删除未使用的镜像和卷,谨慎使用

# 4. 清理 npm 缓存
npm cache clean --force

# 5. 清理临时文件
find /tmp -type f -mtime +7 -delete

验证

# 1. 检查磁盘空间
df -h

# 2. 运行健康检查
./scripts/health-check.sh

---

附录: 快速参考命令

备份相关

# 执行备份
npm run backup

# 校验备份
npm run dr:backup-verify

# 异地同步
npm run dr:offsite-sync

# 灾备演练
npm run dr:drill

# 健康检查
npm run dr:health-check

恢复相关

# 从备份恢复
./scripts/restore-db.sh backups/db_backup_YYYYMMDD_HHMMSS.sql.gz

# 故障切换
./scripts/failover.sh --auto

诊断相关

# 完整健康检查
./scripts/health-check.sh

# 检查数据库
mysql -h <DB_HOST> -P <DB_PORT> -u <DB_USER> -p -e "SHOW PROCESSLIST;"

# 检查应用日志
docker logs nextjs-app --tail 100

# 检查磁盘空间
df -h

---

变更记录

日期	版本	变更内容	变更人
2026-06-17	1.0	初始版本	-