ministack-aws-emulator

MiniStack AWS Emulator 是一个免费、MIT 许可的开源本地 AWS 模拟器，定位为 LocalStack 的直接替代品，可在单一端口上模拟 25 个以上 AWS 服务，使用时无需账号、API Key 或遥测。

用途

MiniStack 用于在本地环境中模拟 AWS 服务，便于开发、调试、单元测试以及在 CI 流水线中运行依赖 AWS 的代码。它兼容 boto3、AWS CLI、Terraform、CDK 以及任何 SDK。

主要能力

支持的服务及关键操作包括：

• S3：CRUD、分片上传、版本控制、加密、生命周期、CORS、ACL、通知
• SQS：标准队列与 FIFO 队列、死信队列、批量操作
• SNS：主题、订阅、向 SQS/Lambda 扇出、平台端点
• DynamoDB：表、CRUD、Query、Scan、TTL、事务、批量操作
• Lambda：Python 运行时、调用、SQS 事件源、Function URL
• IAM：用户、角色、策略、组、实例配置文件、OIDC
• STS：GetCallerIdentity、AssumeRole、GetSessionToken
• SecretsManager：完整 CRUD、轮换、版本控制
• SSM Parameter Store：String、SecureString、StringList、路径查询
• EventBridge：总线、规则、目标、Lambda 分发
• Kinesis：流、分片、记录、迭代器
• CloudWatch Metrics：PutMetricData、告警、仪表盘、CBOR 协议
• CloudWatch Logs：日志组/流、glob 过滤、指标过滤器
• SES：发送邮件、模板、配置集
• Step Functions：状态机 CRUD
• RDS：启动真实的 Postgres/MySQL 容器
• ElastiCache：启动真实的 Redis 容器
• Athena：通过 DuckDB 执行真实 SQL
• ECS：运行真实 Docker 容器

安装与使用方式

安装方式有三种：

1. PyPI（最简单）：pip install ministack 后运行 ministack，服务默认运行在 http://localhost:4566，可用 GATEWAY_PORT=5000 ministack 更换端口。
2. Docker Hub：docker run -p 4566:4566 nahuelnucera/ministack
3. Docker Compose（从源码）：git clone https://github.com/Nahuel990/ministack，进入目录后 docker compose up -d。

验证运行：curl http://localhost:4566/_localstack/health

配置项：GATEWAY_PORT 默认 4566（监听端口）；S3_PERSIST 默认 0，设为 1 可将 S3 数据持久化到磁盘。

使用 AWS CLI 时，设置任意非空凭证（export AWS_ACCESS_KEY_ID=test、AWS_SECRET_ACCESS_KEY=test、AWS_DEFAULT_REGION=us-east-1），并在命令中指定 --endpoint-url=http://localhost:4566，即可操作 S3、SQS、DynamoDB 等服务。也可使用命名 profile（aws configure --profile local）或源码中的 awslocal 封装脚本。

使用 boto3 时，创建客户端时传入 endpoint_url="http://localhost:4566"、aws_access_key_id="test"、aws_secret_access_key="test"、region_name="us-east-1"。boto3 >= 1.28 也支持通过环境变量 AWS_ENDPOINT_URL 自动识别，无需传 endpoint_url。

适用场景

• 本地开发：在无网络或无 AWS 账号时模拟云服务。
• 单元测试：配合 pytest fixture 创建/清理测试资源。
• CI 集成：在 GitHub Actions 中作为 service 容器启动，配合环境变量运行测试。

限制与注意事项

• 资料未提供各服务完整兼容性列表与已知差异的更多细节。
• 凭证不做校验，任意非空值即可。
• 遇到 InvalidSignatureException 通常是区域不匹配，需确保 region_name 一致。
• Lambda 创建后可能需稍等（使用热工作池执行 Python 运行时），或以 InvocationType="Event" 异步调用。
• S3 数据默认重启后丢失，需启用 S3_PERSIST=1。
• 端口冲突时可用 GATEWAY_PORT 更换。
• 从 LocalStack 迁移：端点 URL 保持 http://localhost:4566 不变，移除 LOCALSTACK_AUTH_TOKEN / LOCALSTACK_API_KEY 环境变量，将 Docker 镜像从 localstack/localstack 替换为 nahuelnucera/ministack，boto3 客户端代码无需修改。