如何连接到 DynamoDB Local 和 LocalStack

你已经有一个本地 DynamoDB 在运行，代码也能正常与它通信 —— 但你想 看到 这些表，而不是每次都写一个 scan 脚本。把客户端连接到 本地端点只需两处改动：指向正确的 URL，并给它一次性的 凭证。下面的细节正是人们卡壳的地方 —— 区域命名空间、 字母数字键规则，以及 8000 与 4566 的端口区分。

DynamoDB Local 与 LocalStack：你在连接什么

两者都在 localhost 上给你一个无需 AWS 账户的 DynamoDB API，但它们是 不同的东西：

• DynamoDB Local 是可下载的、运行在单个进程中的 DynamoDB 引擎 —— AWS 以 一个 JAR 和一个 Docker 镜像的形式发布它 （amazon/dynamodb-local）。它就是 DynamoDB， 别无其他。默认端口 8000 （AWS 文档）。参见 用 Docker 运行 DynamoDB Local。
• LocalStack 在一个端点后面模拟一整套 AWS 服务。它的 DynamoDB 本身也是 由 DynamoDB Local 驱动的， 但一切都通过 LocalStack 的单一 边缘端口 4566 进行。

因此在连接上唯一实际的区别就是端点 URL：独立的 DynamoDB Local 用 :8000， 经由 LocalStack 的 DynamoDB 用 :4566。其余的一切 —— API、凭证技巧、GUI 配置 —— 都完全相同。

让所有人踩坑的端点 + 虚拟凭证设置

AWS SDK 和 CLI 即使在与本地端点通信时也要求提供访问密钥和区域 —— 但那些值 不必是真实的。AWS 自己的文档说 这些值“在本地运行时不必是有效的 AWS 值” （AWS 文档）。

有两个不太显眼的坑：

• 区域/访问密钥会悄悄地为你的数据划分命名空间。 若不加 -sharedDb 标志，DynamoDB Local 会为每个访问密钥 ID + 区域组合 写入一个单独的 myaccesskeyid_region.db 文件 —— AWS 的确切命名规则。 用与应用不同的密钥或区域连接，你的表看起来就像 消失了；其实它们只是在另一个文件里。用 -sharedDb 运行（所有客户端共用一个 shared-local-instance.db），或匹配应用所用的确切密钥 + 区域。
• 访问密钥 ID 必须是字母数字 —— 在 DynamoDB Local 上不能有符号。 AWS 文档 说明 AWS_ACCESS_KEY_ID 只能包含 A–Z、a–z 和 0–9；AWS 在 DynamoDB Local 2.0.0（以及 1.23.0+）中引入了这一点，因此一个在 更早镜像上可用的含特殊字符的密钥现在会失败 （AWS re:Post）。 参见下面的错误。

对于 LocalStack，安全的默认值是 test / test：它 完全忽略密钥 且从不校验其值。看起来真实的 AKIA…/ASIA… 密钥会 作为一种保护措施被拒绝，并回退到虚拟账户 000000000000 —— 与像 test 这样任意密钥解析到的是同一个账户。坚持用 test。

用 AWS CLI 连接（健全性检查）

在把 GUI 指向它之前，先从 CLI 确认端点是活的。CLI 没有内置的默认本地端点， 因此要么每条命令传入 --endpoint-url，要么设置 AWS_ENDPOINT_URL_DYNAMODB=http://localhost:8000（CLI v2.13+）。

DynamoDB Local：

aws dynamodb list-tables --endpoint-url http://localhost:8000

LocalStack（相同命令，不同端口）：

aws dynamodb list-tables --endpoint-url http://localhost:4566

只要你配置了任何凭证（哪怕是 ~/.aws/credentials 里或通过 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY 提供的虚拟凭证），这就会返回你的表 列表。返回空列表且无错误，意味着端点可用，但你看的是 另一个密钥/区域的命名空间 —— 参见上面的坑。

DynamoDB Local GUI：在 DynoTable 中浏览和查询本地表

一旦 CLI 可用，GUI 就需要同样的三个值：端点、区域 以及任意虚拟凭证。CLI 返回你用肉眼阅读的 DynamoDB-JSON；而 GUI 把同一份数据渲染成一个你可以排序、筛选和编辑的表。

在 DynoTable 中，添加一个连接并设置自定义端点：

• 端点： http://localhost:8000（DynamoDB Local）或 http://localhost:4566（LocalStack）
• 区域： 你的应用所用的任何值 —— 例如 us-east-1。这里它是一个标签，而非 真实的 AWS 区域，但它必须匹配，才能让你落在同一个数据命名空间里。
• 访问密钥 / 密钥： 任意值（test / test 是惯例）。在 DynamoDB Local 上， 访问密钥只能是字母数字。

