Docker环境下Python无法通过服务名连接PostgreSQL数据库

问题根源 #

Python容器无法解析Docker Compose服务名db到PostgreSQL容器的IP，但Node.js容器可正常解析，且用数据库IP能连接，说明问题出在Docker网络DNS解析或容器网络配置层面。

解决方案步骤 #

1. 确认Python与DB容器处于同一Docker网络 #

Docker Compose默认会为所有服务创建默认网络（命名为[项目名]_default），所有服务自动加入该网络。可通过以下命令验证：

• 查看所有Docker网络：docker network ls
• 查看db容器所在网络：docker inspect db --format '{{.NetworkSettings.Networks}}'
• 查看python-app容器所在网络：docker inspect python-app --format '{{.NetworkSettings.Networks}}'

若两者不在同一网络，需在docker-compose.yaml的python-app服务中显式指定默认网络：

python-app:
  build: .
  env_file: .env
  depends_on:
    - db
    - web
  networks:
    - default

2. 验证Python容器内的DNS解析能力 #

进入Python容器，尝试解析db服务名，排查DNS是否正常：

docker exec -it python-app nslookup db

若解析失败，可在docker-compose.yaml中为python-app配置公共DNS服务器：

python-app:
  build: .
  env_file: .env
  depends_on:
    - db
    - web
  dns:
    - 8.8.8.8
    - 1.1.1.1

3. 替换固定休眠为连接重试逻辑 #

depends_on仅等待容器启动，不保证PostgreSQL服务完全就绪。固定time.sleep(10)可能因数据库初始化慢失效，改用重试逻辑更可靠：

def get_users():
    max_retries = 5
    retry_delay = 3
    for attempt in range(max_retries):
        try:
            conn = psycopg2.connect(
                dbname=DB_NAME,
                user=DB_USER,
                password=DB_PASSWORD,
                host=DB_HOST,
                port=DB_PORT
            )
            print("Database connection successful")
            
            with conn.cursor() as cur:
                cur.execute("SELECT * FROM users")
                users = cur.fetchall()
            
            conn.close()
            return users
        except psycopg2.Error as connection_error:
            if attempt < max_retries - 1:
                print(f"Connection attempt {attempt+1} failed, retrying in {retry_delay}s...")
                time.sleep(retry_delay)
            else:
                print(f"Database connection failed after {max_retries} attempts: {connection_error}")

4. 检查Python Dockerfile配置 #

确保Dockerfile未使用特殊网络模式（如--network=host），保持默认桥接网络。示例Dockerfile：

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "your_script.py"]

5. 重启Docker Compose环境 #

网络缓存可能导致解析异常，重启所有容器：

docker-compose down
docker-compose up --build

内容的提问来源于stack exchange，提问作者Christian Hulot