igeshosk/localstack

LocalStack - 功能齐全的本地AWS云栈

!LocalStack

镜像概述和主要用途

LocalStack提供了一个易于使用的测试/模拟框架，用于开发云应用程序。目前主要专注于支持AWS云栈，可在本地机器上启动多种核心AWS服务的模拟实例，方便开发人员在无需连接真实AWS环境的情况下进行应用开发、测试和调试。本镜像为原atlassian/localstack的分支版本，修复了SNS发布功能相关的问题。

核心功能和特性

支持的AWS服务

LocalStack在本地机器上启动以下核心云服务API：

** API Gateway：http://localhost:4567

• Kinesis：http://localhost:4568
• DynamoDB：http://localhost:4569
• DynamoDB Streams：http://localhost:4570
• Elasticsearch：http://localhost:4571
• S3：http://localhost:4572
• Firehose：http://localhost:4573
• Lambda：http://localhost:4574
• SNS：http://localhost:4575
• SQS：http://localhost:4576
• Redshift：http://localhost:4577
• ES (Elasticsearch Service)：http://localhost:4578
• SES：http://localhost:4579
• Route53：http://localhost:4580
• CloudFormation：http://localhost:4581
• CloudWatch：http://localhost:4582

核心特性

• 错误注入：可注入入真实云环境中常见的错误，如Kinesis或DynamoDB的"预配置吞吐量超出异常"（ProvisionedThroughputExceededException）
• 实际HTTP REST服务：所有服务通过TCP端口提供实际HTTP连接，而非进程内模拟
• 语言无关：尽管使用Python开发，但通过HTTP REST API支持任意编程语言和环境
• 隔离进程：各服务运行在独立进程，模拟真真实云环境的服务隔离特性
• 可插拔服务：各服务易于替换，可灵活选择最佳模拟工具

使用场景和适用范围

• 云应用本地开发：无需连接真实AWS环境即可开发依赖AWS服务的应用
• 集成测试：在CI/CD pipeline中进行快速、隔离的集成测试
• 功能验证：验证AWS服务交互逻辑，如SNS到SQS的消息转发、Lambda函数触发等
• 错误处理测试：测试应用对云服务错误的处理能力

系统要求

• make
• python（支持Python 2.x和3.x）
• pip（Python包管理器）
• npm（Node.js包管理器）
• java/javac（Java 8运行时环境和编译器）
• mvn（Maven构建工具）

安装和使用方法

通过pip安装

最简单的安装方式是使用pip：

bash
pip install localstack

安装后启动基础设施：

bash
localstack start

使用Docker运行

可通过Docker启动LocalStack：

bash
localstack start --docker

或使用docker-compose（需先克隆仓库）：

bash
docker-compose up

注意：在macOS上，如果$TMPDIR包含Docker无法挂载的符号链接，可能需要运行：TMPDIR=/private$TMPDIR docker-compose up

配置说明

可通过以下环境变量配置LocalStack：

通过CLI或代码访问基础设施

AWS CLI访问

可将AWS CLI指向本地基础设施：

bash
aws --endpoint-url=http://localhost:4568 kinesis list-streams
{
    "StreamNames": []
}

Python代码访问

在Python代码中使用boto3时，通过endpoint_url参数连接本地服务：

python
import boto3

kinesis = boto3.client('kinesis', endpoint_url='http://localhost:4568')
print(kinesis.list_streams())

可参考localstack.utils.aws.aws_stack获取连接本地服务的便捷方法。

与测试框架集成

与nosetests集成

在集成测试中，可在测试 setup/teardown 中启动/停止基础设施：

python
from localstack.mock import infra

def setup():
    infra.start_infra(async=True)

def teardown():
    infra.stop_infra()

def my_app_test():
    # 测试逻辑
    pass

更多示例见tests/test_integration.py。

与Java/JUnit集成

项目提供JUnit运行器，示例如下：

java
@RunWith(LocalstackTestRunner.class)
public class MyCloudAppTest {

  @Test
  public void testLocalS3API() {
    AmazonS3 s3 = new AmazonS3Client(...);
    s3.setEndpoint(LocalstackTestRunner.getEndpointS3());
    List<Bucket> buckets = s3.listBuckets();
    // 测试逻辑
  }

}

Maven依赖配置：

xml
<project ...>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>com.atlassian</groupId>
      <artifactId>localstack-utils</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
  </dependencies>

  <repositories>
    <repository>
      <id>localstack-repo</id>
      <url>https://bitbucket.org/atlassian/localstack/raw/mvn/release</url>
    </repository>
  </repositories>

</project>

故障排除

• Java SDK的CBOR协议问题：Kinesis不支持CBOR协议，需禁用。参考https://github.com/mhart/kinesalite#cbor-protocol-issues-with-the-java-sdk
• Java访问本地S3：需启用路径样式访问：

  java
  s3.setS3ClientOptions(S3ClientOptions.builder().setPathStyleAccess(true).build());
  // 或使用构建器
  AmazonS3ClientBuilder builder = AmazonS3ClientBuilder.standard();
  builder.withPathStyleAccessEnabled(true);
  

• macOS临时目录挂载问题：若$TMPDIR包含无法挂载的符号链接，运行TMPDIR=/private$TMPDIR docker-compose up

开发和测试

开发环境设置

克隆仓库后安装依赖：

bash
make install

启动开发用基础设施：

bash
make infra

运行测试

执行单元测试和集成测试：

bash
make test

Web仪表板

启动Web仪表板查看部署的AWS组件及其关系：

bash
localstack web

变更日志

• v0.6.0：以插件形式加载服务；修复服务默认端口；修复SQS->SNS和消息属性MD5；修复S3的Host头
• v0.5.5：支持所有服务端点的SSL加密（USE_SSL配置）；创建Docker基础镜像；修复DATA_DIR问题
• v0.5.4：移除Windows不兼容的硬编码/tmp/；更新CLI和文档；修复S3/SNS通知；禁用Elasticsearch压缩
• v0.5.3：添加CloudFormation对serverless/API Gateway部署的支持；修复pypi安装问题；Java环境变量传递修复
• v0.5.0：扩展DynamoDB Streams API；修复S3的keep-alive连接；修复嵌套Lambda执行死锁；添加SNS->Lambda集成；CloudFormation serverless示例；用DynamoDBLocal替换dynalite；支持远程Docker容器中执行Lambda；修复Lambda调用错误的CloudWatch指标
• ...（更多历史版本变更略）

贡献

欢迎反馈、错误报告和拉取请求！提交拉取请求请遵循以下准则：

• 为新功能和错误修复添加测试，理想情况下每个PR应提高测试覆盖率
• 遵循现有代码风格（如缩进），Makefile包含PEP8代码检查目标
• 代码中添加合理数量的注释
• 将不相关的更改拆分为多个拉取请求

许可

LocalStack采用Apache License 2.0许可（见LICENSE.txt）。

构建于多个第三方软件工具之上，相关许可信息如下：