Docker容器间连接失败：Node应用无法连接MySQL容器

可能的原因及解决方法 #

1. MySQL 8.0 认证插件兼容性问题 #

MySQL 8.0 默认使用 caching_sha2_password 认证插件，部分版本的 mysql2 客户端连接时需显式指定兼容的认证方式。

解决方法：
在创建连接池时添加 authPlugin 配置：

pool = mysql.createPool({
    connectionLimit: 5,
    host,
    user,
    password,
    database,
    charset: 'utf8mb4',
    authPlugin: 'mysql_native_password' // 新增该行
});

2. MySQL 容器初始化未完成（端口开放但服务未就绪） #

wait-port 仅检测端口是否开放，但MySQL容器在端口开放后，仍需几秒完成数据库初始化、权限配置等操作，此时直接连接会失败。

解决方法：

• 延长等待时间：调整 waitPort 的超时时间并增加检测频率：

  await waitPort({ 
      host, 
      port: 3306,
      timeout: 20000, // 延长至20秒
      interval: 500,  // 每500毫秒检测一次
      waitForDns: true,
  });
  

• 或者使用Docker健康检查机制，修改 docker-compose.yml：

  mysql:
    image: mysql:8.0
    volumes:
      - todo-mysql-data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: todos
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-psecret"]
      timeout: 20s
      retries: 10
  

  同时更新app服务的依赖配置，等待MySQL服务就绪：

  app:
    # 其他配置保持不变
    depends_on:
      mysql:
        condition: service_healthy
  

3. 确认MySQL用户访问权限 #

即使能登录MySQL Shell，仍需确认root用户是否允许从Node应用所在的容器网络访问。进入MySQL容器执行以下命令：

docker exec -it <mysql-container-id> mysql -uroot -psecret

然后执行SQL查询：

SELECT user, host FROM mysql.user WHERE user='root';

如果root用户的host为localhost，需修改为允许所有主机访问：

ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY 'secret';
FLUSH PRIVILEGES;

注：生产环境不建议开放全权限，仅测试环境临时使用

4. 检查环境变量传递是否正确 #

进入Node容器验证环境变量是否正确设置：

docker exec -it <node-container-id> printenv

确认MYSQL_HOST、MYSQL_USER、MYSQL_PASSWORD、MYSQL_DB的值与docker-compose.yml配置一致。

验证步骤 #

修改配置后重启容器：

docker compose down
docker compose up -d

查看Node应用日志确认连接状态：

docker compose logs app

连接成功时会输出 Connected to mysql db at host mysql。

内容的提问来源于stack exchange，提问作者Neha Soni