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 上手動 marshal 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（或一個 假的 Profile），讓 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 瀏覽、查詢與編輯你的本機資料表。

已更新