tian/QAUP_Management

Fork 0

Tian jianyong 140d3e7e19 增加了Docker部署支持

2025-07-31 13:14:42 +08:00

11 KiB

Raw Permalink Blame History

QAUP 系统故障排除指南

概述

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

快速诊断

系统状态检查

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

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

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

日志快速查看

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

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

容器相关问题

问题 1: 容器无法启动

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

诊断步骤:

# 查看容器状态
docker ps -a

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

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

常见原因和解决方案:

端口冲突

# 检查端口占用
netstat -tuln | grep <port>

# 解决方案：修改 .env 文件中的端口配置
nano .env

资源不足

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

# 解决方案：释放资源或增加服务器配置

配置文件错误

# 验证配置文件
./docker/config-manager.sh validate

# 重新初始化配置
./docker/config-manager.sh init

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

症状: 容器状态显示 unhealthy

诊断步骤:

# 查看健康检查日志
docker inspect <container_name> | grep -A 10 "Health"

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

解决方案:

# 重启不健康的容器
docker restart <container_name>

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

数据库相关问题

问题 3: 数据库连接失败

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

诊断步骤:

# 检查数据库容器状态
docker ps | grep qaup-postgres

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

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

常见原因和解决方案:

数据库未完全启动

# 等待数据库完全启动
sleep 30

# 重新测试连接
docker exec qaup-postgres pg_isready -h localhost -p 5432 -U postgres

密码错误

# 检查环境变量
grep POSTGRES .env

# 重置数据库密码（需要重新创建容器）
docker-compose down
docker volume rm qaup_postgres_data
docker-compose up -d

数据库损坏

# 检查数据库完整性
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: 数据库性能问题

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

诊断步骤:

# 检查数据库连接数
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;"

解决方案:

# 终止长时间运行的查询
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 容器无法启动或立即退出

诊断步骤:

# 查看应用启动日志
docker logs qaup-app

# 检查 JVM 参数
grep JVM_OPTS .env

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

常见原因和解决方案:

内存不足

# 检查系统内存
free -h

# 调整 JVM 内存参数
nano .env
# 修改 JVM_OPTS，减少 -Xmx 值

配置文件错误

# 验证配置文件语法
docker run --rm -v $(pwd)/config:/config mikefarah/yq eval /config/application-prod.yml

# 重新生成配置
./docker/config-manager.sh generate prod

依赖服务未就绪

# 检查数据库和 Redis 状态
docker exec qaup-postgres pg_isready
docker exec qaup-redis redis-cli ping

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

问题 6: 应用内存泄漏

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

诊断步骤:

# 监控内存使用
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

解决方案:

# 调整 JVM 参数
nano .env
# 添加内存分析参数
JVM_OPTS="... -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/app/logs/"

# 重启应用
docker restart qaup-app

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

网络相关问题

问题 7: 前端无法访问

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

诊断步骤:

# 检查 Nginx 容器状态
docker ps | grep qaup-nginx

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

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

解决方案:

# 重启 Nginx 容器
docker restart qaup-nginx

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

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

问题 8: API 请求失败

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

诊断步骤:

# 测试后端应用健康检查
curl http://localhost:8080/actuator/health

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

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

解决方案:

# 检查应用容器状态
docker ps | grep qaup-app

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

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

性能相关问题

问题 9: 系统响应慢

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

诊断步骤:

# 检查系统资源使用
./docker/monitor.sh resources

# 检查容器资源使用
docker stats

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

解决方案:

# 优化数据库连接池
nano config/application-prod.yml
# 调整 maxActive, minIdle 等参数

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

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

问题 10: 磁盘空间不足

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

诊断步骤:

# 检查磁盘使用
df -h

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

# 检查 Docker 空间使用
docker system df

解决方案:

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

# 清理 Docker 资源
docker system prune -f

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

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

数据相关问题

问题 11: 数据丢失

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

诊断步骤:

# 检查数据卷
docker volume ls | grep qaup

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

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

解决方案:

# 从最近的备份恢复
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: 备份失败

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

诊断步骤:

# 手动执行备份
docker exec qaup-postgres /backup-db.sh

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

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

解决方案:

# 修复目录权限
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: 监控脚本无法运行

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

诊断步骤:

# 检查脚本权限
ls -la docker/monitor.sh

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

# 检查依赖工具
which curl nc

解决方案:

# 修复脚本权限
chmod +x docker/monitor.sh

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

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

问题 14: 告警不工作

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

诊断步骤:

# 测试告警系统
./docker/alert-manager.sh test

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

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

解决方案:

# 重新配置告警
nano docker/healthcheck.yml

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

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

紧急恢复程序

完全系统故障

如果系统完全无法访问：

# 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

数据库完全损坏

# 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

预防措施

定期维护

# 创建维护脚本
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 -

监控设置

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

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

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

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

11 KiB Raw Permalink Blame History Unescape Escape

QAUP 系统故障排除指南

概述

快速诊断

系统状态检查

日志快速查看

容器相关问题

问题 1: 容器无法启动

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

数据库相关问题

问题 3: 数据库连接失败

问题 4: 数据库性能问题

应用相关问题

问题 5: 应用启动失败

问题 6: 应用内存泄漏

网络相关问题

问题 7: 前端无法访问

问题 8: API 请求失败

性能相关问题

问题 9: 系统响应慢

问题 10: 磁盘空间不足

数据相关问题

问题 11: 数据丢失

问题 12: 备份失败

监控和告警问题

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

问题 14: 告警不工作

紧急恢复程序

完全系统故障

数据库完全损坏

预防措施

定期维护

监控设置

11 KiB

Raw Permalink Blame History