从那里，你可以浏览项目、运行 Query 或 Scan，并可视化地编辑行， 而不必在 CLI 上手动 marshalling JSON。当你加载夹具时， DynamoDB-JSON 转换器会把普通 JSON 转换为 线格式，而 Query 与 Scan 讲解该选用哪种读取。 LocalStack DynamoDB 查看器的操作也一样 —— 只是端口改成 4566。

DynoTable 是仅本地的桌面软件，因此把它指向 localhost 会让 你的夹具留在你自己的机器上。想更全面地了解 GUI 选项，参见 DynamoDB GUI 对比。

常见错误（区域不匹配、端口、凭证）

• Connection refused。 端口错了 —— 8000 是 DynamoDB Local，4566 是 LocalStack。同时确认容器确实发布了端口 （docker run -p 8000:8000 amazon/dynamodb-local）。对于 LocalStack，请在 http://localhost:4566/_localstack/health 检查 服务是否已启动。
• DynamoDB Local 上出现 The Access Key ID or Security Token is Invalid。 自 2.0.0（以及 1.23.0+）镜像起，访问密钥 ID 必须是 仅字母数字。 一个在更早镜像上可用的含符号的密钥现在会失败 —— 用 字母/数字替换它（例如 test），并更新每个工具以保持一致。
• 针对 LocalStack 出现 The security token included in the request is invalid。 这几乎总是一个端点问题，而非凭证问题 —— 你的 SDK 客户端丢掉了 --endpoint-url / endpoint_url，命中了真实的 AWS 端点，而它拒绝了你的虚拟密钥。确认客户端确实指向 http://localhost:4566。
• 来自 SDK/CLI 的凭证错误。 即便是本地端点也需要存在 某些 凭证。设置 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY（或一个 虚拟配置文件），以便 SDK 的凭证链能够解析。
• http 与 https。 本地端点是纯 http。https:// 的 URL 会 在 TLS 握手时失败。

DynamoDB Local 里的数据和我真实的 AWS 表是一份数据吗？

不是 —— 本地和云端是完全独立的存储。DynamoDB Local（以及 LocalStack 的 DynamoDB）把数据保存在本地文件或内存里；它从不接触 你的 AWS 账户，而且在本地 客户端层面不支持 AWS 区域/账户。 这正是它的用途所在：它是 用于开发和测试的。 如果你之后想在云端使用相同的夹具， AWS 建议 在本地使用 看起来有效的 密钥/区域值，这样当你迁移时只需更换端点。要在 发布前对该架构建模，单表设计和 GSI 与 LSI 涵盖了那些在本地和生产之间不会改变的 决策。

本地帮你省下什么（以及生产环境仍然要收的钱）

DynamoDB Local 不计量任何东西——没有 RCU，没有 WCU，也没有传输费用。同样一次 GetItem，打到 us-east-1 按需模式的托管 DynamoDB 上，对一个 ≤ 4 KB 的项 会按最终一致读 0.5 RCU或强一致读 1 RCU 计费。当你把 --endpoint-url 换成真实端点时，每一次浏览和查询都会重新开始计费。用 定价计算器模拟这个跳变，并用 项大小计算器度量有代表性的项。

常见问题

我需要真实的 AWS 凭证吗？ 不需要。DynamoDB Local 和 LocalStack 都接受 虚拟值。它们只需要 存在、是字母数字（对于 DynamoDB Local）， 并在你的各个工具之间保持一致。

为什么切换工具时我的表会消失？ 若不加 -sharedDb，DynamoDB Local 会按访问密钥 + 区域把数据划分到单独的 myaccesskeyid_region.db 文件里。使用 -sharedDb，或在所有地方保持这些值一致。

端口 8000 和 4566 有什么区别？ 8000 是独立 DynamoDB Local 的默认端口；4566 是 LocalStack 的单一边缘端口，它对接其所有 被模拟的服务，包括 DynamoDB。

一个 GUI 能同时连接两者吗？ 能 —— 它们说的是同一套 DynamoDB API。只是 端点 URL 会改变（:8000 与 :4566）。

DynamoDB Local 是免费的吗？ 是。AWS 免费分发 DynamoDB Local，形式是一个 JAR 和一个 Docker 镜像 —— 它 “没有预置吞吐量、数据存储或数据传输费用”；它 仅用于开发和测试， 而非生产。

我能针对我的本地表运行 SQL 吗？ 本地 DynamoDB 说的是与 云端相同的 API，因此适用相同的访问模式规则 —— 以及相同的限制：DynamoDB 的 PartiQL SELECT 语法 只有 SELECT … FROM … WHERE … ORDER BY —— 没有 JOIN、没有 GROUP BY，也 没有分组聚合函数 如 COUNT/SUM/AVG（参见 PartiQL 与 SQL）。 DynoTable 的 SQL Workbench 可在任意连接上运行这些 分析型查询，本地连接也包括在内。

试用 DynoTable，直接连接到 localhost:8000 或 localhost:4566，用 GUI 浏览、查询和编辑你的本地表。