未使用Docker Compose时Spring Boot容器无法连接PostgreSQL容器

云原生阿岚

2026-6-18

问题：Spring Boot容器无法连接PostgreSQL容器

我正在对依赖PostgreSQL的Spring Boot应用进行容器化部署，未使用Docker Compose。启动PostgreSQL容器后，运行Spring Boot镜像时无法连接数据库，报错如下：

Caused by: org.postgresql.util.PSQLException: Connection to localhost:5432 refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections.
        at org.postgresql.core.v3.ConnectionFactoryImpl.openConnectionImpl(ConnectionFactoryImpl.java:346) ~[postgresql-42.7.3.jar!/:42.7.3]
        at org.postgresql.core.ConnectionFactory.openConnection(ConnectionFactory.java:54) ~[postgresql-42.7.3.jar!/:42.7.3]
        at org.postgresql.jdbc.PgConnection.<init>(PgConnection.java:273) ~[postgresql-42.7.3.jar!/:42.7.3]
        at org.postgresql.Driver.makeConnection(Driver.java:446) ~[postgresql-42.7.3.jar!/:42.7.3]
        at org.postgresql.Driver.connect(Driver.java:298) ~[postgresql-42.7.3.jar!/:42.7.3]
        at com.zaxxer.hikari.util.DriverDataSource.getConnection(DriverDataSource.java:137) ~[HikariCP-5.1.0.jar!/:na]
        at com.zaxxer.hikari.pool.PoolBase.newConnection(PoolBase.java:360) ~[HikariCP-5.1.0.jar!/:na]
        at com.zaxxer.hikari.pool.PoolBase.newPoolEntry(PoolBase.java:202) ~[HikariCP-5.1.0.jar!/:na]
        at com.zaxxer.hikari.pool.HikariPool.createPoolEntry(HikariPool.java:461) ~[HikariCP-5.1.0.jar!/:na]
        at com.zaxxer.hikari.pool.HikariPool.checkFailFast(HikariPool.java:550) ~[HikariCP-5.1.0.jar!/:na]
        at com.zaxxer.hikari.pool.HikariPool.<init>(HikariPool.java:98) ~[HikariCP-5.1.0.jar!/:na]
        at com.zaxxer.hikari.HikariDataSource.getConnection(HikariDataSource.java:111) ~[HikariCP-5.1.0.jar!/:na]
        at org.hibernate.engine.jdbc.connections.internal.DatasourceConnectionProviderImpl.getConnection(DatasourceConnectionProviderImpl.java:122) ~[hibernate-core-6.5.2.Final.jar!/:6.5.2.Final]
        at org.hibernate.engine.jdbc.env.internal.JdbcEnvironmentInitiator$ConnectionProviderJdbcConnectionAccess.obtainConnection(JdbcEnvironmentInitiator.java:437) ~[hibernate-core-6.5.2.Final.jar!/:6.5.2.Final]
        at org.hibernate.resource.transaction.backend.jdbc.internal.DdlTransactionIsolatorNonJtaImpl.getIsolatedConnection(DdlTransactionIsolatorNonJtaImpl.java:46) ~[hibernate-core-6.5.2.Final.jar!/:6.5.2.Final]
        ... 130 common frames omitted
Caused by: java.net.ConnectException: Connection refused
        at java.base/sun.nio.ch.Net.pollConnect(Native Method) ~[na:na]
        at java.base/sun.nio.ch.Net.pollConnectNow(Net.java:682) ~[na:na]
        at java.base/sun.nio.ch.NioSocketImpl.timedFinishConnect(NioSocketImpl.java:542) ~[na:na]
        at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:592) ~[na:na]
        at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:327) ~[na:na]
        at java.base/java.net.Socket.connect(Socket.java:751) ~[na:na]
        at org.postgresql.core.PGStream.createSocket(PGStream.java:243) ~[postgresql-42.7.3.jar!/:42.7.3]
        at org.postgresql.core.PGStream.<init>(PGStream.java:98) ~[postgresql-42.7.3.jar!/:42.7.3]
        at org.postgresql.core.v3.ConnectionFactoryImpl.tryConnect(ConnectionFactoryImpl.java:136) ~[postgresql-42.7.3.jar!/:42.7.3]
        at org.postgresql.core.v3.ConnectionFactoryImpl.openConnectionImpl(ConnectionFactoryImpl.java:262) ~[postgresql-42.7.3.jar!/:42.7.3]
        ... 144 common frames omitted

我的application.properties配置如下：

server.port=9500
spring.application.name=test_service
#database
spring.datasource.url=jdbc:postgresql://${PGHOST:localhost}:${PGPORT:5432}/${POSTGRES_DB:test-dev1}
spring.datasource.username=postgres
spring.datasource.password=${POSTGRES_PASSWORD:abcd}

#JPA Config
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

PostgreSQL容器启动命令：

docker run --network=bridge -e POSTGRES_PASSWORD=root -e POSTGRES_DB=test-dev --name postgresdb -p 5051:5432 -d postgres:16.4

Spring Boot容器启动命令：

docker run -it --name testservice -p 9100:9500 --network=bridge -e PGHOST=postgresdb -e PGPORT=5432 -e POSTGRES_DB=test-dev -e POSTGRES_PASSWORD=root test_service

我已尝试使用--network参数、更换端口及--link，但问题仍未解决。

解决方案

验证环境变量传递有效性：进入Spring Boot容器执行echo $PGHOST，确认输出为postgresdb。如果不是，检查启动命令的环境变量参数是否有误，比如拼写错误或格式问题。
等待PostgreSQL完全就绪：PostgreSQL容器启动需要初始化时间，等容器日志输出database system is ready to accept connections后，再启动Spring Boot容器。也可以在Spring Boot应用中添加数据库连接重试逻辑（比如使用HikariCP的connection-test-query和initialization-fail-timeout配置）。

使用自定义Docker网络：默认bridge网络可能存在名称解析问题，创建自定义网络替代：

# 创建自定义网络
docker network create app-network
# 启动PostgreSQL容器
docker run --network=app-network -e POSTGRES_PASSWORD=root -e POSTGRES_DB=test-dev --name postgresdb -p 5051:5432 -d postgres:16.4
# 启动Spring Boot容器
docker run -it --name testservice -p 9100:9500 --network=app-network -e PGHOST=postgresdb -e PGPORT=5432 -e POSTGRES_DB=test-dev -e POSTGRES_PASSWORD=root test_service

检查PostgreSQL网络监听配置：进入PostgreSQL容器，确认postgresql.conf中listen_addresses = '*'，且pg_hba.conf包含host all all 0.0.0.0/0 md5规则，允许外部连接。
核对数据库凭证一致性：确认PostgreSQL启动时的POSTGRES_DB=test-dev、POSTGRES_PASSWORD=root与Spring Boot容器传递的环境变量完全匹配，避免默认值覆盖（比如application.properties中默认的test-dev1和abcd）。

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