# 智能算法展示平台 - 故障排除指南

## Docker镜像拉取问题

### 问题描述
当尝试使用Docker Compose部署时，可能会遇到镜像拉取缓慢或失败的问题，特别是在网络受限的环境中。

### 解决方案

#### 1. 配置Docker镜像加速器

对于中国大陆用户，可以配置Docker镜像加速器：

```bash
# 编辑Docker守护进程配置
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}
EOF

# 重启Docker服务
sudo systemctl restart docker
```

#### 2. 手动拉取镜像

如果自动拉取失败，可以手动拉取所需镜像：

```bash
# 拉取所有必需的镜像
docker pull postgres:14-alpine
docker pull redis:7-alpine
docker pull minio/minio:latest
docker pull nginx:alpine
docker pull python:3.9-slim
docker pull node:18-alpine
```

#### 3. 使用不同的Compose文件

我们提供了两个Compose文件：

- `docker-compose-full.yml` - 适用于网络良好的环境，包含构建步骤
- `compose-without-build.yml` - 适用于网络受限的环境，使用预拉取的镜像

#### 4. 本地开发模式

如果Docker部署遇到困难，可以使用本地开发模式：

```bash
# 启动后端服务
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload

# 启动前端服务
cd frontend
npm install
npm run dev
```

## 端口冲突问题

### 问题描述
部署时可能遇到端口已被占用的情况。

### 解决方案

检查并释放被占用的端口：

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

# 终止占用端口的进程
kill -9 <PID>
```

## 数据库连接问题

### 问题描述
后端服务启动后无法连接到数据库。

### 解决方案

确保PostgreSQL服务已完全启动后再启动后端服务：

```bash
# 等待PostgreSQL准备就绪
docker exec -it algorithm-showcase-postgres pg_isready
```

## MinIO连接问题

### 问题描述
后端服务无法连接到MinIO对象存储。

### 解决方案

MinIO服务在首次启动时需要一些时间初始化存储桶。如果遇到连接问题，可以：

1. 等待MinIO服务完全启动
2. 检查MinIO控制台 http://localhost:9001
3. 验证凭据是否正确（admin/minioadmin）

## 前端API连接问题

### 问题描述
前端无法连接到后端API。

### 解决方案

确保环境变量正确设置：

```bash
# 检查前端环境变量
VITE_API_BASE_URL=http://localhost:8000/api
```

## 部署验证

部署完成后，可以通过以下方式验证服务是否正常运行：

```bash
# 检查所有服务状态
docker-compose -f docker-compose-full.yml ps

# 测试后端API
curl http://localhost:8000/health

# 访问前端
open http://localhost:3000

# 访问API文档
open http://localhost:8000/docs
```

## 常见错误及解决方案

### 错误：`connection refused`
- 检查相应服务是否已启动
- 检查防火墙设置

### 错误：`permission denied`
- 检查文件权限
- 确保有足够的磁盘空间

### 错误：`port already allocated`
- 检查端口占用情况
- 终止占用端口的进程

### 错误：`image not found`
- 手动拉取缺失的镜像
- 检查镜像名称和标签是否正确

## 调试技巧

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

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

### 进入容器调试
```bash
# 进入后端容器
docker exec -it algorithm-showcase-backend bash

# 进入前端容器
docker exec -it algorithm-showcase-frontend sh
```

### 清理部署
```bash
# 停止并删除所有服务
docker-compose -f docker-compose-full.yml down

# 删除卷（谨慎使用，会删除所有数据）
docker-compose -f docker-compose-full.yml down -v

# 清理孤立容器
docker container prune
```

## 联系支持

如果遇到无法解决的问题，请联系技术支持并提供以下信息：

1. 操作系统版本
2. Docker和Docker Compose版本
3. 完整的错误日志
4. 已尝试的解决方案