user-system/docs/runbooks/07-incident-response.md

事件响应 Runbook

触发条件

• 服务无响应
• 服务报错
• 性能严重下降
• 依赖服务故障
• 硬件/基础设施故障

事件分级

级别	说明	响应时间	示例
SEV1	服务完全不可用	立即	服务崩溃、数据库损坏
SEV2	部分功能不可用	30分钟内	登录失败、API 超时
SEV3	性能下降	2小时内	响应变慢、偶发错误
SEV4	轻微问题	24小时内	日志错误、非关键功能异常

SEV1 响应（服务完全不可用）

1. 确认事件

# 检查服务状态
docker compose ps

# 检查容器日志
docker compose logs --tail=100

# 检查系统资源
docker stats --no-stream

2. 收集信息

# 保存当前日志
docker compose logs > incident_logs_$(date +%Y%m%d_%H%M%S).txt

# 检查磁盘空间
df -h

# 检查内存
free -h

# 检查进程
ps aux | grep docker

3. 尝试重启

# 优雅重启
docker compose restart

# 等待 30 秒后检查
sleep 30
docker compose ps
curl http://localhost:8080/api/v1/health

4. 如果重启失败

# 查看详细错误
docker compose up

# 检查端口占用
lsof -i :8080

# 检查配置文件
cat ./configs/config.yaml

5. 数据库问题

# 检查数据库文件
ls -la ./data/

# 验证 SQLite 完整性
sqlite3 ./data/user_management.db "PRAGMA integrity_check;"

# 如果损坏，从备份恢复
./scripts/backup/backup.sh --restore

SEV2 响应（部分功能不可用）

1. 确认问题范围

# 测试健康端点
curl http://localhost:8080/api/v1/health

# 测试登录
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test"}'

# 查看错误日志
docker compose logs | grep -E "error|ERROR|fail|FAIL" | tail -50

2. 检查依赖

# 检查数据库连接
docker compose logs | grep -i "database"

# 检查外部服务（如邮件、短信）
docker compose logs | grep -i "external\|oauth\|sms\|email"

3. 针对性修复

# 如果是数据库连接问题
docker compose restart

# 如果是配置问题，更新配置后重启
vi ./configs/config.yaml
docker compose restart

# 如果是资源问题，清理资源
docker system prune -a
docker compose restart

SEV3 响应（性能下降）

1. 诊断

# 查看实时资源使用
docker stats

# 检查慢请求
grep -E "[0-9]+ms" ./logs/app.log | awk '{if($NF ~ /[0-9]+ms/ && $NF+0 > 1000) print}' | head -20

# 检查数据库查询
sqlite3 ./data/user_management.db "SELECT COUNT(*) FROM users;"

# 查看当前连接数
lsof ./data/user_management.db | wc -l

2. 常见解决方案

# 重启服务清理缓存
docker compose restart

# 如果是数据库锁等待，等待或重启
docker compose restart

# 检查是否有慢查询
# 参考 04-log-analysis.md 的查询分析

3. 监控恢复

# 持续监控
watch -n 5 'curl -s http://localhost:8080/api/v1/health'

# 检查响应时间
time curl -s http://localhost:8080/api/v1/health

SEV4 响应（轻微问题）

1. 记录问题

# 创建问题记录
cat > issue_$(date +%Y%m%d).md << EOF
# 问题记录

日期：[填写]
问题描述：[详细描述]
影响：[影响范围]
日志：[相关日志片段]
EOF

2. 安排修复

# 在下一个维护窗口修复
# 或安排开发团队跟进

回滚步骤

如果当前修复导致新问题：

# 停止服务
docker compose stop

# 恢复到上一个稳定版本
git checkout <previous-version>
docker compose up -d

# 或从备份恢复数据
./scripts/backup/backup.sh --restore

事件恢复清单

• 服务恢复正常
• 健康检查通过
• 主要功能验证正常
• 性能指标正常
• 无新增错误
• 通知相关人员恢复完成

联系人

• 运维负责人：[填写]
• 开发团队：[填写]
• 基础设施团队：[填写]
• 项目经理：[填写]

事后处理

1. 事件记录

创建详细的事件报告，包括：

• 事件时间线
• 根本原因
• 影响评估
• 修复步骤
• 经验教训

2. 预防措施

根据事件分析：

• 增强监控告警
• 优化自动化恢复流程
• 更新 Runbook
• 加强容量规划

3. 复盘会议

• 讨论事件过程
• 识别改进点
• 分配行动项
• 更新应急流程