本教程将指导你部署 MiniStack——一个免费、开源的本地 AWS 模拟器，提供 60 多种服务、多账户和地域支持，兼容 Terraform，且完全免费（MIT 许可）。

📋 准备工作

1. 系统要求

  • 操作系统：Linux、macOS 或 Windows（通过 WSL2 或 Docker Desktop）。
  • 依赖工具：
    • Docker（推荐方式，或使用 PyPI 安装）。
    • Python 3.8+（PyPI 安装方式）。
  • 资源：MiniStack 资源占用很小（~270MB 镜像，空闲时约 30MB 内存），对硬件要求较低。

2. 其他要求（可选）

  • 如果你需要使用 RDS（真实数据库容器）、ECS（运行真实 Docker 容器） 或 Lambda 容器镜像等功能，需要挂载宿主机的 Docker 套接字 (/var/run/docker.sock)。
  • 如果你需要使用 Athena 服务，推荐使用 full 镜像（包含 DuckDB 等额外依赖）。

🚀 快速安装与启动

MiniStack 提供了三种安装方式，选择最适合你的即可。

方式一：通过 PyPI 安装（最简单）

这是最轻量的方式，适合开发环境和快速测试。

1
2
3
4
5
6
7
8
# 安装
pip install ministack

# 启动服务（默认运行在 http://localhost:4566）
ministack

# 验证服务是否正常运行
curl http://localhost:4566/_ministack/health

你可以通过设置环境变量 GATEWAY_PORT=XXXX 来更改默认端口。

方式二：通过 Docker Hub 运行（推荐）

这是最干净、隔离性最好的方式，适合大多数用户。

1
2
3
4
5
6
7
8
9
10
11
# 基础镜像（~270MB）
docker run -p 4566:4566 ministackorg/ministack

# 使用真实基础设施（RDS, ECS, Lambda 容器）
docker run -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock ministackorg/ministack

# 使用完整镜像（包含 Athena/DuckDB 支持，~360MB）
docker run -p 4566:4566 ministackorg/ministack:full

# 验证服务
curl http://localhost:4566/_ministack/health

方式三：从源码构建（开发者）

适合需要修改源码或离线环境的用户。

1
2
3
4
5
6
7
8
9
# 克隆仓库
git clone https://github.com/ministackorg/ministack.git
cd ministack

# 使用 Docker Compose 启动
docker compose up -d

# 验证服务
curl http://localhost:4566/_ministack/health

🔧 使用与配置

1. 设置默认区域和账户 ID

通过环境变量在启动时设置默认值：

1
2
3
4
docker run -p 4566:4566 \
  -e MINISTACK_REGION=eu-west-1 \
  -e MINISTACK_ACCOUNT_ID=123456789012 \
  ministackorg/ministack

2. 多租户隔离（基于 Access Key）

MiniStack 支持轻量级多租户，无需额外配置。如果 AWS_ACCESS_KEY_ID 是一个 12 位数字，它将被用作 账户 ID，实现资源和 ARN 的完全隔离。

1
2
3
4
5
6
7
8
# 团队 A 使用账户 111111111111
export AWS_ACCESS_KEY_ID=111111111111
export AWS_SECRET_ACCESS_KEY=test
aws --endpoint-url=http://localhost:4566 s3 mb s3://my-bucket

# 团队 B 使用账户 222222222222（资源完全隔离）
export AWS_ACCESS_KEY_ID=222222222222
aws --endpoint-url=http://localhost:4566 s3 ls

非数字的 Access Key（如 test）会回退到默认账户 000000000000。

3. 使用 AWS CLI 连接

1
2
3
4
5
6
7
8
9
10
# 方式 A：使用环境变量
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1
aws --endpoint-url=http://localhost:4566 s3 mb s3://my-bucket

# 方式 B：使用命名 Profile
aws configure --profile ministack
# 输入 Access Key: test, Secret: test, Region: us-east-1
aws --profile ministack --endpoint-url=http://localhost:4566 dynamodb list-tables

4. 使用 Python (boto3) 连接

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import boto3

def client(service):
    return boto3.client(
        service,
        endpoint_url="http://localhost:4566",
        aws_access_key_id="test",
        aws_secret_access_key="test",
        region_name="us-east-1",
    )

