Design Image Search - Docker 部署指南

快速开始

1. 准备环境变量

创建 .env 文件：

# MySQL配置
MYSQL_HOST=host.docker.internal  # Mac/Windows宿主机MySQL
# MYSQL_HOST=172.17.0.1          # Linux宿主机MySQL
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=saas_design

# JWT密钥（与Java应用保持一致）
JWT_SECRET=your_jwt_secret_key

# 可选配置
SYNC_INTERVAL_SECONDS=60
LOG_LEVEL=INFO

2. 构建镜像

# 开发环境
docker-compose build

# 生产环境（多平台构建）
docker buildx build --platform linux/amd64,linux/arm64 -t design-image-search:latest .

3. 启动服务

# 启动主服务
docker-compose up -d

# 查看日志
docker-compose logs -f design-image-search

# 检查健康状态
curl http://localhost:8088/health

4. 停止服务

docker-compose down

# 停止并删除数据卷（慎用！）
docker-compose down -v

---

配置说明

数据持久化

重要的数据目录已挂载为volumes：

volumes:
  - ./data:/app/data          # SQLite数据库 + FAISS索引
  - ./logs:/app/logs          # 日志文件
  - ./config.yml:/app/config.yml:ro  # 配置文件（只读）

MySQL连接

宿主机MySQL：

• Mac/Windows: MYSQL_HOST=host.docker.internal
• Linux: MYSQL_HOST=172.17.0.1

Docker容器MySQL：

• 使用服务名：MYSQL_HOST=mysql-container-name

端口映射

• 应用端口：8088 → 8088
• Nginx（可选）：80 → 80, 443 → 443

---

生产环境部署

使用Nginx反向代理

1. 启动Nginx服务：

   docker-compose --profile production up -d
   

2. 配置nginx.conf（示例）：

   upstream design_search {
   server design-image-search:8088;
   }
   

server { listen 80; server_name your-domain.com;

location / {
    proxy_pass http://design_search;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

}

### 资源限制

在docker-compose.yml中添加：

```yaml
services:
  design-image-search:
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G

---

监控与维护

查看健康状态

# HTTP健康检查
curl http://localhost:8088/health

# 查看容器状态
docker ps
docker inspect design-image-search

日志管理

# 实时日志
docker-compose logs -f

# 查看最近100行
docker-compose logs --tail=100

# 导出日志
docker-compose logs > logs/docker.log

备份数据

# 备份SQLite数据库和FAISS索引
tar -czf backup-$(date +%Y%m%d).tar.gz data/

# 恢复
tar -xzf backup-20231217.tar.gz

---

常见问题

1. OpenCV无法加载

症状： ImportError: libGL.so.1

解决： Dockerfile已包含所需依赖，重新构建镜像

2. MySQL连接失败

症状： Can't connect to MySQL server

解决方案：

• 检查 MYSQL_HOST 配置
• 确认MySQL允许Docker IP访问： sql GRANT ALL ON *.* TO 'root'@'172.17.0.%' IDENTIFIED BY 'password'; FLUSH PRIVILEGES;

3. FAISS索引损坏

症状： 搜索返回空结果

解决方案：

# 进入容器
docker exec -it design-image-search bash

# 手动触发重建
python -c "from database import DatabaseManager; from core.faiss_manager import FAISSManager; import yaml; config=yaml.safe_load(open('config.yml')); fm=FAISSManager(config['faiss']['index_path'], config['faiss']['mapping_path'], config['faiss']['tombstone_path'], config['faiss']['vector_dim']); dm=DatabaseManager(config['database']['sqlite']['path']); fm.rebuild_index(dm)"

4. 权限问题

症状： Permission denied

解决方案：

# 修改宿主机目录权限
chmod -R 755 data/ logs/
chown -R 1000:1000 data/ logs/

---

更新部署

更新代码

# 拉取最新代码
git pull

# 重新构建并启动
docker-compose up -d --build

# 查看新版本日志
docker-compose logs -f design-image-search

零停机更新

# 1. 构建新镜像
docker-compose build

# 2. 启动新容器（临时端口）
docker run -d --name design-search-new \
  -p 8089:8088 \
  -v $(pwd)/data:/app/data \
  --env-file .env \
  design-image-search:latest

# 3. 验证新版本
curl http://localhost:8089/health

# 4. 切换流量（更新Nginx配置）

# 5. 停止旧容器
docker-compose down

---

安全建议

1. 非root用户运行 ✓（已配置）
2. 只读配置文件 ✓（已配置）
3. 环境变量管理：使用 .env 文件，不要提交到Git
4. 定期更新：及时更新基础镜像和依赖
5. 网络隔离：使用独立Docker网络
6. 日志轮转：配置logrotate防止日志占满磁盘

---

支持

遇到问题请查看：

• 应用日志：docker-compose logs design-image-search
• 系统日志：./logs/
• 健康检查：http://localhost:8088/health