localstack-state

状态管理

保存、加载和管理 LocalStack 状态，以便在可复现的开发环境中使用状态快照；使用 lstk snapshot 及其别名 lstk save / lstk load。

功能

• 将状态保存为本地快照文件并从中恢复
• 将状态保存到 Cloud Pods（LocalStack 平台存储），并从中加载
• 将状态保存到自己的 S3 存储桶，并从中加载
• 通过 Cloud Pods 在团队间共享状态
• 每次模拟器启动时自动加载快照
• 在容器重启后保留状态

前提条件

• 已安装并完成身份验证的 lstk（使用 lstk login，或在 CI 中设置 LOCALSTACK_AUTH_TOKEN）——参见 localstack 技能
• 正在运行的模拟器，用于执行 save（如有需要，lstk load 会为你启动模拟器）

lstk save / lstk load 用统一的快照接口取代旧版 localstack state export/import 和 localstack pod save/load 命令。目标 REF 决定状态的保存位置。

快照引用（REF）

REF 形式	目标位置
(省略)	自动命名的本地文件 ./snapshot-<timestamp>-<hex>.snapshot
./my-snapshot.snapshot	指定的本地路径
pod:my-baseline	LocalStack 平台上的 Cloud Pod
pod:my-baseline:3	该 Cloud Pod 的第 3 版
my-pod s3://my-bucket/prefix	你自己的 S3 存储桶

本地快照

保存

# Save to an auto-named file in the current directory
lstk save

# Save to a specific path (the .snapshot extension is added if omitted)
lstk save ./my-snapshot.snapshot
lstk save /tmp/my-state

# Limit the snapshot to a subset of services
lstk save --services s3,lambda

加载

# Loads ./my-baseline or ./my-baseline.snapshot
lstk load my-baseline

# Load from an explicit path
lstk load ./checkpoint.snapshot

本地快照的使用场景

• 备份/恢复：在执行破坏性操作前保存状态
• CI/CD 管道：将快照文件提交到版本控制，以便进行可复现的测试
• 离线工作流：无需连接云端即可使用快照文件
• 快速快照：开发过程中快速进行本地保存/恢复

Cloud Pods

Cloud Pods 在 LocalStack 平台上存储状态，支持团队协作和远程状态管理。使用它们需要身份验证（lstk login 或 LOCALSTACK_AUTH_TOKEN）。

保存到 Cloud Pod

lstk save pod:my-baseline

# Only part of the state
lstk save pod:my-baseline --services s3,lambda

保存到已有 Pod 名称时，每次都会创建一个新版本。

从 Cloud Pod 加载

lstk load pod:my-baseline

# A specific version
lstk load pod:my-baseline:3

# Preview the changes without applying them (Cloud Pod refs only)
lstk load pod:my-baseline --dry-run

列出、检查和移除

# Your Cloud Pods
lstk snapshot list

# Everything in your organisation
lstk snapshot list --all

# Metadata: created date, size, LocalStack version, per-service resource counts
lstk snapshot show pod:my-baseline
lstk snapshot show pod:my-baseline:3

# Version history
lstk snapshot versions pod:my-baseline

# Delete (cloud snapshots only, cannot be undone)
lstk snapshot remove pod:my-baseline
lstk snapshot remove pod:my-baseline --force

Cloud Pods 的使用场景

• 团队协作：在团队成员间共享一致的开发环境
• 演示环境：准备并分享适合演示的状态
• 跨机器开发：从不同机器访问同一状态

基于 S3 的快照

将快照存储在你自己的存储桶中。凭证从 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY、--profile，或 AWS_PROFILE 指定的配置文件中读取——切勿将凭证写入 URL。

lstk save my-pod s3://my-bucket/prefix
lstk save my-pod s3://my-bucket/prefix --profile my-aws-profile

lstk load my-pod s3://my-bucket/prefix

lstk snapshot list s3://my-bucket/prefix

合并策略

lstk load 控制快照状态与模拟器中已有状态的合并方式：

策略	行为
account-region-merge (默认)	对于重叠的（服务、账户、区域），以快照为准
overwrite	清除运行中的状态，然后加载
service-merge	对每项资源以快照为准；合并不重叠的资源

lstk load pod:my-baseline --merge=overwrite

也可以设置 LSTK_MERGE_STRATEGY 来替代传递该标志。

启动时自动加载快照

对于 AWS 模拟器，在容器块中设置 snapshot 字段，以便每次启动时加载快照：

[[containers]]
type     = "aws"
snapshot = "pod:my-baseline"

对单次运行进行覆盖或跳过：

lstk start --snapshot pod:other-baseline
lstk start --no-snapshot

本地持久化

如需在重启后自动持久化状态，而无需显式保存/加载：

lstk start --persist
lstk restart --persist

--persist 会注入 LOCALSTACK_PERSISTENCE=1，并将状态写入挂载卷，该状态会在下次启动时重新加载。使用 lstk volume path 查找该目录；使用 lstk volume clear 清除该目录。

也可以在 config.toml 的 [env.*] 配置文件中设置 PERSISTENCE = "1"，使其成为每次运行的默认设置。

清除状态

# Discard in-memory resources, keep the emulator running
lstk reset

# Wipe the on-disk volume (stop the emulator first)
lstk volume clear

对比

功能	本地快照文件	Cloud Pods（pod:）	你的 S3 存储桶（s3://）
存储位置	本地文件	LocalStack 平台	你的 AWS 账户
额外身份验证	除 lstk 外无需额外验证	LocalStack 身份验证令牌	AWS 凭证
团队共享	手动共享文件	内置	通过存储桶权限
版本管理	手动	内置（snapshot versions）	手动
离线使用	是	否	否

请注意，无论使用哪种快照后端，lstk 本身始终需要 LocalStack 账户和许可证。

最佳实践

• 使用本地快照文件保存开发检查点并用于 CI/CD 流水线
• 使用 Cloud Pods 进行团队协作并共享环境
• 使用能说明状态内容的描述性名称
• 如果只关注堆栈的一部分，请使用 --services 以减小快照体积
• 将不熟悉的 Cloud Pod 加载到已填充内容的模拟器之前，先使用 --dry-run
• 使用 lstk start --persist 简单地保留重启后的状态