Evolution API 数据库迁移失败问题分析与解决方案

问题背景

在使用 Evolution API 项目时，许多开发者遇到了数据库迁移失败的问题。具体表现为在执行 docker-compose up -d 命令后，系统无法完成 PostgreSQL 数据库的迁移操作，导致 API 服务无法正常启动。

错误现象

开发者报告的主要错误信息包括：

1. 数据库连接失败：Can't reach database server at localhost:5432
2. 认证失败：Authentication failed against database server at postgres

这些错误表明系统无法建立与数据库的有效连接，导致迁移过程无法完成。

根本原因分析

经过深入分析，我们发现这些问题主要由以下几个因素导致：

1. 网络配置不当：Docker 容器间的网络通信未正确配置，导致 API 服务容器无法访问数据库容器。

2. 连接字符串配置错误：环境变量中仍使用 localhost 作为数据库主机地址，这在 Docker 环境中是不正确的。

3. 认证信息不匹配：数据库连接字符串中的用户名/密码与数据库容器配置不一致。

解决方案

1. 正确的 Docker Compose 配置

确保你的 docker-compose.yml 文件包含正确的网络配置：

version: '3.9'
services:
  evolution-api:
    container_name: evolution_api
    image: atendai/evolution-api:v2.1.1
    restart: always
    ports:
      - "8080:8080"
    env_file:
      - .env
    volumes:
      - evolution_instances:/evolution/instances
    networks:
      - evolution-net

volumes:
  evolution_instances:

networks:
  evolution-net:
    name: evolution-net
    driver: bridge

2. 正确的环境变量配置

在 .env 文件中，确保使用容器名称而非 localhost 作为主机地址：

# PostgreSQL 连接字符串
DATABASE_CONNECTION_URI='postgresql://user:password@postgres:5432/evolution?schema=public'

# Redis 连接字符串
CACHE_REDIS_URI=redis://redis:6379/6

3. 验证数据库容器状态

在启动 API 服务前，确保数据库容器已正常运行：

docker-compose up -d postgres
docker ps  # 确认 postgres 容器状态为健康

4. 检查数据库认证信息

确保连接字符串中的用户名和密码与数据库容器配置一致。如果使用官方镜像，默认用户通常是 postgres，密码可以通过环境变量 POSTGRES_PASSWORD 设置。

最佳实践建议

1. 版本兼容性：使用 PostgreSQL 16.4 版本，已知与 Evolution API 兼容性良好。

2. 分步部署：先启动数据库服务，确认正常运行后再启动 API 服务。

3. 日志检查：使用 docker logs <container_name> 检查容器日志，获取更详细的错误信息。

4. 网络隔离：为 Evolution API 相关服务创建专用网络，避免与其他服务冲突。

总结

Evolution API 的数据库迁移问题通常源于容器网络配置和连接字符串设置不当。通过正确配置 Docker 网络、使用容器名称作为主机地址以及验证认证信息，大多数迁移失败问题都可以得到解决。遵循上述解决方案和最佳实践，开发者可以顺利完成 Evolution API 的部署和数据库迁移工作。