first commit

TROUBLESHOOTING.md

@@ -0,0 +1,207 @@
+# 智能算法展示平台 - 故障排除指南
+
+## 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. 已尝试的解决方案