使用LocalStack社区版Docker镜像实现S3数据持久化问题排查

问题根源 #

1. 未启用持久化模式：LocalStack 新版本默认采用临时存储策略，必须显式设置 PERSISTENCE=1 环境变量，才会将服务元数据（包括S3桶信息）和对象数据持久化到指定目录，否则所有数据仅存于容器内的/tmp临时路径，容器重启即丢失。
2. 元数据与对象存储分离：你之前仅挂载了S3对象的存储目录/tmp/localstack-s3-storage，但未持久化S3桶的元数据（桶名、配置等），导致重启后LocalStack无法识别本地已存在的对象文件，所以list-buckets返回空。

正确配置方案 #

修改Docker Compose，添加PERSISTENCE=1并正确挂载元数据目录：

localstack-main:
  container_name: localstack-main
  image: localstack/localstack:latest
  ports:
    - "4566:4566"
    - "4510-4559:4510-4559"
  environment:
    - DEBUG=1
    - DOCKER_HOST=unix:///var/run/docker.sock
    - PERSISTENCE=1  # 启用持久化模式，关键配置
  volumes:
    - ./localstack-data:/var/lib/localstack  # 统一持久化元数据和对象数据
    - /var/run/docker.sock:/var/run/docker.sock
  networks:
    - mynetwork

配置说明 #

• PERSISTENCE=1：开启后，LocalStack会将所有服务的状态（包括S3桶元数据、对象数据）写入/var/lib/localstack，不再使用/tmp的临时存储。
• 挂载./localstack-data:/var/lib/localstack：将本地目录与容器内的持久化根目录绑定，确保容器重启后所有数据完整保留。

为什么之前的操作无效 #

• 未设置PERSISTENCE=1时，/var/lib/localstack目录不会被写入任何数据，所以你看到该目录为空，数据仅存于/tmp。
• 单独挂载/tmp/localstack-s3-storage只能保存对象文件，但桶的元数据未被持久化，重启后LocalStack无法读取到桶的信息，自然无法列出已存在的桶。

内容的提问来源于stack exchange，提问作者Dillon Brock