
执行 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 文档整理,使用前应核对本机插件版本。




