FastAPI容器构建时无法连接PostgreSQL容器，Alembic迁移失败

Docker镜像构建过程处于独立的隔离环境，和你本地运行的postgres_db容器不在同一网络命名空间里。所以构建阶段执行alembic upgrade HEAD时，根本无法访问到PostgreSQL容器——哪怕替换容器IP也不行，因为构建容器的网络是临时创建的，和宿主机、运行中容器的网络不互通。

方案1：将迁移移到容器启动阶段（推荐） #

不要在Dockerfile的构建阶段执行迁移，而是把迁移命令放到容器启动脚本里。容器启动后会加入和postgres_db同一网络，此时就能正常解析主机名并连接数据库。

操作步骤： #

1. 修改Dockerfile，移除构建阶段的alembic upgrade HEAD，替换为启动命令：

# 保留原有基础镜像、依赖安装等步骤
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

# 启动时先执行迁移，再启动FastAPI服务
CMD ["sh", "-c", "alembic upgrade HEAD && uvicorn main:app --host 0.0.0.0 --port 8000"]

2. 确保FastAPI容器和postgres_db在同一Docker网络（无自定义网络则先创建）：

# 创建自定义网络
docker network create app-network
# 重启PostgreSQL容器加入该网络
docker run -d --name postgres_db --network app-network -e POSTGRES_USER=your_user -e POSTGRES_PASSWORD=your_pwd -e POSTGRES_DB=your_db postgres
# 启动FastAPI容器时也加入同一网络
docker run -d --name fastapi-backend --network app-network -e DATABASE_URL=postgresql://your_user:your_pwd@postgres_db:5432/your_db -p 8000:8000 backend

方案2：构建阶段使用临时PostgreSQL容器（适合CI/CD场景） #

如果必须在构建阶段完成迁移，可以用Docker多阶段构建，在构建阶段临时启动一个PostgreSQL容器供迁移使用：

示例Dockerfile： #

# 第一阶段：执行数据库迁移
FROM python:3.11-slim as migrate-stage
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

# 安装Docker CLI，用于启动临时PostgreSQL容器
RUN apt-get update && apt-get install -y docker.io

# 启动临时PostgreSQL、执行迁移后清理容器
RUN docker run -d --name temp-postgres -e POSTGRES_USER=your_user -e POSTGRES_PASSWORD=your_pwd -e POSTGRES_DB=your_db postgres && \
    sleep 10 && # 等待PostgreSQL启动完成
    alembic upgrade HEAD && \
    docker stop temp-postgres && docker rm temp-postgres

# 第二阶段：构建最终运行镜像
FROM python:3.11-slim
WORKDIR /app
COPY --from=migrate-stage /app /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

注意：这种方式需要构建环境能访问Docker守护进程（本地构建时需挂载/var/run/docker.sock），CI/CD环境也要配置Docker权限。

方案3：构建阶段连接宿主机映射的PostgreSQL（不推荐） #

如果你的postgres_db容器绑定了宿主机端口（比如-p 5432:5432），可以在构建阶段用宿主机专属域名访问，但通用性差，仅适合本地调试：

• Linux/macOS/Windows：构建阶段可使用host.docker.internal作为宿主机域名
  修改构建阶段的数据库连接变量：

ENV DATABASE_URL=postgresql://your_user:your_pwd@host.docker.internal:5432/your_db

然后在Dockerfile中执行alembic upgrade HEAD即可，但这种方式依赖宿主机端口映射，生产环境不建议使用。

内容的提问来源于stack exchange，提问作者RAHUL JHA