Docker化FastAPI连接已有Docker容器PostgreSQL问题求助

核心问题说明 #

容器默认运行在独立网络空间，localhost在容器内指向自身而非宿主机，必须通过容器网络别名/容器名实现跨容器通信，且两个容器需处于同一个网络。

步骤1：确保FastAPI与PostgreSQL容器在同一网络 #

方式1：复用PostgreSQL容器已在的网络 #

1. 查看PostgreSQL容器所属网络：

   docker inspect <postgres-container-name> | grep Networks
   

2. 运行FastAPI容器时指定该网络：

   docker run -d --name fastapi-app --network <postgres-network-name> -p 8000:8000 your-fastapi-image
   

方式2：创建自定义网络并连接两个容器 #

1. 创建自定义网络：

   docker network create app-shared-network
   

2. 将已有PostgreSQL容器连接到该网络：

   docker network connect app-shared-network <postgres-container-name>
   

3. 运行FastAPI容器时加入该网络：

   docker run -d --name fastapi-app --network app-shared-network -p 8000:8000 your-fastapi-image
   

步骤2：修改FastAPI数据库连接URL #

将本地使用的localhost:5432替换为PostgreSQL容器的名称（或网络别名），示例：

# main.py 或配置文件中
DATABASE_URL = "postgresql://db_user:db_password@<postgres-container-name>:5432/target_db_name"

注：若PostgreSQL容器设置了网络别名，也可使用别名替代容器名。

步骤3：FastAPI Dockerfile示例 #

FROM python:3.11-slim

WORKDIR /app

# 安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目代码
COPY . .

# 启动FastAPI服务（绑定0.0.0.0允许容器外部访问）
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

步骤4：Docker Compose配置（不新建数据库） #

若使用Compose，需指定使用外部已有网络，且不定义PostgreSQL服务：

version: '3.8'

services:
  fastapi:
    build: .
    ports:
      - "8000:8000"
    environment:
      # 替换为实际的数据库信息和容器名
      - DATABASE_URL=postgresql://db_user:db_password@<postgres-container-name>:5432/target_db_name
    networks:
      - app-shared-network

networks:
  app-shared-network:
    external: true  # 声明使用已存在的自定义网络

常见排查点 #

• 确认PostgreSQL配置：postgresql.conf中listen_addresses = '*'，允许非本地连接；pg_hba.conf添加自定义网络的IP段权限（如host all all 172.18.0.0/16 md5，子网需匹配实际网络）
• 验证容器间连通性：进入FastAPI容器，执行ping <postgres-container-name>，确认能解析并连通
• 检查数据库账号权限：确保账号允许从容器网络的IP段连接

内容的提问来源于stack exchange，提问作者Wana Muhanga