localstack

LocalStack 生命周期管理

使用当前的 LocalStack CLI lstk 管理 LocalStack 模拟器的生命周期，包括启动、停止和监控本地云环境。

功能

• 使用自定义配置启动 LocalStack
• 停止、重启和重置正在运行的 LocalStack 实例
• 检查 LocalStack 状态和运行状况
• 管理模拟器卷和持久化状态
• 对 LocalStack 平台进行身份验证

前置条件

• 已安装并运行 Docker
• LocalStack 账户（lstk 会拉取 localstack/localstack-pro 镜像，并且需要有效的许可证）
• lstk CLI：

# Homebrew (macOS/Linux)
brew install localstack/tap/lstk

# npm
npm install -g @localstack/lstk

# Verify
lstk --version

旧版 localstack CLI 已弃用，并将在未来版本中移除。建议使用 lstk。少数功能目前仍仅支持旧版 CLI，详见旧版 CLI 的替代方案。

身份验证

# Interactive browser login; stores the token in the system keyring
lstk login

# Remove stored credentials
lstk logout

在 CI 或任何非 TTY 环境中，请改为设置身份验证令牌（CI 身份验证令牌；个人 Developer Auth Token 在 CI 中无法使用）：

export LOCALSTACK_AUTH_TOKEN=<token>
lstk --non-interactive start

令牌解析顺序：系统密钥环（通过 lstk login 设置）→ LOCALSTACK_AUTH_TOKEN → 交互式浏览器登录。密钥环的优先级高于环境变量，因此如需切换，请先运行 lstk logout。

常用命令

启动 LocalStack

# Start the emulator (bare `lstk` is equivalent to `lstk start`)
lstk start

# Start and keep state across restarts
lstk start --persist

# Start with debug logging (note the LOCALSTACK_ prefix)
LOCALSTACK_DEBUG=1 lstk start

# Pick the emulator type
lstk start --type aws          # also: snowflake, azure

# Plain output for scripts/CI, with a startup deadline
lstk --non-interactive --timeout 90s start

lstk start 会在后台运行容器，并在模拟器就绪后返回——没有 -d 标志。

检查状态

# Emulator state plus the resources currently deployed in it
lstk status

# Plain-text output for scripts
lstk --non-interactive status

# Service health endpoint
curl http://localhost:4566/_localstack/health | jq

停止和重启

lstk stop
lstk restart
lstk restart --persist

重置状态

# Discard all in-memory resources; the emulator keeps running
lstk reset
lstk reset --force        # skip the confirmation prompt

查看日志

lstk logs                 # print available logs
lstk logs -f              # follow in real time
lstk logs -n 100          # last 100 lines
lstk logs -v              # unfiltered output

管理卷

lstk volume path          # print the volume directory
lstk volume clear         # wipe certificates, cached tools, persisted data
lstk volume clear --force

lstk reset 会清除内存中的状态；lstk volume clear 会清空磁盘上的卷。清空卷之前，请先停止模拟器。

配置

传递环境变量

lstk 会将以 LOCALSTACK_ 为前缀的主机环境变量传递给模拟器。之前直接传递的 LocalStack 配置变量现在都必须带上此前缀：

LOCALSTACK_DEBUG=1 lstk start
LOCALSTACK_SERVICES=s3,sqs lstk start
LOCALSTACK_ENFORCE_IAM=soft lstk start

主机上的 LOCALSTACK_AUTH_TOKEN 会被有意排除在传递范围之外，因此不会覆盖 lstk 解析出的令牌。

在 config.toml 中设置环境配置

对于每次运行都需要应用的设置，可在 config.toml 中定义命名配置，并在容器配置块中引用这些配置。配置中的键无需带 LOCALSTACK_ 前缀：

[[containers]]
type = "aws"
tag  = "latest"
port = "4566"
env  = ["debug", "ci"]

[env.debug]
DEBUG = "1"
PERSISTENCE = "1"

[env.ci]
SERVICES = "s3,sqs"
EAGER_SERVICE_LOADING = "1"

配置文件的查找顺序：./.lstk/config.toml（项目本地）→ $HOME/.config/lstk/config.toml → 操作系统默认位置。运行 lstk config path 可查看当前使用的路径。

常用配置选项

变量	说明	设置方式
DEBUG	启用调试日志	LOCALSTACK_DEBUG=1 lstk start 或 [env.*] 配置
PERSISTENCE	在重启后保留状态	lstk start --persist（推荐）或配置
SERVICES	限制启动的服务	LOCALSTACK_SERVICES=s3,sqs lstk start
GATEWAY_LISTEN	绑定地址和端口	在配置中设置 GATEWAY_LISTEN = "0.0.0.0:4566"
LOCALSTACK_AUTH_TOKEN	平台身份验证令牌	环境变量或运行 lstk login
LOCALSTACK_HOST	覆盖 lstk aws 等命令使用的端点主机	环境变量

在 config.toml 中使用 tag 固定镜像版本（例如 tag = "2026.4"），或将 image 指向内部注册表，以用于气隙环境。

旧版 CLI 的替代方案

lstk 目前尚未涵盖旧版 CLI 的所有功能。仅在需要以下功能时，才需在安装 lstk 的同时安装旧版 CLI（pip install localstack）：

• 扩展——没有 lstk extensions 命令套件；请参阅 localstack-extensions 技能
• localstack aws iam stream / summary——IAM 策略流和摘要；请参阅 localstack-iam 技能
• 高级 DNS 配置（systemd-resolved 集成）和临时云实例

lstk 会管理自己的 Docker 容器，因此不能与 Docker Compose LocalStack 配置或由旧版 localstack start 启动的容器混用。如需让 lstk 指向由你自行管理的模拟器，请使用 --endpoint-url。

故障排查

• Error: runtime not healthy：Docker 未运行。启动 Docker Desktop 或守护进程，或者为自定义套接字设置 DOCKER_HOST。
• 443 端口冲突：在环境配置文件中设置 GATEWAY_LISTEN = "0.0.0.0:4566"，这样只会绑定 4566 端口。
• CI 中的身份验证错误：在运行 lstk start 前设置 LOCALSTACK_AUTH_TOKEN；没有 TTY 的环境无法运行浏览器流程。
• 许可证过期：运行 lstk logout && lstk login。
• 未知环境变量未生效：确认它在主机上以 LOCALSTACK_ 为前缀，或已移至 [env.*] 配置文件中。
• 诊断信息：lstk 会在配置文件旁写入 lstk.log — 使用 lstk config path 查找该文件。