207 lines
4.2 KiB
Markdown
207 lines
4.2 KiB
Markdown
# 智能算法展示平台 - 故障排除指南
|
||
|
||
## 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. 已尝试的解决方案 |