docker-compose指定外部网络时FastAPI容器无法连接MySQL容器如何解决

问题原因及解决方案 #

你遇到的问题核心是mysql容器未正常启动/未完成网络初始化，结合你提供的配置和输出，按优先级给出以下解决步骤：

1. 清理同名残留容器 #

你之前手动通过命令行启动过名为mysql的容器，而你的docker-compose配置中也指定了container_name: mysql，如果旧容器未被删除，docker-compose启动时会跳过mysql服务的创建，你查询到的IP为空、EndpointID为空的mysql容器就是之前的残留实例，自然无法被应用解析访问。
执行以下命令清理旧容器：

docker rm -f mysql

清理完成后重新启动服务：

docker-compose -f docker-compose.yml up -d

2. 补充服务依赖配置 #

docker-compose默认并行启动所有服务，FastAPI应用的启动速度远快于MySQL的初始化速度，MySQL还没完成网络配置、启动端口监听时，应用就已经发起连接请求，也会抛出主机不可达的错误。
修改docker-compose.yml中app服务的配置，添加depends_on字段指定启动顺序，建议同时把MySQL主机名也放入环境变量方便管理：

app:
  build: .
  image: app:1.0
  container_name: app
  ports:
    - 8000:8000
  environment:
    PASSWORD: password
    USERNAME: root
    MYSQL_HOST: mysql # 代码中直接读取该环境变量作为数据库主机地址即可
  depends_on:
    - mysql

注：depends_on仅能保证服务的启动顺序，无法保证MySQL完全初始化完成可接受连接，如果重启后仍然报错，可以在应用的数据库连接逻辑中添加3-5次的重试间隔，或者使用脚本等待MySQL端口就绪后再启动应用。

3. 验证网络连通性 #

服务启动完成后，可以通过以下命令验证网络配置是否正确：

• 分别查询两个容器的网络信息，确认都分配了正常的IP地址：

  docker inspect mysql -f "{{json .NetworkSettings.Networks }}"
  docker inspect app -f "{{json .NetworkSettings.Networks }}"
  

• 进入应用容器测试mysql域名解析是否正常：

  docker exec -it app ping mysql
  

  如果能正常ping通，说明网络配置没有问题，连接报错只需调整应用的连接重试逻辑即可。

内容的提问来源于stack exchange，提问作者Shay Barak