# 故障排查

## 常见问题

### 服务无法启动

#### 端口被占用

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

# 释放端口
kill -9 <PID>
```

#### 数据库连接失败

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

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

# 重启数据库
docker-compose restart db
```

### 前端问题

#### 页面空白

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

#### API请求失败

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

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

### 后端问题

#### 数据库迁移失败

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

# 手动执行迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1
```

#### Agent服务异常

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

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

### 性能问题

#### 响应缓慢

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

```bash
# 开启SQL日志
export SQL_ECHO=true
```

#### 内存泄漏

```bash
# 检查容器内存使用
docker stats

# 重启服务
docker-compose restart backend
```

## 日志查看

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

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

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

## 调试模式

### 后端调试

```bash
# 开启调试模式
export APP_DEBUG=true

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

### 前端调试

```bash
# 开启调试模式
export NEXT_PUBLIC_DEBUG=true

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

## 健康检查

```bash
# 检查所有服务健康状态
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
```

## 重置环境

### 清除所有数据（危险）

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

# 重新启动
docker-compose up -d
```

### 重建特定服务

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

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

## 获取帮助

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

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