Flask应用中Sqlalchemy无法连接PostgreSQL数据库问题排查

问题1：PostgreSQL容器启动后自动关闭 #

从PostgreSQL日志可见，服务启动后很快收到关闭请求，核心原因是数据目录挂载配置错误：
你的postgres服务卷配置为- /var/lib/postgresql，但PostgreSQL官方镜像的默认数据目录是/var/lib/postgresql/data。挂载上级目录会干扰容器内部的数据初始化流程，导致PostgreSQL无法正常运行，最终自动退出。

修复方案：
修改docker-compose.yml中postgres的卷配置，改为挂载到正确的数据目录：

postgres:
  restart: always
  image: postgres:latest
  volumes:
    - postgres_data:/var/lib/postgresql/data  # 使用命名卷持久化数据
  environment:
    POSTGRES_PASSWORD: 1234
    POSTGRES_USER: postgres
    POSTGRES_DB: postgres
    POSTGRES_INITDB_ARGS: "-A md5"
  ports:
    - "5432:5432"

# 在docker-compose.yml末尾添加命名卷定义
volumes:
  postgres_data:

问题2：应用连接数据库的主机地址错误 #

Python应用日志显示尝试连接0.0.0.0:5432，但在Docker Compose的服务网络中，跨服务访问需要使用目标服务的名称postgres作为主机地址，0.0.0.0是容器自身的监听地址，不能用于访问其他服务。

修复方案：
修改Flask应用的数据库URL配置，将主机部分改为postgres：

# SQLAlchemy数据库连接示例配置
SQLALCHEMY_DATABASE_URI = "postgresql://postgres:1234@postgres:5432/postgres"

问题3：容器启动顺序与服务就绪检测 #

depends_on仅保证postgres容器先启动，但不保证PostgreSQL服务已经完全就绪并可以接受连接。如果应用在PostgreSQL初始化完成前尝试连接，就会出现连接拒绝错误。

修复方案：

1. 给postgres服务添加健康检查，确保服务就绪后再启动backend：

postgres:
  # 其他配置不变
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 5s
    timeout: 5s
    retries: 5

2. 修改backend服务的depends_on，依赖postgres的健康状态：

backend:
  # 其他配置不变
  depends_on:
    postgres:
      condition: service_healthy

额外优化：Dockerfile冗余处理 #

你的Dockerfile中有重复的pip3 install -r requirements.txt命令，删除其中一条以减少构建时间：

# 原重复命令
RUN --mount=type=cache,target=/root/.cache/pip pip3 install -r requirements.txt
RUN pip3 install -r requirements.txt

# 修改后保留带缓存的版本
RUN --mount=type=cache,target=/root/.cache/pip pip3 install -r requirements.txt

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