如何連線到 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 瀏覽、查詢和編輯你的本地表。