feat(P2): 实现质量保障类5项功能(无障碍/视觉回归/通知渠道/漏洞扫描/灾备)

## 新增功能 ### 1. 屏幕阅读器兼容性增强（a11y） - 无障碍工具库：src/shared/lib/a11y.ts - aria-live Hook：src/shared/hooks/use-aria-live.ts - a11y 组件：skip-link/visually-hidden/focus-trap/aria-status - 增强 UI：table.tsx 系统性 ARIA role，dialog.tsx aria-modal - 审计文档：docs/accessibility/a11y-audit.md（WCAG 2.1 AA 清单） ### 2. 视觉回归测试 - 测试套件：tests/visual/（homepage + 3 个 dashboard） - 3 视口（desktop/tablet/mobile）× 2 主题（light/dark） - 动态元素遮罩，避免误报 - playwright.config.ts 新增 visual-chromium 项目 - 文档：docs/testing/visual-regression.md ### 3. 短信/微信推送渠道集成 - 新模块：src/modules/notifications/ - 4 个渠道：SMS（阿里云/腾讯云）、WeChat（公众号）、Email（SMTP）、In-App - 分发器按用户偏好并行多渠道发送 - 外部 SDK 动态 import，Mock 模式开发可用 - 文档：docs/notifications/channels.md ### 4. 漏洞扫描 CI 集成 - CI security-scan job：npm audit + Snyk + Trivy FS + OWASP ZAP - 独立工作流 security.yml：每周一深度扫描 + 容器镜像扫描 - 配置：suppressions.json + .trivyignore - 本地脚本：security-scan.sh/ps1 - 文档：docs/security/scanning.md（SLA 分级） ### 5. 灾备方案 - 脚本：backup-verify/backup-offsite-sync/dr-drill/failover/health-check - CI 增强：备份后校验+异地同步，每周灾备演练 - 独立工作流 dr-drill.yml：每周一凌晨 4 点自动演练 - 文档：docs/dr/dr-plan.md（RTO 4h/RPO 24h）+ dr-runbook.md（6 故障场景） ## 验证 - npx tsc --noEmit：0 错误 - npm run lint：0 错误 0 警告
2026-06-17 20:18:29 +08:00
parent b86255f0ea
commit 6585e10c6f
53 changed files with 7491 additions and 37 deletions
--- a/docs/dr/dr-runbook.md
+++ b/docs/dr/dr-runbook.md
@@ -0,0 +1,699 @@
+# 灾备操作手册 (DR Runbook)
+
+> **文档版本**: 1.0
+> **最后更新**: 2026-06-17
+> **适用场景**: 生产环境故障处理
+
+---
+
+## 概述
+
+本手册提供常见故障场景的诊断和处理步骤。每个场景包含:症状、诊断、处理步骤、验证方法。
+
+**紧急联系**: 参见 `docs/dr/dr-plan.md` 第 6 节联系人列表
+
+---
+
+## 场景 1: 数据库故障
+
+### 1.1 数据库不可达
+
+#### 症状
+- 应用报错: `ECONNREFUSED` 或 `Connection refused`
+- 健康检查 `database` 状态为 `fail`
+- 用户无法登录、查询数据
+
+#### 诊断
+```bash
+# 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: 数据库服务停止**
+```bash
+# 重启数据库服务
+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: 数据库无法启动**
+```bash
+# 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: 数据库损坏,需要从备份恢复**
+```bash
+# 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: 主库故障,需要切换到备库**
+```bash
+# 1. 执行故障切换(手动模式)
+./scripts/failover.sh
+
+# 2. 或半自动模式
+./scripts/failover.sh --auto
+
+# 3. 验证切换结果
+./scripts/health-check.sh
+```
+
+#### 验证
+```bash
+# 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/内存使用率高
+
+#### 诊断
+```bash
+# 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
+```
+
+#### 处理步骤
+```bash
+# 1. 终止长时间运行的查询
+mysql -e "KILL <process_id>;"
+
+# 2. 优化表
+mysql -e "OPTIMIZE TABLE <table_name>;"
+
+# 3. 重启数据库(如果必要)
+sudo systemctl restart mysql
+```
+
+#### 验证
+```bash
+# 监控性能指标
+mysql -e "SHOW STATUS LIKE 'Threads%';"
+mysql -e "SHOW STATUS LIKE 'Slow_queries';"
+```
+
+---
+
+## 场景 2: 应用故障
+
+### 2.1 应用不可达
+
+#### 症状
+- HTTP 502/503 错误
+- 页面无法访问
+- 健康检查 `app` 状态为 `fail`
+
+#### 诊断
+```bash
+# 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: 容器停止**
+```bash
+# 启动容器
+docker start nextjs-app
+
+# 等待启动
+sleep 10
+curl -f http://localhost:8015
+```
+
+**情况 B: 容器崩溃,需要重启**
+```bash
+# 重启容器
+docker restart nextjs-app
+
+# 如果重启失败,重新部署
+docker stop nextjs-app || true
+docker rm nextjs-app || true
+# 重新运行部署流程(参见 CI/CD)
+```
+
+**情况 C: 应用配置错误**
+```bash
+# 1. 检查环境变量
+docker exec nextjs-app env | grep DATABASE_URL
+
+# 2. 检查 .env.local
+cat .env.local
+
+# 3. 修正配置后重启
+docker restart nextjs-app
+```
+
+#### 验证
+```bash
+# 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`
+
+#### 诊断
+```bash
+# 1. 查看容器状态
+docker inspect nextjs-app | grep -A 5 "State"
+
+# 2. 查看内存使用
+docker stats nextjs-app
+
+# 3. 查看系统日志
+dmesg | grep -i "oom"
+```
+
+#### 处理步骤
+```bash
+# 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 ...
+```
+
+#### 验证
+```bash
+# 监控内存使用
+docker stats nextjs-app
+
+# 确认应用正常
+curl -f http://localhost:8015
+```
+
+---
+
+## 场景 3: 备份失败
+
+### 3.1 定时备份未执行
+
+#### 症状
+- 健康检查 `backup` 状态为 `fail`(备份超过 24 小时)
+- `./backups/` 目录无新文件
+- CI 中 `scheduled-backup` job 失败
+
+#### 诊断
+```bash
+# 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: 磁盘空间不足**
+```bash
+# 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: 数据库连接问题**
+```bash
+# 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 权限问题**
+```bash
+# 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
+```
+
+#### 验证
+```bash
+# 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 文件内容异常
+
+#### 诊断
+```bash
+# 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
+```
+
+#### 处理步骤
+```bash
+# 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;"
+```
+
+#### 验证
+```bash
+# 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" 步骤失败
+- 异地存储缺少最新备份
+
+#### 诊断
+```bash
+# 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: 凭证错误**
+```bash
+# 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: 网络问题**
+```bash
+# 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: 工具未安装**
+```bash
+# 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
+```
+
+#### 验证
+```bash
+# 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 目录不可写
+
+#### 诊断
+```bash
+# 1. 检查 NFS 挂载
+mount | grep nfs
+
+# 2. 检查目录权限
+ls -la $BACKUP_OFFSITE_REMOTE
+
+# 3. 测试写入
+touch $BACKUP_OFFSITE_REMOTE/test && rm $BACKUP_OFFSITE_REMOTE/test
+```
+
+#### 处理步骤
+```bash
+# 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(恢复)失败
+- 测试数据库创建成功但恢复失败
+
+#### 诊断
+```bash
+# 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
+```
+
+#### 处理步骤
+```bash
+# 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` 数据库残留
+- 磁盘空间异常增长
+
+#### 诊断
+```bash
+# 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;"
+```
+
+#### 处理步骤
+```bash
+# 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`
+- 应用或数据库写入失败
+- 系统响应缓慢
+
+#### 诊断
+```bash
+# 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 {} \;
+```
+
+#### 处理步骤
+```bash
+# 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
+```
+
+#### 验证
+```bash
+# 1. 检查磁盘空间
+df -h
+
+# 2. 运行健康检查
+./scripts/health-check.sh
+```
+
+---
+
+## 附录: 快速参考命令
+
+### 备份相关
+```bash
+# 执行备份
+npm run backup
+
+# 校验备份
+npm run dr:backup-verify
+
+# 异地同步
+npm run dr:offsite-sync
+
+# 灾备演练
+npm run dr:drill
+
+# 健康检查
+npm run dr:health-check
+```
+
+### 恢复相关
+```bash
+# 从备份恢复
+./scripts/restore-db.sh backups/db_backup_YYYYMMDD_HHMMSS.sql.gz
+
+# 故障切换
+./scripts/failover.sh --auto
+```
+
+### 诊断相关
+```bash
+# 完整健康检查
+./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 | 初始版本 | - |