本文深入解析 Docker Compose 中 Vaadin 应用无法连接 MariaDB 的典型问题，指出 depends_on 仅检测容器启动而非服务就绪，并提供基于健康检查（healthcheck）与重试机制的生产级修复方案。
本文深入解析 docker compose 中 vaadin 应用无法连接 mariadb 的典型问题，指出 `depends_on` 仅检测容器启动而非服务就绪，并提供基于健康检查（healthcheck）与重试机制的生产级修复方案。
在使用 Docker Compose 编排多服务应用（如 Vaadin 前端 + MariaDB 后端）时，一个高频却易被误解的问题是：容器能正常启动，但应用启动即崩溃，报错 Connection refused 或 Communications link failure。你提供的日志明确显示：
Caused by: java.net.ConnectException: Connection refused ... spring.datasource.url=jdbc:mysql://mariadb:3306/Test
这看似是网络不通，实则本质是服务就绪性（readiness）问题——Docker Compose 的 depends_on 仅确保 mariadb 容器进程已启动（created → running），但 MariaDB 进程从启动到完成初始化、监听 3306 端口、接受连接，通常需要数秒甚至十几秒。而 Vaadin 应用在 Spring Boot 启动初期（DataSource 初始化阶段）就立即尝试连接数据库，此时 MariaDB 尚未就绪，连接被拒绝。
✅ 关键事实澄清：
- Docker Compose 默认为同一
docker-compose.yml文件中的所有服务创建一个隐式自定义桥接网络（如myproject_default），服务名（mariadb）可直接作为 DNS 主机名被解析，网络层面完全通畅； -
depends_on在 Compose v3+ 中不保证依赖服务“已就绪”，它只做容器状态检查（service started），而非应用层健康检查（port listening & accepting connections）； - 使用
docker network inspect可验证：两个容器确实在同一网络中，且vaadin-app能ping mariadb（ICMP 可通），但telnet mariadb 3306或mysql -h mariadb -P 3306 -u test2 -ptest2 Test会失败——直到 MariaDB 完全启动。
✅ 正确解决方案：健康检查 + 启动等待
1. 为 MariaDB 添加 healthcheck
在 docker-compose.yml 中为 mariadb 服务显式定义健康检查，使其状态真正反映数据库服务能力：
version: "3.8"
services:
vaadin-app:
build:
context: .
container_name: vaadin-app
ports:
- "8080:8080"
# 使用 healthcheck 依赖（推荐 Compose v2.23+）
depends_on:
mariadb:
condition: service_healthy # ← 关键：等待 mariadb 健康
# （可选）添加启动重试逻辑（见下文）
mariadb:
image: "mariadb:10.5.8"
container_name: mariadb
environment:
MYSQL_ROOT_PASSWORD: test
MYSQL_DATABASE: Test
MYSQL_USER: test2
MYSQL_PASSWORD: test2
volumes:
- data:/var/lib/mysql
ports:
- "3306:3306"
# ← 健康检查：每 30 秒执行一次，超时 20 秒，连续 3 次成功才标记 healthy
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-ptest"]
timeout: 20s
retries: 3
interval: 30s
start_period: 40s # 给 MariaDB 充足初始启动时间（重要！）
volumes:
data:? 说明：
start_period: 40s是关键配置，避免健康检查在 MariaDB 还未完成初始化时过早失败；test命令使用mysqladmin ping（需 root 权限），比单纯nc -z localhost 3306更可靠（后者仅检测端口开放，不验证 MySQL 协议就绪）。
2. （增强鲁棒性）在 Vaadin 应用中加入连接重试
即使 Compose 层做了健康检查，Spring Boot 应用仍建议启用数据库连接重试，避免因瞬时抖动失败。在 application.properties 中追加：
# 启用连接池自动重试（HikariCP 默认支持） spring.datasource.hikari.connection-timeout=30000 spring.datasource.hikari.validation-timeout=3000 spring.datasource.hikari.idle-timeout=600000 spring.datasource.hikari.max-lifetime=1800000 # Spring Boot 2.3+ 推荐：延迟初始化 DataSource，配合健康检查更安全 spring.sql.init.defer-initialization=true
? 进阶提示：若使用 Spring Boot 3.x，还可结合
@ConditionalOnProperty或自定义ApplicationRunner实现更精细的连接等待逻辑。
3. 验证与调试技巧
- 查看健康状态：
docker-compose ps——STATUS列将显示healthy或unhealthy； - 实时观察日志：
docker-compose logs -f mariadb，确认输出MySQL init process done. Ready for start up.； - 手动测试连通性：
# 进入 vaadin-app 容器测试 docker-compose exec vaadin-app sh -c "apk add --no-cache mysql-client && mysql -h mariadb -P 3306 -u test2 -ptest2 Test -e 'SELECT 1;'"
⚠️ 注意事项与常见误区
- ❌ 不要依赖
sleep 10或wait-for-it.sh等硬编码延时脚本——不可靠且难以维护； - ❌ 不要移除
healthcheck而仅靠restart: on-failure——这会导致应用反复崩溃重启，掩盖根本问题； - ✅ 始终为数据库服务设置
start_period，尤其对 MariaDB/PostgreSQL 等初始化耗时的服务； - ✅ 若项目升级至 Docker Compose V2.23+，优先使用
condition: service_healthy；旧版本可配合wait-for-it.sh作为临时替代（但非首选）。
通过以上配置，Vaadin 应用将严格等待 MariaDB 进入 healthy 状态后才开始启动流程，彻底规避 ECONNREFUSED 错误。这不仅是解决当前问题的方法，更是构建高可用、可观测容器化微服务的基础设施实践标准。
