# QAUP 系统故障排除指南

## 概述

本文档提供了 QAUP 系统常见问题的诊断和解决方案。按照问题类型分类，提供详细的排查步骤和解决方法。

## 快速诊断

### 系统状态检查

```bash
# 快速检查所有服务状态
./deploy.sh status

# 运行完整的系统检查
./docker/monitor.sh status

# 检查系统告警
./docker/alert-manager.sh check
```

### 日志快速查看

```bash
# 查看所有服务的最新日志
./deploy.sh logs all

# 查看错误日志分析
./docker/log-manager.sh analyze
```

## 容器相关问题

### 问题 1: 容器无法启动

**症状**: 容器状态显示 `Exited` 或 `Restarting`

**诊断步骤**:
```bash
# 查看容器状态
docker ps -a

# 查看容器启动日志
docker logs <container_name>

# 检查容器配置
docker inspect <container_name>
```

**常见原因和解决方案**:

1. **端口冲突**
   ```bash
   # 检查端口占用
   netstat -tuln | grep <port>
   
   # 解决方案：修改 .env 文件中的端口配置
   nano .env
   ```

2. **资源不足**
   ```bash
   # 检查系统资源
   free -h
   df -h
   
   # 解决方案：释放资源或增加服务器配置
   ```

3. **配置文件错误**
   ```bash
   # 验证配置文件
   ./docker/config-manager.sh validate
   
   # 重新初始化配置
   ./docker/config-manager.sh init
   ```

### 问题 2: 容器健康检查失败

**症状**: 容器状态显示 `unhealthy`

**诊断步骤**:
```bash
# 查看健康检查日志
docker inspect <container_name> | grep -A 10 "Health"

# 手动执行健康检查命令
docker exec <container_name> <health_check_command>
```

**解决方案**:
```bash
# 重启不健康的容器
docker restart <container_name>

# 如果持续失败，检查应用日志
docker logs <container_name> | tail -100
```

## 数据库相关问题

### 问题 3: 数据库连接失败

**症状**: 应用日志显示数据库连接错误

**诊断步骤**:
```bash
# 检查数据库容器状态
docker ps | grep qaup-postgres

# 测试数据库连接
docker exec qaup-postgres pg_isready -h localhost -p 5432 -U postgres

# 检查数据库日志
docker logs qaup-postgres | tail -50
```

**常见原因和解决方案**:

1. **数据库未完全启动**
   ```bash
   # 等待数据库完全启动
   sleep 30
   
   # 重新测试连接
   docker exec qaup-postgres pg_isready -h localhost -p 5432 -U postgres
   ```

2. **密码错误**
   ```bash
   # 检查环境变量
   grep POSTGRES .env
   
   # 重置数据库密码（需要重新创建容器）
   docker-compose down
   docker volume rm qaup_postgres_data
   docker-compose up -d
   ```

3. **数据库损坏**
   ```bash
   # 检查数据库完整性
   docker exec qaup-postgres psql -U postgres -d qaup -c "SELECT version();"
   
   # 如果损坏，从备份恢复
   docker exec qaup-postgres /restore-db.sh /backup/latest_backup.sql.gz
   ```

### 问题 4: 数据库性能问题

**症状**: 查询响应慢，应用超时

**诊断步骤**:
```bash
# 检查数据库连接数
docker exec qaup-postgres psql -U postgres -d qaup -c "SELECT count(*) FROM pg_stat_activity;"

# 检查慢查询
docker exec qaup-postgres psql -U postgres -d qaup -c "SELECT query, query_start, state FROM pg_stat_activity WHERE state = 'active';"

# 检查数据库锁
docker exec qaup-postgres psql -U postgres -d qaup -c "SELECT * FROM pg_locks WHERE NOT granted;"
```

**解决方案**:
```bash
# 终止长时间运行的查询
docker exec qaup-postgres psql -U postgres -d qaup -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'active' AND query_start < now() - interval '5 minutes';"

# 重启数据库容器
docker restart qaup-postgres

# 优化数据库配置
nano docker/postgres/postgresql.conf
```

## 应用相关问题

### 问题 5: 应用启动失败

**症状**: qaup-app 容器无法启动或立即退出

