FastAPI+Docker环境下Alembic迁移连接PostgreSQL 5432端口失败

核心问题原因 #

用docker run sm-api_api alembic upgrade head执行迁移时，容器内的localhost指向容器自身，而非宿主机或Docker-compose网络中的PostgreSQL服务，导致连接被拒绝。

排查步骤 #

1. 检查数据库连接配置

   • 查看.env文件中的DB_HOST是否设为localhost，这是最常见的错误点。
   • 确认Alembic配置文件alembic.ini中的sqlalchemy.url是否正确读取了环境变量，而非硬编码localhost。

2. 确认PostgreSQL运行状态

   • 如果PostgreSQL是Docker-compose管理的服务，执行docker-compose ps检查db服务是否正常启动。
   • 如果PostgreSQL在宿主机，执行ps aux | grep postgres确认服务运行，同时检查端口5432是否被监听：netstat -tulpn | grep 5432。

3. 验证Docker网络连通性

   • 若使用docker-compose，docker run创建的容器不会加入compose默认网络，无法访问db服务。改用docker-compose exec api ping <DB_HOST>测试连通性。

针对性解决方法 #

场景1：PostgreSQL与API均在Docker-compose中部署 #

1. 修改.env文件，将DB_HOST设为docker-compose中PostgreSQL服务的名称（通常是db）：

   DB_HOST=db
   DB_PORT=5432
   DB_USER=your_user
   DB_PASSWORD=your_pass
   DB_NAME=your_db
   

2. 确保docker-compose.yml中api服务配置了依赖，且网络互通：

   services:
     db:
       image: postgres:15
       environment:
         POSTGRES_USER: ${DB_USER}
         POSTGRES_PASSWORD: ${DB_PASSWORD}
         POSTGRES_DB: ${DB_NAME}
       volumes:
         - postgres_data:/var/lib/postgresql/data/
     api:
       build: .
       depends_on:
         - db
       environment:
         - DB_HOST=db
   

3. 使用compose命令执行迁移（而非docker run）：

   docker-compose exec api alembic upgrade head
   

场景2：PostgreSQL部署在宿主机 #

1. 修改.env中的DB_HOST为宿主机的实际IP（如192.168.1.100），Windows/macOS可使用host.docker.internal，Linux需添加--network host参数运行容器。
2. 配置宿主机PostgreSQL允许远程连接：
   • 编辑postgresql.conf，设置listen_addresses = '*'
   • 编辑pg_hba.conf，添加一行：host all all <容器IP段> md5（如host all all 172.17.0.0/16 md5）
3. 重启PostgreSQL服务，再执行迁移命令。

额外检查点 #

• 确认Dockerfile中已安装PostgreSQL客户端依赖（如psycopg2-binary），避免因缺少驱动导致连接失败。
• 查看Alembic日志，确认sqlalchemy.url是否正确拼接了环境变量：docker-compose exec api cat alembic.ini | grep sqlalchemy.url

内容的提问来源于stack exchange，提问作者Fre An