故障排查手册

本文档提供井云服务中心后端项目的常见问题排查指南，帮助开发者和运维人员快速定位和解决问题。

🔍 问题诊断流程

1. 检查服务状态

# 检查所有服务状态
docker-compose -f deployments/docker-compose.local.yml ps

# 检查 Kubernetes Pod 状态
kubectl get pods -n jingyun

# 检查服务详情
kubectl describe pod <pod-name> -n jingyun

2. 查看服务日志

# Docker Compose 日志
docker-compose -f deployments/docker-compose.local.yml logs -f [service-name]

# Kubernetes 日志
kubectl logs -f deployment/<service-name> -n jingyun

# 查看最近的日志
kubectl logs --tail=100 deployment/<service-name> -n jingyun

3. 检查网络连通性

# 检查端口是否开放
telnet localhost 8000
curl -I http://localhost:8000/health

# 检查服务发现
curl http://localhost:8500/v1/agent/services

🚨 常见问题

服务启动问题

Q: 服务启动失败，提示端口被占用

解决方案:

# 查看端口占用
lsof -i :8000
netstat -tulpn | grep :8000

# 杀死占用进程
kill -9 <PID>

# 或者修改端口配置
vim conf/config.yaml

Q: 服务启动失败，提示无法连接数据库

解决方案:

# 1. 检查数据库服务状态
docker-compose -f deployments/docker-compose.local.yml ps postgres-jingyun

# 2. 检查数据库连接
docker exec -it postgres-jingyun psql -U akita -d akita -c "\l"

# 3. 检查网络连通性
docker exec -it gateway ping postgres-jingyun

# 4. 验证数据库配置
grep -r "database" conf/

Q: 服务启动失败，提示无法连接 Redis

解决方案:

# 1. 检查 Redis 服务状态
docker-compose -f deployments/docker-compose.local.yml ps redis-jingyun

# 2. 测试 Redis 连接
docker exec -it redis-jingyun redis-cli ping

# 3. 检查 Redis 配置
docker exec -it redis-jingyun redis-cli config get "*"

# 4. 清理 Redis 数据（如需要）
docker exec -it redis-jingyun redis-cli FLUSHALL

Q: 服务启动失败，提示无法连接 Consul

解决方案:

# 1. 检查 Consul 服务状态
docker-compose -f deployments/docker-compose.local.yml ps consul

# 2. 检查 Consul UI
open http://localhost:8500

# 3. 检查服务注册
curl http://localhost:8500/v1/agent/services

# 4. 检查 Consul 配置
curl http://localhost:8500/v1/kv/kratos/?keys

API 调用问题

Q: API 返回 401 Unauthorized

解决方案:

# 1. 检查 Token 是否有效
echo "your-token" | cut -d. -f2 | base64 -d

# 2. 生成新的 Token
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}'

# 3. 检查 Token 过期时间
echo "your-token" | cut -d. -f2 | base64 -d | jq '.exp'

Q: API 返回 500 Internal Server Error

解决方案:

# 1. 查看详细错误日志
docker-compose -f deployments/docker-compose.local.yml logs -f gateway

# 2. 检查数据库连接
docker exec -it postgres-jingyun psql -U akita -d akita -c "SELECT 1"

# 3. 检查 Redis 连接
docker exec -it redis-jingyun redis-cli ping

# 4. 检查依赖服务状态
curl http://localhost:8500/v1/agent/services

Q: API 响应超时

解决方案:

# 1. 检查服务资源使用
docker stats

# 2. 检查网络延迟
ping localhost
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:8000/health

# 3. 调整超时配置
vim conf/config.yaml
# 增加 timeout 值

数据库问题

Q: 数据库连接数过多

解决方案:

# 1. 查看当前连接数
docker exec -it postgres-jingyun psql -U akita -d akita -c "SELECT count(*) FROM pg_stat_activity;"

# 2. 查看连接详情
docker exec -it postgres-jingyun psql -U akita -d akita -c "SELECT * FROM pg_stat_activity;"

# 3. 杀死空闲连接
docker exec -it postgres-jingyun psql -U akita -d akita -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle';"

# 4. 调整连接池配置
# 在配置文件中调整 max_connections

Q: 数据库查询慢

解决方案:

# 1. 查看慢查询日志
docker exec -it postgres-jingyun grep "slow" /var/log/postgresql/postgresql-*.log

# 2. 分析查询计划
docker exec -it postgres-jingyun psql -U akita -d akita -c "EXPLAIN ANALYZE SELECT * FROM users WHERE id = 1;"

# 3. 检查索引使用情况
docker exec -it postgres-jingyun psql -U akita -d akita -c "SELECT * FROM pg_stat_user_indexes;"

# 4. 创建缺失索引
docker exec -it postgres-jingyun psql -U akita -d akita -c "CREATE INDEX CONCURRENTLY idx_users_email ON users(email);"

Q: 数据库锁表

解决方案:

# 1. 查看锁信息
docker exec -it postgres-jingyun psql -U akita -d akita -c "SELECT * FROM pg_locks;"

# 2. 查看锁等待关系
docker exec -it postgres-jingyun psql -U akita -d akita -c "
SELECT 
    blocked_locks.pid AS blocked_pid,
    blocked_activity.usename AS blocked_user,
    blocking_locks.pid AS blocking_pid,
    blocking_activity.usename AS blocking_user,
    blocked_activity.query AS blocked_statement,
    blocking_activity.query AS current_statement_in_blocking_process