# 使用 S3
s3 = client("s3")
s3.create_bucket(Bucket="my-bucket")
s3.put_object(Bucket="my-bucket", Key="hello.txt", Body=b"Hello MiniStack!")

# 使用 DynamoDB
ddb = client("dynamodb")
ddb.create_table(
    TableName="Users",
    KeySchema=[{"AttributeName": "userId", "KeyType": "HASH"}],
    AttributeDefinitions=[{"AttributeName": "userId", "AttributeType": "S"}],
    BillingMode="PAY_PER_REQUEST",
)

5. 与 Terraform 集成

在 Terraform 配置中设置 access_key 为 12 位数字即可实现账户隔离：

1
2
3
4
5
6
7
8
9
provider "aws" {
  access_key = "048408301323"  # 12 位数字作为 Account ID
  secret_key = "test"
  region     = "us-east-1"
  endpoints {
    s3  = "http://localhost:4566"
    sqs = "http://localhost:4566"
  }
}

⚙️ 高级功能与运维

1. 内部 API（测试与重置）

MiniStack 提供内部端点，方便测试自动化：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 健康检查
curl http://localhost:4566/_ministack/health

# 重置所有状态（清空所有服务数据）
curl -X POST http://localhost:4566/_ministack/reset

# 重置并重新执行初始化脚本
curl -X POST http://localhost:4566/_ministack/reset?init=1

# 动态修改服务配置（无需重启）
curl -X POST http://localhost:4566/_ministack/config \
  -H "Content-Type: application/json" \
  -d '{"lambda_svc.LAMBDA_EXECUTOR": "docker"}'

# 查看 SES 发送的邮件
curl http://localhost:4566/_ministack/ses/messages

# 查看 SQS 队列中的消息
curl "http://localhost:4566/_ministack/sqs/messages?account=000000000000&QueueUrl=http://localhost:4566/000000000000/my-queue"

2. 启用状态持久化

默认情况下，MiniStack 的数据存储在内存中，重启后丢失。若要持久化 S3 数据，可以设置环境变量：

1
docker run -p 4566:4566 -e S3_PERSIST=1 ministackorg/ministack

这会将 S3 数据持久化到容器内的文件系统。对于其他服务（如 DynamoDB），持久化支持正在逐步添加中。

3. 使用真实基础设施（RDS、ECS、Lambda 容器）

要启用这些需要 Docker 的功能，启动时需挂载 Docker 套接字：

1
docker run -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock ministackorg/ministack
  • RDS：CreateDBInstance 会启动一个真实的 Postgres/MySQL 容器，并返回可连接的 host:port。
  • ECS：RunTask 会启动真实的 Docker 容器。
  • Lambda：当 LAMBDA_EXECUTOR=docker 时，provided.al2023 等运行时会在 Docker 中执行。

4. 数据持久化与升级

如果你使用 PERSIST_STATE=1 持久化状态，升级到新版本时，状态文件会自动迁移（磁盘格式 v2 带版本戳）。降级到旧版本时，新格式的文件会被拒绝，避免解析错误。

❓ 常见问题排查

  • 端口冲突：MiniStack 默认使用 4566 端口。如果被占用，可以通过设置 GATEWAY_PORT 环境变量（PyPI）或修改 Docker 映射端口（-p XXXX:4566）来更改。
  • 无法创建 RDS/ECS 资源：请检查是否在启动时挂载了 Docker 套接字 (-v /var/run/docker.sock:/var/run/docker.sock)。如果未挂载，这些服务会返回模拟的控制面数据，但不会创建真实容器。
  • S3 操作报错：确保在使用 AWS CLI 或 SDK 时，为 S3 操作指定了正确的区域（如 --region us-east-1），因为 S3 在某些版本中可能已实现多区域隔离。
  • Athena 查询失败：Athena 需要 full 镜像（ministackorg/ministack:full）中的 DuckDB 引擎。如果使用基础镜像，Athena 的 StartQueryExecution 会返回错误，提醒使用完整镜像。
  • IAM 权限不足：MiniStack 的 IAM 实现支持策略评估。如果收到 AccessDenied，请检查你的 IAM 角色/用户策略是否正确。

通过以上步骤，你可以在几分钟内拥有一个功能完备的本地 AWS 环境。它特别适用于开发测试、CI/CD 管道、Terraform 验证和云原生应用的离线开发，能显著降低成本并提高迭代速度。