Docker Compose 配了 depends_on 仍连不上数据库?就绪检查与启动顺序排查

Docker Compose 已配置 depends_on,应用启动时却仍报数据库连接失败,可能是数据库进程启动了,但还没有准备好接受连接。本文用 PostgreSQL 示例说明 healthcheck、service_healthy 和一次性迁移任务的配置,区分启动等待、运行时重连与重启策略,并给出变量转义、日志核查、部署验证及配置回退方法。
Docker Compose 配了 depends_on 仍连不上数据库?就绪检查与启动顺序排查

执行 docker compose up 后,数据库和应用都显示 running,应用日志却报 connection refused。过一会儿单独重启应用,它又能连上。遇到这种情况,先检查启动时序:depends_on 的简写只安排依赖服务先启动,数据库此时可能仍在恢复数据、执行初始化脚本,尚不能接受连接。

处理这类启动竞态,可以给数据库配置 healthcheck,再让应用通过 condition: service_healthy 等待检查通过。应用自身仍需具备重试和断线重连能力,才能处理数据库运行期间的短暂中断。Docker 官方启动顺序文档说明了这些条件的区别,见文末资料 [1]。

本文面向使用 docker compose 插件的单机部署,示例使用 PostgreSQL。旧版 docker-compose 和 docker stack deploy 的行为不能直接按本文推断。以下配置用于说明写法,未在你的服务器上执行。

先分清:连接被拒绝,还是认证失败

在包含 compose.yaml 的目录查看状态与日志:

docker compose version
docker compose ps -a
docker compose logs --since 10m --tail 200 db app

db 和 app 是本文的服务名,请换成实际名称。日志可能包含连接串,转发前先遮掉密码、令牌和内部地址。

如果应用第一次连接报错时,数据库仍在输出初始化或恢复日志,而稍后才出现接受连接的提示,就有理由检查就绪等待。下面这些报错需要分别判断:

现象 优先检查
connection refused 数据库监听是否建立、连接地址和端口
password authentication failed 凭据、数据库账号及认证规则
database does not exist 库名及初始化结果
name resolution failed 服务名、网络配置和 DNS
启动很久后仍反复超时 网络、数据库负载、连接池及服务端日志

容器里的 localhost 指向容器自身。应用访问同一 Compose 网络中的 PostgreSQL,通常应使用服务名 db 和容器端口 5432。仅调整 depends_on,修不好错误的密码、库名或主机地址。

把“先启动”改为“检查通过后启动”

常见的简写配置如下:

services:
  app:
    depends_on:
      - db