**诊断步骤**:
```bash
# 查看应用启动日志
docker logs qaup-app

# 检查 JVM 参数
grep JVM_OPTS .env

# 检查应用配置
docker exec qaup-app cat /app/config/application-prod.yml
```

**常见原因和解决方案**:

1. **内存不足**
   ```bash
   # 检查系统内存
   free -h
   
   # 调整 JVM 内存参数
   nano .env
   # 修改 JVM_OPTS，减少 -Xmx 值
   ```

2. **配置文件错误**
   ```bash
   # 验证配置文件语法
   docker run --rm -v $(pwd)/config:/config mikefarah/yq eval /config/application-prod.yml
   
   # 重新生成配置
   ./docker/config-manager.sh generate prod
   ```

3. **依赖服务未就绪**
   ```bash
   # 检查数据库和 Redis 状态
   docker exec qaup-postgres pg_isready
   docker exec qaup-redis redis-cli ping
   
   # 重启应用容器
   docker restart qaup-app
   ```

### 问题 6: 应用内存泄漏

**症状**: 应用内存使用持续增长，最终 OOM

**诊断步骤**:
```bash
# 监控内存使用
docker stats qaup-app

# 检查 JVM 内存使用
docker exec qaup-app jstat -gc 1

# 生成堆转储
docker exec qaup-app jcmd 1 GC.run_finalization
docker exec qaup-app jcmd 1 VM.gc
```

**解决方案**:
```bash
# 调整 JVM 参数
nano .env
# 添加内存分析参数
JVM_OPTS="... -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/app/logs/"

# 重启应用
docker restart qaup-app

# 定期重启应用（临时方案）
echo "0 2 * * * docker restart qaup-app" | crontab -
```

## 网络相关问题

### 问题 7: 前端无法访问

**症状**: 浏览器无法打开前端页面

**诊断步骤**:
```bash
# 检查 Nginx 容器状态
docker ps | grep qaup-nginx

# 测试 Nginx 健康检查
curl -I http://localhost/health

# 检查端口监听
netstat -tuln | grep :80
```

**解决方案**:
```bash
# 重启 Nginx 容器
docker restart qaup-nginx

# 检查 Nginx 配置
docker exec qaup-nginx nginx -t

# 查看 Nginx 错误日志
docker logs qaup-nginx | grep error
```

### 问题 8: API 请求失败

**症状**: 前端可以访问，但 API 请求返回 502/504 错误

**诊断步骤**:
```bash
# 测试后端应用健康检查
curl http://localhost:8080/actuator/health

# 检查 Nginx 到应用的连接
docker exec qaup-nginx nc -z qaup-app 8080

# 查看 Nginx 访问日志
docker logs qaup-nginx | grep "prod-api"
```

**解决方案**:
```bash
# 检查应用容器状态
docker ps | grep qaup-app

# 重启应用容器
docker restart qaup-app

# 检查网络连接
docker network ls
docker network inspect qaup_qaup-network
```

## 性能相关问题

### 问题 9: 系统响应慢

**症状**: 页面加载慢，API 响应时间长

**诊断步骤**:
```bash
# 检查系统资源使用
./docker/monitor.sh resources

# 检查容器资源使用
docker stats

# 测试响应时间
curl -w "@curl-format.txt" -o /dev/null -s http://localhost/health
```

**解决方案**:
```bash
# 优化数据库连接池
nano config/application-prod.yml
# 调整 maxActive, minIdle 等参数

# 增加 JVM 内存
nano .env
# 增加 -Xmx 值

# 启用 Nginx 缓存
nano docker/nginx/default.conf
# 添加缓存配置
```

### 问题 10: 磁盘空间不足

**症状**: 系统告警磁盘使用率过高

**诊断步骤**:
```bash
# 检查磁盘使用
df -h

# 检查日志文件大小
du -sh logs/

# 检查 Docker 空间使用
docker system df
```

**解决方案**:
```bash
# 清理旧日志
./docker/log-manager.sh cleanup 7

# 清理 Docker 资源
docker system prune -f

# 压缩日志文件
./docker/log-manager.sh compress

# 设置日志轮转
./docker/log-manager.sh setup
```

## 数据相关问题

### 问题 11: 数据丢失

**症状**: 数据库中的数据消失或损坏

