geo/docs/05-部署运维/troubleshooting.md

故障排查

常见问题

服务无法启动

端口被占用

# 检查端口占用
lsof -i :8000
lsof -i :3000
lsof -i :5432
lsof -i :6379

# 释放端口
kill -9 <PID>

数据库连接失败

# 检查数据库是否运行
docker-compose ps db

# 检查数据库日志
docker-compose logs db

# 重启数据库
docker-compose restart db

前端问题

页面空白

1. 检查浏览器控制台错误
2. 清除浏览器缓存
3. 检查API地址配置

API请求失败

# 检查后端服务
curl http://localhost:8000/health

# 检查CORS配置
# 确保后端CORS_ORIGINS包含前端地址

后端问题

数据库迁移失败

# 查看迁移状态
cd backend
alembic current
alembic history

# 手动执行迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1

Agent服务异常

# 检查Agent状态
curl http://localhost:8000/api/v1/agents

# 查看Agent日志
docker-compose logs backend | grep Agent

性能问题

响应缓慢

1. 检查数据库查询性能
2. 检查Redis缓存命中率
3. 查看是否有慢查询

# 开启SQL日志
export SQL_ECHO=true

内存泄漏

# 检查容器内存使用
docker stats

# 重启服务
docker-compose restart backend

日志查看

# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f frontend

# 查看最近日志
docker-compose logs --tail=100 backend

调试模式

后端调试

# 开启调试模式
export APP_DEBUG=true

# 使用debug模式启动
uvicorn app.main:app --reload --log-level debug

前端调试

# 开启调试模式
export NEXT_PUBLIC_DEBUG=true

# 使用详细日志启动
npm run dev

健康检查

# 检查所有服务健康状态
curl http://localhost:8000/health
curl http://localhost:8000/health/ready
curl http://localhost:8000/health/live

# 检查数据库连接
docker-compose exec db pg_isready

# 检查Redis连接
docker-compose exec redis redis-cli ping

重置环境

清除所有数据（危险）

# 停止服务并删除数据卷
docker-compose down -v

# 重新启动
docker-compose up -d

重建特定服务

# 重建后端
docker-compose up -d --force-recreate backend

# 重建前端
docker-compose up -d --force-recreate frontend

获取帮助

如遇到无法解决的问题，请提供以下信息：

1. 服务日志
2. 环境变量配置（隐藏敏感信息）
3. 操作系统和Docker版本
4. 问题的完整描述