Docker化Spring Boot应用连接MQTT Mosquitto代理问题排查

我有一个Docker化的my-app应用，需要连接同样运行在Docker容器中的MQTT Mosquitto代理，但Java应用无法连接，报错java.net.UnknownHostException: mosquitto。

Docker Compose配置 #

mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:2.0.14
    ports:
      - 1883:1883
      - 9001:9001
    volumes:
      - "./mosquitto/Broker.conf:/mosquitto/config/mosquitto.conf"
      - "./mosquitto/Password:/mosquitto/config/mosquitto.passwd"

  my-app:
    container_name: my-app
    image: data-provider:latest
    ports:
      - 8080:8080
    depends_on:
      - mosquitto
    networks:
      - my-app-network

Mosquitto配置文件 #

listener 1883
password_file /mosquitto/config/mosquitto.passwd
allow_anonymous false

报错信息 #

Caused by: org.springframework.messaging.MessagingException: Failed to connect; nested exception is MqttException (0) - java.net.UnknownHostException: mosquitto

Java配置 #

代码中使用tcp://mosquitto:1883作为MQTT地址，本地运行嵌入式Tomcat时改为localhost:1883可正常连接。

1. 统一容器网络（核心修复） #

问题根源是mosquitto容器未加入my-app使用的自定义网络my-app-network，导致两个容器处于不同网络，无法通过服务名mosquitto解析通信。

修改Docker Compose配置，给mosquitto添加相同的网络配置，并确保网络在compose文件中定义：

version: '3.8'

# 定义自定义网络
networks:
  my-app-network:
    driver: bridge

services:
  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:2.0.14
    ports:
      - 1883:1883
      - 9001:9001
    volumes:
      - "./mosquitto/Broker.conf:/mosquitto/config/mosquitto.conf"
      - "./mosquitto/Password:/mosquitto/config/mosquitto.passwd"
    # 添加网络配置
    networks:
      - my-app-network

  my-app:
    container_name: my-app
    image: data-provider:latest
    ports:
      - 8080:8080
    depends_on:
      - mosquitto
    networks:
      - my-app-network

2. 验证Mosquitto监听配置 #

当前Mosquitto配置中的listener 1883默认会监听所有网络接口（0.0.0.0），无需修改。如果曾手动设置为localhost，则需要改为0.0.0.0，确保容器内的服务能被同一网络的其他容器访问。

3. 可选：添加健康检查避免启动时序问题 #

depends_on仅保证容器启动顺序，不保证Mosquitto服务完全就绪。添加健康检查可确保my-app在Mosquitto就绪后再启动：

# 在mosquitto服务中添加健康检查
mosquitto:
  # ... 其他配置
  healthcheck:
    test: ["CMD", "mosquitto_sub", "-h", "localhost", "-p", "1883", "-t", "healthcheck-topic", "-u", "admin", "-P", "你的密码", "-C", "1", "-W", "5"]
    interval: 10s
    timeout: 5s
    retries: 3

# 修改my-app的depends_on配置
my-app:
  # ... 其他配置
  depends_on:
    mosquitto:
      condition: service_healthy

内容的提问来源于stack exchange，提问作者Gustavo Correa