FROM pg_catalog.pg_locks blocked_locks
    JOIN pg_catalog.pg_stat_activity blocked_activity ON blocked_activity.pid = blocked_locks.pid
    JOIN pg_catalog.pg_locks blocking_locks ON blocking_locks.locktype = blocked_locks.locktype
    JOIN pg_catalog.pg_stat_activity blocking_activity ON blocking_activity.pid = blocking_locks.pid
WHERE NOT blocked_locks.granted;
"

# 3. 杀死阻塞进程（谨慎操作）
docker exec -it postgres-jingyun psql -U akita -d akita -c "SELECT pg_terminate_backend(<blocking_pid>);"

缓存问题

Q: Redis 连接超时

解决方案:

# 1. 检查 Redis 状态
docker exec -it redis-jingyun redis-cli info server

# 2. 检查内存使用
docker exec -it redis-jingyun redis-cli info memory

# 3. 清理过期键
docker exec -it redis-jingyun redis-cli --scan --pattern "*" | xargs docker exec -i redis-jingyun redis-cli del

# 4. 重启 Redis 服务
docker-compose -f deployments/docker-compose.local.yml restart redis-jingyun

Q: 缓存穿透

解决方案:

# 1. 检查缓存命中率
docker exec -it redis-jingyun redis-cli info stats | grep keyspace

# 2. 设置空值缓存
# 在代码中添加对空值的缓存

# 3. 使用布隆过滤器
# 引入布隆过滤器防止恶意查询

消息队列问题

Q: RabbitMQ 消息堆积

解决方案:

# 1. 检查队列状态
curl -u akita:chrishy123 http://localhost:15672/api/queues

# 2. 查看消息数量
curl -u akita:chrishy123 http://localhost:15672/api/queues/%2f/payment/events

# 3. 清理队列（谨慎操作）
curl -u akita:chrishy123 -X DELETE http://localhost:15672/api/queues/%2f/payment/events

# 4. 增加消费者实例
# 水平扩展消费者服务

Q: 消费者处理失败

解决方案:

# 1. 查看死信队列
curl -u akita:chrishy123 http://localhost:15672/api/queues/%2f/payment.dlq

# 2. 重新投递死信消息
# 使用管理界面或 API 重新投递

# 3. 检查消费者日志
docker-compose -f deployments/docker-compose.local.yml logs -f payment

# 4. 增加重试机制
# 在代码中增加消息重试逻辑

🔧 调试技巧

1. 启用调试模式

# 设置调试日志级别
export LOG_LEVEL=debug

# 运行服务
./bin/gateway -conf consul:8500

2. 使用 Delve 调试器

# 安装 delve
go install github.com/go-delve/delve/cmd/dlv@latest

# 调试服务
cd services/gateway
dlv debug ./cmd/gateway

3. 性能分析

# CPU 性能分析
go tool pprof http://localhost:8000/debug/pprof/profile

# 内存分析
go tool pprof http://localhost:8000/debug/pprof/heap

# Goroutine 分析
go tool pprof http://localhost:8000/debug/pprof/goroutine

4. 网络调试

# 抓包分析
tcpdump -i any port 8000 -w capture.pcap

# 分析抓包文件
wireshark capture.pcap

# 检查 DNS 解析
nslookup consul
dig consul

📊 监控指标

关键指标监控

指标类型	指标名称	告警阈值	说明
HTTP	http_requests_total	-	HTTP 请求总数
HTTP	http_request_duration_seconds	> 1s	HTTP 请求延迟
HTTP	http_requests_errors_rate	> 5%	HTTP 错误率
gRPC	grpc_requests_total	-	gRPC 请求总数
gRPC	grpc_request_duration_seconds	> 500ms	gRPC 请求延迟
数据库	db_connections_active	> 80%	数据库连接数
数据库	db_query_duration_seconds	> 100ms	数据库查询延迟
缓存	cache_hit_rate	< 80%	缓存命中率
队列	queue_messages	> 1000	队列消息堆积
系统	cpu_usage	> 80%	CPU 使用率
系统	memory_usage	> 85%	内存使用率

Grafana 仪表板

推荐配置以下仪表板：

1. 系统概览仪表板

   • 服务健康状态
   • 请求量 QPS
   • 错误率
   • 响应时间

2. 基础设施仪表板

   • 数据库性能
   • 缓存性能
   • 消息队列状态
   • 系统资源

3. 业务指标仪表板

   • 用户注册数
   • 订单量
   • 支付成功率
   • 智能体使用量

🚨 应急响应

服务宕机处理流程

1. 发现问题 (1-5分钟)

   • 监控告警触发
   • 用户反馈问题
   • 自动化检测发现

2. 快速响应 (5-15分钟)

   • 确认影响范围
   • 启动应急响应小组
   • 通知相关人员

3. 问题定位 (15-30分钟)

   • 查看监控指标
   • 分析服务日志
   • 检查依赖服务

4. 紧急修复 (30-60分钟)

   • 重启异常服务
   • 回滚最近变更
   • 切换备用方案

5. 恢复验证 (60-90分钟)

   • 验证服务恢复
   • 检查业务功能
   • 监控系统状态

6. 事后复盘 (24小时内)

   • 分析根本原因
   • 制定改进措施
   • 更新应急预案

联系方式

角色	联系人	电话	邮箱
技术负责人	张三	138xxxx8888	zhangsan@jingyun.team
运维负责人	李四	139xxxx9999	lisi@jingyun.team
产品负责人	王五	137xxxx7777	wangwu@jingyun.team

---

📖 相关文档:

• 📊 配置监控告警 - 监控配置和告警设置
• 部署指南 - 部署相关文档
• 配置管理 - 系统配置说明
• 灾难恢复 - 灾难恢复方案