algorithm/TROUBLESHOOTING.md

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

Docker镜像拉取问题

问题描述

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

解决方案

1. 配置Docker镜像加速器

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

# 编辑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. 手动拉取镜像

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

# 拉取所有必需的镜像
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部署遇到困难，可以使用本地开发模式：

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

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

端口冲突问题

问题描述

部署时可能遇到端口已被占用的情况。

解决方案

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

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

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

数据库连接问题

问题描述

后端服务启动后无法连接到数据库。

解决方案

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

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

MinIO连接问题

问题描述

后端服务无法连接到MinIO对象存储。

解决方案

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

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

前端API连接问题

问题描述

前端无法连接到后端API。

解决方案

确保环境变量正确设置：

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

部署验证

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

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

• 手动拉取缺失的镜像
• 检查镜像名称和标签是否正确

调试技巧

查看服务日志

# 查看所有服务日志
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

进入容器调试

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

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

清理部署

# 停止并删除所有服务
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. 已尝试的解决方案