它没有声明数据库的就绪标准。下面是一个更完整的示例:

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: appuser
      POSTGRES_DB: appdb
      POSTGRES_PASSWORD: ${DB_PASSWORD:?请先配置 DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
      interval: 5s
      timeout: 3s
      retries: 12
      start_period: 30s

  app:
    image: ${APP_IMAGE:?请配置你的应用镜像}
    environment:
      DB_HOST: db
      DB_PORT: "5432"
      DB_USER: appuser
      DB_NAME: appdb
      DB_PASSWORD: ${DB_PASSWORD:?请先配置 DB_PASSWORD}
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:

APP_IMAGE 必须换成你的应用镜像。DB_HOST 等只是示例环境变量,应用需要实际支持这些名称;有的程序使用 DATABASE_URL,应按其文档配置。密码通过部署环境或受权限控制且不提交到版本库的 .env 文件提供,生产环境应结合应用能力使用 secrets 等凭据机制。

postgres:17 和对应数据目录仅用于说明。已有数据库应保留原镜像版本、卷和挂载位置,不要为了照抄示例切换主版本。初始化变量也不能用来直接修改已有数据卷中的账号和库。

健康检查显式指定 127.0.0.1,通过容器内部 TCP 检查 PostgreSQL 是否接受连接,避免把仅供初始化使用的本地 socket 状态当成 TCP 监听已就绪。它仍没有覆盖应用容器到 db 的完整网络路径。

两个美元符号需要保留:Compose 将 $$ 转义成字面量美元符号,再由容器里的 shell 展开 POSTGRES_USER 和 POSTGRES_DB。直接写单个美元符号时,变量可能提前在宿主机的 Compose 插值阶段被处理,见资料 [3]。

这些检查参数是起点。start_period 是启动宽限期,其间失败通常不计入失败次数;检查一旦成功,容器可以提前变为 healthy,不会强制等满 30 秒。恢复时间较长的数据库,应结合日志调整参数,不能靠扩大等待时间掩盖数据库故障。

healthy 能证明到哪一步

pg_isready 用于判断 PostgreSQL 的连接状态。它返回成功,不等于应用密码正确、业务库可用或数据表已经建好。PostgreSQL 官方文档说明,获取服务状态并不要求提供正确的用户名、密码或数据库名,见资料 [4]。

因此,先看数据库 healthy,再从应用运行环境验证连接和必要的只读查询。如果应用依赖迁移结果,应该把“数据库接受连接”和“迁移成功”分开处理。

例如已有 migrate 服务负责执行一次迁移时,app 的依赖可以改为:

depends_on:
  db:
    condition: service_healthy
  migrate:
    condition: service_completed_successfully

这只是 app 服务下的配置片段。migrate 服务本身也需要等待 db healthy,使用与你的应用匹配的迁移命令,成功后退出 0;失败则返回非零值。应用会等待迁移成功,而不是跟着失败的迁移继续启动。

迁移可能修改数据库结构,执行前应备份,并确认是否允许重复运行、是否需要锁、是否与旧应用兼容。回退 compose.yaml 不会自动回退数据库结构。

数据库运行中断线,depends_on 会再等一次吗

不能把启动时的依赖条件当成持续运行的故障处理机制。数据库启动后出现故障,Compose 不会仅因它后来变为 unhealthy,就自动暂停应用、重跑迁移或修复连接池。

几个配置容易混在一起:

配置或状态 作用范围
condition: service_started 等依赖服务启动,效果对应简写
condition: service_healthy 启动依赖方前,等待健康检查通过
condition: service_completed_successfully 等一次性依赖任务成功退出
depends_on 下的 restart: true 在相关显式 Compose 操作重启或更新依赖后,重启依赖方
服务层的 restart: unless-stopped 按容器退出等事件决定是否重启

depends_on 下的 restart: true 不包含容器运行时自动重启依赖服务的情形。普通 Docker 容器单纯被标记为 unhealthy,也不会因此由重启策略自动重启;重启策略处理的是退出等事件。具体定义见资料 [1][2][5]。

应用侧可以对短暂连接失败采用有上限的指数退避,逐步延长等待并加入随机抖动,同时设置单次超时、总等待期限和告警。认证失败、库不存在等配置错误应明确报出,避免无限重试。恢复连接后,也要清理连接池中的失效连接。

固定 sleep 30 虽然容易写,但数据库快时白等,恢复超过 30 秒时仍会失败。健康检查和应用重试更能贴近实际状态。

修改后怎么验证,失败后怎么回退

先备份实际使用的配置文件:

cp compose.yaml compose.yaml.before-readiness
docker compose config --quiet

cp 示例用于 Linux shell。使用多个 -f 文件时,备份相应文件,并在后续命令中沿用相同参数。config –quiet 用于检查配置能否被解析,不能证明应用环境变量正确或数据库能够连接;如插件不支持该选项,先查看本机命令帮助或升级插件。

选择允许应用短暂重建的维护窗口,再应用修改:

docker compose up -d db app
docker compose ps -a
docker compose logs --since 5m --tail 200 db app
docker compose exec db pg_isready -h 127.0.0.1 -U appuser -d appdb

up -d 可能重建发生配置变化的容器,数据库配置也改变时可能造成数据库中断。需要迁移服务时,把实际 migrate 服务纳入部署流程并核对退出码,不要机械照搬上面的服务列表。

验收应同时看到数据库 healthy、应用连接成功、业务请求恢复。还应在测试环境检查数据库延迟启动和短暂重启后,应用能否恢复连接;只看容器 running 不够。本文没有代替这些环境测试。

如果只是依赖条件或健康检查写错,可恢复原文件并重新应用:

cp compose.yaml.before-readiness compose.yaml
docker compose up -d db app

这只回退配置。已有数据和迁移结果需要按各自备份与恢复方案处理。排查启动顺序不需要执行 docker compose down -v,也不需要清理数据库卷。

官方资料

资料核验日期:2026 年 11 月 19 日。示例按当前官方 Compose 文档整理,使用前应核对本机插件版本。

  1. Docker Compose:控制启动与关闭顺序
  2. Compose services:depends_on 与 healthcheck
  3. Compose:变量插值与 $$ 转义
  4. PostgreSQL:pg_isready
  5. Docker:容器重启策略
Docker与容器

Docker 容器运行正常,日志却查不到?日志驱动、输出位置与保留策略排查

2026-11-17 12:20:11

知识库

Web应用安全入门:从OWASP Top 10理解SQL注入与纵深防御

2025-9-4 10:58:53