DynoTable
进阶阅读约 3 分钟

如何连接到 DynamoDB Local 和 LocalStack

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

DynamoDB Local 与 LocalStack：你要连接的是什么

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

所以连接时唯一的实际差别就是端点 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。

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 上手动整理 JSON。当你加载测试数据时， DynamoDB-JSON 转换器能把普通 JSON 转成 线缆格式，而 Query vs Scan 讲解该用哪种读取 方式。对于 LocalStack DynamoDB 查看器，套路相同——只是端口换成 4566。

DynoTable 是纯本地桌面软件，所以把它指向 localhost 能让 你的测试数据留在你的机器上。要更全面地了解 GUI 格局，参见 DynamoDB GUI 对比。

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

  • 连接被拒绝。 端口错了——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 建议 本地使用看起来有效的键/区域值，这样在迁移时你只需更换端点。要在交付前对该 schema 建模， 单表设计和 GSI vs LSI 涵盖了在本地和生产之间不会改变的 那些决策。

常见问题

我需要真实的 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 以 JAR 和 Docker 镜像的形式免费分发 DynamoDB Local—— "没有预置吞吐量、数据存储或数据传输成本"；它 仅供开发和测试使用， 不用于生产。

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

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

更新于