容器与云原生 / 系统课时
应用为什么连不上数据库
应用为什么连不上数据库
Compose 中应用连不上数据库,最常见的原因不是“Docker 网络坏了”,而是连接地址写错、数据库尚未就绪、初始化未完成或账号配置不一致。按连接链路逐层验证,可以避免在应用和数据库两端来回猜测。
学习目标
- 正确区分容器内的
localhost与 Compose 服务名 - 按 DNS、网络、监听、初始化和认证顺序定位连接失败
- 使用实际数据库客户端验证网络与账号是否同时可用
先检查连接地址
同一个 Compose 项目中的服务通常通过项目默认网络互通,并可使用服务名进行 DNS 解析。因此应用服务连接名为 db 的数据库服务时,主机地址通常应写成 db,而不是 127.0.0.1 或 localhost。
在应用容器内部,localhost 指向应用容器自身。只有数据库进程也运行在同一个容器中时,这个地址才会指向数据库。宿主机映射出的端口主要供宿主机或外部客户端访问,容器之间通常直接使用数据库容器监听的内部端口。

用最小环境验证连接链路
下面的 Compose 配置使用两个 PostgreSQL 官方镜像:db 运行数据库,client 作为数据库客户端。客户端直接通过服务名 db 和内部端口 5432 连接,不依赖宿主机端口映射。
services:
db:
image: postgres:16-alpine
environment:
POSTGRES_DB: appdb
POSTGRES_USER: appuser
POSTGRES_PASSWORD: example-password
healthcheck:
test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
interval: 2s
timeout: 2s
retries: 15
client:
image: postgres:16-alpine
depends_on:
db:
condition: service_healthy
environment:
PGPASSWORD: example-password
command:
- psql
- -h
- db
- -U
- appuser
- -d
- appdb
- -c
- SELECT 1 AS connected;该配置的生效行为是:client 等待 db 健康检查通过后,再使用与数据库初始化一致的用户、密码和数据库名发起连接。可执行以下命令验证完整链路:
docker compose up --abort-on-container-exit --exit-code-from client client预期结果中应包含查询返回的一行 1;镜像拉取和容器名称等动态日志可能不同。
connected
-----------
1
(1 row)这说明服务名解析、容器网络、PostgreSQL 监听、数据库创建和账号认证都已经通过。
按错误类型缩小范围
如果应用报“name or service not known”或类似名称解析错误,先核对数据库服务是否真的叫 db,以及两个服务是否连接到至少一个共同的 Compose 网络。手工指定网络后尤其要检查是否把两个服务拆到了互不相通的网络中。
如果能够解析地址,但收到 connection refused,说明请求已经到达目标主机附近,却没有进程在目标端口接受连接。应检查数据库容器是否仍在运行、数据库是否已经监听,以及应用使用的是容器内部端口而不是随意复制宿主机映射端口。
如果最初拒绝连接,过几秒又恢复,通常要检查启动时序。depends_on 可以控制启动顺序,但只有配合健康检查和 condition: service_healthy 时,才能让依赖服务等待数据库达到健康状态。即便如此,生产应用仍应具备合理的连接重试能力,因为运行过程中数据库也可能短暂重启。
网络通了还要检查初始化和账号
网络可达并不代表 SQL 登录一定成功。PostgreSQL、MySQL 等数据库镜像通常只在首次初始化数据目录时根据环境变量创建初始数据库和账号。之后修改 Compose 中的初始化密码,不一定会自动修改已有卷中的数据库账号。
因此出现“password authentication failed”“access denied”或“unknown database”一类错误时,要同时核对应用侧连接字符串、数据库内实际用户和数据库名,以及命名卷是否保存着旧初始化结果。不要为了测试直接删除生产数据卷;应先进入数据库确认真实账号状态,再决定修改密码、创建缺失数据库或重新初始化测试环境。
最终可以按一条固定链路判断:先确认应用连接的是数据库服务名,再确认双方共享网络和端口正确,然后验证数据库已经 ready,最后检查数据库名、用户名、密码与持久化数据中的实际状态。这样即使错误信息只显示“数据库连接失败”,也能迅速确定问题停在哪一层。