**诊断步骤**:
```bash
# 检查数据卷
docker volume ls | grep qaup

# 检查数据库表
docker exec qaup-postgres psql -U postgres -d qaup -c "\dt"

# 检查备份文件
ls -la backup/postgres/
```

**解决方案**:
```bash
# 从最近的备份恢复
docker exec qaup-postgres /restore-db.sh /backup/qaup_backup_latest.sql.gz

# 如果没有备份，检查数据卷
docker volume inspect qaup_postgres_data

# 重新初始化数据库（最后手段）
docker-compose down
docker volume rm qaup_postgres_data
docker-compose up -d
```

### 问题 12: 备份失败

**症状**: 数据库备份脚本执行失败

**诊断步骤**:
```bash
# 手动执行备份
docker exec qaup-postgres /backup-db.sh

# 检查备份目录权限
ls -la backup/postgres/

# 检查磁盘空间
df -h backup/
```

**解决方案**:
```bash
# 修复目录权限
sudo chown -R $USER:$USER backup/
chmod 755 backup/postgres/

# 清理旧备份释放空间
find backup/postgres/ -name "*.sql.gz" -mtime +30 -delete

# 重新执行备份
docker exec qaup-postgres /backup-db.sh
```

## 监控和告警问题

### 问题 13: 监控脚本无法运行

**症状**: 监控脚本报错或无输出

**诊断步骤**:
```bash
# 检查脚本权限
ls -la docker/monitor.sh

# 手动运行脚本
bash -x docker/monitor.sh status

# 检查依赖工具
which curl nc
```

**解决方案**:
```bash
# 修复脚本权限
chmod +x docker/monitor.sh

# 安装缺失的工具
sudo apt install curl netcat-openbsd

# 重新运行监控
./docker/monitor.sh status
```

### 问题 14: 告警不工作

**症状**: 系统异常但没有收到告警

**诊断步骤**:
```bash
# 测试告警系统
./docker/alert-manager.sh test

# 检查告警配置
cat docker/healthcheck.yml

# 查看告警日志
tail -f logs/alerts.log
```

**解决方案**:
```bash
# 重新配置告警
nano docker/healthcheck.yml

# 启动持续监控
./docker/alert-manager.sh monitor 60 &

# 检查告警历史
./docker/alert-manager.sh history 50
```

## 紧急恢复程序

### 完全系统故障

如果系统完全无法访问：

```bash
# 1. 停止所有服务
docker-compose down

# 2. 检查系统资源
free -h
df -h

# 3. 清理 Docker 资源
docker system prune -f

# 4. 从备份恢复配置
cp backup/config/config_backup_latest.tar.gz .
tar -xzf config_backup_latest.tar.gz

# 5. 重新启动服务
./deploy.sh start

# 6. 验证服务状态
./deploy.sh status
```

### 数据库完全损坏

```bash
# 1. 停止应用服务
docker stop qaup-app

# 2. 备份当前数据（如果可能）
docker exec qaup-postgres pg_dumpall -U postgres > emergency_backup.sql

# 3. 删除损坏的数据卷
docker-compose down
docker volume rm qaup_postgres_data

# 4. 重新创建数据库
docker-compose up -d qaup-postgres

# 5. 等待数据库启动
sleep 60

# 6. 从备份恢复
docker exec qaup-postgres /restore-db.sh /backup/qaup_backup_latest.sql.gz

# 7. 启动应用服务
docker start qaup-app
```

## 预防措施

### 定期维护

```bash
# 创建维护脚本
cat > maintenance.sh << 'EOF'
#!/bin/bash
# 每日维护脚本

# 检查系统状态
./docker/monitor.sh status

# 检查告警
./docker/alert-manager.sh check

# 备份数据库
docker exec qaup-postgres /backup-db.sh

# 清理旧日志
./docker/log-manager.sh cleanup 30

# 生成监控报告
./docker/monitor.sh report
EOF

chmod +x maintenance.sh

# 设置定时任务
echo "0 2 * * * /path/to/qaup/maintenance.sh" | crontab -
```

### 监控设置

```bash
# 启动持续监控
./docker/alert-manager.sh monitor 300 &

# 设置日志轮转
./docker/log-manager.sh setup

# 配置系统监控
./docker/monitor.sh watch 60 &
```

---

**注意**: 如果问题仍然无法解决，请收集相关日志和系统信息，联系技术支持团队。