Docker-Compose首次启动时.NET5 Web API无法连接MySQL容器的问题排查与解决方案咨询

这个问题我之前处理过好几次，核心原因很明确：你配置的depends_on: [userdb]只会让Docker等待MySQL容器启动完成，但不会等待MySQL服务真正就绪（比如数据库初始化完成、可以接受外部连接）。当你的.NET API容器启动时，MySQL可能还在执行初始化脚本或者加载服务，这时候自然会抛出连接失败的错误；而你手动重启API时，MySQL已经完成准备，所以连接就能正常建立了。

下面给你几个可行的解决方案，按推荐程度排序：

方案1：使用Docker健康检查（最推荐） #

通过给MySQL服务添加健康检查，让Docker确保MySQL服务真正就绪后，再启动API容器。

修改你的docker-compose.override.yml中的userdb配置，添加健康检查规则：

userdb:
  container_name: userdb
  restart: always
  environment:
    - MYSQL_ROOT_PASSWORD=root
    - MYSQL_DATABASE=user
  ports:
    - "3306:3306"
  volumes:
    - mysql_data:/var/lib/mysql
  # 新增健康检查：定期ping MySQL服务，确认可用
  healthcheck:
    test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-proot"]
    interval: 5s  # 每5秒检查一次
    timeout: 5s   # 超时时间5秒
    retries: 5    # 最多重试5次，失败则标记为不健康

然后修改usermanagement.api的depends_on配置，指定等待MySQL的健康状态：

usermanagement.api:
  environment:
    - ASPNETCORE_ENVIRONMENT=Development
    - "ConnectionStrings:DefaultConnection=server=userdb;port=3306;database=user;userid=root;pwd=root;"
  depends_on:
    userdb:
      condition: service_healthy  # 只有当MySQL健康检查通过时，才启动API
  ports:
    - "8001:80"

这样配置后，Docker会自动循环检查MySQL服务，直到它能正常响应ping请求，才会启动你的API容器，从根源上避免了启动顺序导致的连接问题。

方案2：给API添加启动等待脚本 #

如果不想用健康检查，可以在API的Docker镜像中加入一个启动脚本，让它先等待MySQL可用，再启动.NET应用。

1. 在你的API项目目录（比如Services/User/User.API/）下创建一个start.sh脚本（注意保存为LF换行格式，避免Windows换行导致的脚本错误）：

#!/bin/bash
# 循环检查MySQL是否能正常连接
until mysqladmin ping -h "userdb" -u "root" -p"root" --silent; do
  echo "等待MySQL服务启动中..."
  sleep 2
done

# 确认MySQL就绪后，启动.NET API
exec dotnet User.API.dll

2. 修改API的Dockerfile，把这个脚本加进去并设置为启动命令：

# 替换原有的ENTRYPOINT配置
COPY start.sh /app/start.sh
RUN chmod +x /app/start.sh
ENTRYPOINT ["/app/start.sh"]

这样API容器启动后会先持续检查MySQL状态，直到能连通再启动应用，避免了过早启动导致的连接失败。

方案3：使用第三方等待工具 #

可以借助专门的工具来等待服务就绪，比如wait-for-it或者dockerize，这里以wait-for-it为例：

1. 在API的Dockerfile中下载并添加wait-for-it.sh工具：

RUN curl -o /app/wait-for-it.sh https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh
RUN chmod +x /app/wait-for-it.sh

2. 修改ENTRYPOINT命令，让工具先等待MySQL端口开放，再启动API：

ENTRYPOINT ["/app/wait-for-it.sh", "userdb:3306", "--", "dotnet", "User.API.dll"]

这个工具会监听userdb:3306端口，直到端口开放后才执行后面的.NET启动命令，效果和脚本类似，但封装得更完善。

额外验证小提示 #

• 你的连接字符串是正确的：server=userdb;port=3306;database=user;userid=root;pwd=root;，因为Docker Compose会自动为服务名创建DNS解析，userdb可以直接指向MySQL容器。
• 如果还是有问题，可以用docker logs userdb查看MySQL容器的日志，确认数据库user是否成功初始化，有没有其他启动错误。

内容的提问来源于stack exchange，提问作者Amit Singh Rawat