luofuxiang/local-s3

LocalS3 Docker镜像文档

概述

LocalS3是一个允许开发者在本地开发机器上启动Amazon S3服务的工具，无需访问AWS云服务。它实现了Amazon S3的大部分常用API，包括对象版本控制、分块上传等功能，可作为Web服务运行或作为测试用的外部资源使用，方便本地开发和测试流程。更多详情可访问https://github.com/Robothy/local-s3%E3%80%82

核心功能

• 实现Amazon S3常用API，包括对象版本控制、分块上传等
• 无需依赖AWS云服务，本地即可运行
• 支持作为Web服务或测试外部资源使用
• 提供多种部署方式，包括JAR包运行和原生可执行文件（GraalVM Native Image）

使用场景

• 本地开发环境中需要S3服务时，避免依赖真实AWS环境
• 编写S3相关代码的测试用例时，作为测试资源使用
• 快速搭建本地S3服务进行功能验证和调试

使用方法

基本运行

通过Docker命令启动LocalS3容器，映射端口并挂载数据卷以持久化数据。示例命令如下（Windows系统路径示例，Linux/macOS可替换为/path/to/local-s3:/data）：

bash
docker run --name s3 -d -v C:\\local-s3:/data -p 8080:80 luofuxiang/local-s3

启动后，可通过http://localhost:8080端点执行Amazon S3操作。

客户端配置示例（Java）

使用AmazonS3Client访问LocalS3时，需配置自定义端点并启用路径样式访问（与访问真实Amazon S3不同）。Java示例代码如下：

java
AwsClientBuilder.EndpointConfiguration endpoint = new AwsClientBuilder.EndpointConfiguration("http://localhost:8080", "local");
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
    .enablePathStyleAccess()
    .withEndpointConfiguration(endpoint)
    .build();
s3.createBucket("my-bucket"); // 创建名为"my-bucket"的存储桶

此外，还提供基于testcontainers的Java实现，可通过testcontainers API运行LocalS3，具体可参考Maven仓库。

镜像标签说明

每个发布版本包含3个Docker镜像标签：latest、${version}和native-${version}。latest标签与${version}标签内容一致；native-${version}标签为基于GraalVM Native Image构建的原生可执行文件，体积更小、启动更快。

数据持久化

LocalS3将数据存储在容器内的/data路径。若需在容器删除后保留数据，需将该路径挂载到主机的卷或目录。示例命令如下：

bash
docker run --name s3 -d -v C:\\local-s3:/data -p 8080:80 luofuxiang/local-s3

IN_MEMORY模式运行（带初始数据）

LocalS3启动时可从指定卷或路径加载初始数据，之后所有修改仅在内存中生效，不会持久化到卷中。启动命令如下：

bash
docker run -d -p 8080:80 -e MODE=IN_MEMORY -v C:\\local-s3:/data luofuxiang/local-s3

环境变量配置

MODE

• 有效值：PERSISTENCE（默认）、IN_MEMORY
• 描述：PERSISTENCE模式下，所有数据存储在文件系统；IN_MEMORY模式下，数据仅存在于内存中，性能最优但容器停止后数据丢失。

bash
docker run -d -p 8080:80 -e MODE=IN_MEMORY luofuxiang/local-s3

LOCAL_S3_LOGGING_LEVEL

• 有效值：TRACE、DEBUG、INFO（默认）、WARN、ERROR
• 描述：控制LocalS3在容器内的日志级别。

bash
docker run -d -p 8080:80 -e LOCAL_S3_LOGGING_LEVEL=WARN luofuxiang/local-s3