Docker Compose部署LocalStack与Spring Boot时遇UnknownHostException问题

问题详情 #

我用Docker Compose部署Spring Boot应用（resource-service）和LocalStack，配置看起来没问题，但上传文件到已创建的module-01桶时，抛出异常：java.net.UnknownHostException: module-1.localstack。

从resource-service容器内执行curl http://localstack:4566/_localstack/health，能得到正常的健康状态响应，说明容器间连通性没问题。

我的Docker Compose配置 #

version: '3.9'

services:
  localstack:
    container_name: "localstack"
    image: localstack/localstack
    ports:
      - "8080:8080"
      - "4566:4566"
      - "4510-4559:4510-4559"
    environment:
      DEBUG: 1
    volumes:
      - "./localstack/vol:/var/lib/localstack"
      - "./localstack/init:/etc/localstack/init"
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:4566/_localstack/health" ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    networks:
      - my_network

resource-service:
  build: ./resource-service/.
  container_name: resource-service
  depends_on:
    - localstack
  ports:
    - "8083:8083"
  environment:
    SERVER_PORT: ${RESOURCE_SERVER_PORT}
    AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
    AWS_SECRET_KEY: ${AWS_SECRET_KEY}
    AWS_ENDPOINT_URL: ${AWS_ENDPOINT_URL}
  env_file:
    - .env
  healthcheck:
    test: [ "CMD", "curl", "-f", "http://localhost:8083/actuator/health" ]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 30s
  networks:
    - my_network

networks:
  my_network:
    driver: bridge

.env配置 #

AWS_ENDPOINT_URL=http://localstack:4566

Java S3客户端配置 #

@Bean
public S3Client s3Client() {
    log.info("accessKeyId: {}, endpoint: {}", accessKeyId, endpointUrl);
    return S3Client.builder()
            .region(Region.of(region))
            .endpointOverride(URI.create(endpointUrl))
            .credentialsProvider(StaticCredentialsProvider.create(
                    AwsBasicCredentials.create(accessKeyId, secretAccessKey)))
            .build();
}

解决办法 #

这个问题的核心是AWS SDK默认使用虚拟主机样式访问S3桶（即bucket-name.localstack:4566），但在Docker网络环境下，这个自定义域名无法被解析。需要修改S3客户端配置，强制使用路径样式访问（即localstack:4566/bucket-name）。

修改S3客户端配置 #

在构建S3Client时添加serviceConfiguration，启用路径样式访问：

@Bean
public S3Client s3Client() {
    log.info("accessKeyId: {}, endpoint: {}", accessKeyId, endpointUrl);
    return S3Client.builder()
            .region(Region.of(region))
            .endpointOverride(URI.create(endpointUrl))
            .credentialsProvider(StaticCredentialsProvider.create(
                    AwsBasicCredentials.create(accessKeyId, secretAccessKey)))
            .serviceConfiguration(service -> service.pathStyleAccessEnabled(true)) // 新增该行
            .build();
}

额外检查项 #

1. 桶名一致性：异常中显示的是module-1.localstack，但你创建的桶是module-01，请核对代码中使用的桶名是否正确，避免拼写错误。
2. 启动顺序优化：Docker Compose的depends_on仅保证启动顺序，不能确保LocalStack完全就绪。建议修改resource-service的depends_on配置，等待LocalStack健康检查通过后再启动：

   depends_on:
     localstack:
       condition: service_healthy
   

3. Region一致性：在LocalStack的环境变量中添加AWS_DEFAULT_REGION，确保和Spring Boot应用配置的region一致，避免因region不匹配导致的问题。

内容的提问来源于stack exchange，提问作者გენო მუმლაძ</think_never_used_51bce0c785ca2f68081bfa7d91973934>