6.7 KiB
6.7 KiB
🔍 故障排除指南
常见问题
1. 数据库连接失败
问题：failed to connect to database
解决方案：
# 检查数据库配置
cat config.yaml | grep -A 10 database
# 测试数据库连接
psql -h localhost -U postgres -d tyapi_dev
# 检查环境变量
env | grep DB_
2. Redis 连接失败
问题：failed to connect to redis
解决方案：
# 检查Redis状态
redis-cli ping
# 检查配置
cat config.yaml | grep -A 5 redis
# 重启Redis
docker restart tyapi-redis
3. JWT 令牌验证失败
问题：invalid token
解决方案：
# 检查JWT密钥配置
echo $JWT_SECRET
# 验证令牌格式
echo "your-token" | cut -d. -f2 | base64 -d
4. 内存使用过高
问题：应用内存占用持续增长
解决方案：
# 启用pprof分析
go tool pprof http://localhost:8080/debug/pprof/heap
# 检查Goroutine泄露
go tool pprof http://localhost:8080/debug/pprof/goroutine
# 优化数据库连接池
# 在config.yaml中调整max_open_conns和max_idle_conns
5. 端口冲突
问题：bind: address already in use
解决方案：
# 查找占用端口的进程
netstat -tlnp | grep :8080
lsof -i :8080
# 终止占用端口的进程
kill -9 <PID>
# 修改配置使用其他端口
6. 权限问题
问题：permission denied
解决方案：
# 检查文件权限
ls -la config.yaml
ls -la logs/
# 修复权限
chmod 644 config.yaml
chmod 755 logs/
chown -R $(whoami) logs/
日志分析
1. 应用日志
# 查看应用日志
tail -f logs/app.log
# 过滤错误日志
grep "ERROR" logs/app.log
# 分析请求延迟
grep "request_duration" logs/app.log | awk '{print $NF}' | sort -n
2. 数据库日志
# PostgreSQL日志
docker logs tyapi-postgres 2>&1 | grep ERROR
# 慢查询分析
grep "duration:" logs/postgresql.log | awk '$3 > 1000'
3. 性能监控
# 查看系统指标
curl http://localhost:8080/metrics
# Prometheus查询示例
# HTTP请求QPS
rate(http_requests_total[5m])
# 平均响应时间
rate(http_request_duration_seconds_sum[5m]) / rate(http_request_duration_seconds_count[5m])
容器相关问题
1. 容器启动失败
# 查看容器状态
docker-compose ps
# 查看容器日志
docker-compose logs <service_name>
# 重新构建镜像
docker-compose build --no-cache
2. 网络连接问题
# 检查网络配置
docker network ls
docker network inspect tyapi-network
# 测试容器间连接
docker exec -it tyapi-server ping postgres
3. 数据持久化问题
# 检查数据卷
docker volume ls
docker volume inspect postgres_data
# 备份数据
docker exec tyapi-postgres pg_dump -U postgres tyapi_dev > backup.sql
性能问题
1. 响应时间过长
诊断步骤：
# 启用详细日志
export LOG_LEVEL=debug
# 分析慢查询
grep "slow query" logs/app.log
# 检查数据库索引
psql -h localhost -U postgres -d tyapi_dev -c "\di"
2. 内存泄漏
诊断步骤：
# 监控内存使用
top -p $(pgrep tyapi-server)
# 生成内存分析报告
go tool pprof -http=:6060 http://localhost:8080/debug/pprof/heap
3. 高 CPU 使用率
诊断步骤：
# CPU性能分析
go tool pprof http://localhost:8080/debug/pprof/profile
# 检查系统负载
uptime
iostat 1 5
开发环境问题
1. 热重载不工作
# 检查文件监控
ls -la .air.toml
# 重启开发服务器
make dev-restart
# 检查文件权限
chmod +x scripts/dev.sh
2. 测试失败
# 运行特定测试
go test -v ./internal/domains/user/...
# 清理测试缓存
go clean -testcache
# 运行集成测试
go test -tags=integration ./test/...
生产环境问题
1. 健康检查失败
# 手动测试健康检查
curl -f http://localhost:8080/api/v1/health
# 检查依赖服务
curl -f http://localhost:8080/api/v1/health/ready
# 查看详细错误
curl -v http://localhost:8080/api/v1/health
2. 负载均衡问题
# 检查上游服务器状态
nginx -t
systemctl status nginx
# 查看负载均衡日志
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
3. 证书问题
# 检查SSL证书
openssl x509 -in /etc/ssl/certs/server.crt -text -noout
# 验证证书有效期
openssl x509 -in /etc/ssl/certs/server.crt -checkend 86400
# 测试HTTPS连接
curl -I https://api.yourdomain.com
调试工具
1. 日志查看工具
# 实时查看日志
journalctl -u tyapi-server -f
# 过滤特定级别日志
journalctl -u tyapi-server -p err
# 按时间范围查看日志
journalctl -u tyapi-server --since "2024-01-01 00:00:00"
2. 网络调试
# 检查端口监听
ss -tlnp | grep :8080
# 网络连接测试
telnet localhost 8080
nc -zv localhost 8080
# DNS解析测试
nslookup api.yourdomain.com
dig api.yourdomain.com
3. 数据库调试
# 连接数据库
psql -h localhost -U postgres -d tyapi_dev
# 查看活动连接
SELECT * FROM pg_stat_activity;
# 查看慢查询
SELECT query, mean_time, calls FROM pg_stat_statements ORDER BY mean_time DESC LIMIT 5;
紧急响应流程
1. 服务宕机
-
快速恢复：
# 重启服务 systemctl restart tyapi-server # 或使用Docker docker-compose restart tyapi-server -
回滚部署：
# K8s回滚 kubectl rollout undo deployment/tyapi-server # Docker回滚 docker-compose down docker-compose up -d --scale tyapi-server=3
2. 数据库问题
-
主从切换：
# 提升从库为主库 sudo -u postgres /usr/lib/postgresql/13/bin/pg_promote -D /var/lib/postgresql/13/main -
数据恢复：
# 从备份恢复 psql -h localhost -U postgres -d tyapi_dev < backup_latest.sql
3. 联系支持
当遇到无法解决的问题时：
- 收集错误信息和日志
- 记录重现步骤
- 准备系统环境信息
- 联系技术支持团队
支持信息收集脚本：
#!/bin/bash
echo "=== TYAPI Server Debug Info ===" > debug_info.txt
echo "Date: $(date)" >> debug_info.txt
echo "Version: $(cat VERSION 2>/dev/null || echo 'unknown')" >> debug_info.txt
echo "" >> debug_info.txt
echo "=== System Info ===" >> debug_info.txt
uname -a >> debug_info.txt
echo "" >> debug_info.txt
echo "=== Docker Status ===" >> debug_info.txt
docker-compose ps >> debug_info.txt
echo "" >> debug_info.txt
echo "=== Recent Logs ===" >> debug_info.txt
tail -50 logs/app.log >> debug_info.txt
echo "" >> debug_info.txt
echo "Debug info collected in debug_info.txt"