DynoTable
入門閱讀時間 2 分鐘

如何用 Docker 執行 DynamoDB Local：完整指南

DynamoDB Local 是 AWS 提供的、可下載的 DynamoDB 單程序模擬版——相同的 API，不需要 AWS 帳戶，不需要網路，沒有按請求計費。用它來做本地開發和整合測試，然後在生產環境把同一份程式碼指向雲端。它會忽略預置吞吐量，也永遠不會限流，所以它無法替代負載測試或限額測試。

我該怎麼用 Docker 執行 DynamoDB Local？

執行 docker run -p 8000:8000 amazon/dynamodb-local 來啟動官方映象，它會把 DynamoDB 引擎暴露在 http://localhost:8000。用任意佔位憑證把你的 AWS SDK 或 CLI 指向那個端點，然後就像對著雲端一樣建立表、發請求。加上 -sharedDb 和一個掛載的 -dbPath 卷，可以讓資料在重啟之間保留。

啟動容器

docker run -p 8000:8000 amazon/dynamodb-local

這會把引擎暴露在 http://localhost:8000。

docker-compose

大多數項目會在 docker-compose.yml 裡固定它，好讓整個團隊拿到相同的端點：

services:
  dynamodb:
    image: amazon/dynamodb-local
    user: root
    command: '-jar DynamoDBLocal.jar -sharedDb -dbPath /data'
    ports:
      - '8000:8000'
    volumes:
      - dynamodb-data:/data
volumes:
  dynamodb-data:

該映象以非 root 的 dynamodblocal 使用者身份執行，它無法在 root 擁有的命名卷內開啟資料庫檔案——沒有 user: root 你就會撞上 SQLiteException [14] unable to open database file，而且每一次呼叫都會掛起。

持久化

DynamoDB Local 預設是記憶體中執行的——容器一停，每張表就消失了。兩個標誌能讓它變得持久：

  • -sharedDb 讓所有用戶端使用同一個共享資料庫檔案（沒有它，每一組憑證/區域都會得到自己獨立的資料庫——一個常見的"我的表去哪了？"驚喜）。
  • -dbPath /data 加上一個掛載的卷，會把那個檔案寫到磁碟上，於是資料能在 docker compose down 之後存活。

把 SDK 指向它

只有端點會變——憑證可以是任意佔位值：

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({
  endpoint: 'http://localhost:8000',
  region: 'local',
  credentials: {accessKeyId: 'x', secretAccessKey: 'x'}
});

建立一張表

aws dynamodb create-table \
  --endpoint-url http://localhost:8000 \
  --table-name AppData \
  --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
  --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

像這樣的單表 PK/SK 結構是一個不錯的預設選擇。當你載入測試資料時，用 DynamoDB-JSON 轉換器把普通 JSON 轉換成線路格式。

驗證容器已經啟動、表也建立成功了：

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

用圖形介面瀏覽它

CLI 呼叫很快就會變得繁瑣。常見的選項是開源的 dynamodb-admin 網頁介面，或者一個桌面用戶端。DynoTable 直接連線到 localhost:8000（或任意 LocalStack 端點——參見連線 DynamoDB Local 與 LocalStack），讓你用瀏覽、透過 查詢、編輯本地表——用的就是你操作雲端表時的同一套介面，無需 aws CLI 往返。

Local 不模仿什麼

將 Local 視為 API 相容層，而不是容量模擬器。它忽略了預配置吞吐量，永不返回 ⟦0⟧, 並且不模擬按需突發行為。針對 Local 的負載測試告訴您 AWS 中沒有關於分割區限制或自適應容量的內容。如果您沒有計劃，整合測試中還會出現其他差距：

行為DynamoDB 本地AWS DynamoDB
計費/RCU/WCU無按請求計量
節流從來沒有是的，在表/索引限制下
TTL 刪除時機盡最大努力，不受 SLA 約束AWS日程背景清掃
DynamoDB 直播簡化全流語義+Lambda接線
跨表交易在最近的版本中受支援具有記錄限制的完整 ACID
全域性表/PITR不可用生產特點

如果您的測試斷言節流、TTL 在幾秒鐘內到期或流扇出，針對一次性雲表或 LocalStack 執行至少一套套件您需要啟用的功能。

實用的本地工作流程

大多數團隊將 Local 分為三層：

  1. 單元測試 — 在 CI 中旋轉容器，在 beforeAll 中建立表，撕裂下afterAll。保持固定裝置較小；元帥平原JSON穿過 DynamoDB JSON converter 測試貼上時手動繪製屬性圖。
  2. 整合測試 — 執行您的應用程式使用的相同 SDK 用戶端工廠，僅交換 endpoint 和憑證。斷言項目形狀和有條件寫入，而不是消耗的容量（本地不返回對預算有意義ConsumedCapacity）。
  3. 手動探索 — 將 DynoTable 與本地設定檔案連線，進行階段編輯，並在部署架構更改之前執行 PartiQL 或關鍵條件查詢。當您的業務規模超出單一流程時——多個服務、S3 觸發器或 IAM 風格路由 — 升級到 LocalStack 或開發帳戶。對於“我的訪問模式是否可以編譯？”，本地保持最快的迴圈。

無需手動編組的種子資料

當您不標記每個項目時，從 JSON 檔案載入十個夾具項目會更快珍視自己。將陣列貼上到 DynamoDB JSON converter，複製整理好的輸出，並使用 BatchWriteItem 針對 --endpoint-url 進行批次寫入 http://localhost:8000。對於更新頻繁的固定裝置，組裝 UpdateExpression 在 DynamoDB expression builder 並貼上生成的屬性對映到您的測試工具中。

DynoTable 的項目編輯器在提交時執行相同的編組 — 當測試失敗讓您只能盯著 CLI 中的原始 {"S":...} blob。

何時離開當地

當您需要在 AWS 本身上測量以下任何一項時，請運送到真實的桌子：

  • 容量規劃 — 每秒查詢 1,000 次的 1 KB 項會消耗按需計費每秒大約 250 個最終一致的 RCU；本地報告為零。模型與 pricing calculator 使用以下尺寸 item-size calculator。
  • 索引傳播滯後 — GSI 讀取最終在生產中保持一致；本地返回索引行的速度足夠快，陳舊讀取的錯誤會隱藏起來，直到部署為止。
  • 跨帳戶 IAM — 資源範圍的角色和條件鍵僅存在於雲。保持本地化以快速反饋模式和運算式語法；驗證成本和在生產流量之前針對臨時表的一致性假設。

值得編寫指令碼繞過的陷阱

  • 忘記 -sharedDb — 每個唯一的憑證對都有一個隔離的資料庫； CI 和你的膝上型電腦看起來像是不同的宇宙。
  • 根擁有的卷沒有 user: root — SQLite 後端靜默失敗直到您新增上面部分中的撰寫覆蓋。
  • 假設 Streams 奇偶校驗 — 支援流的 Lambda 需要雲或 LocalStack 目標；僅本地不會執行扇出。
  • 空字串鍵 — 自 2020 年起允許在非鍵屬性上使用，但仍被拒絕在按鍵上；以與AWS中相同的方式驗證燈具。

Download DynoTable，新增指向http://localhost:8000的設定檔案，並瀏覽您剛剛建立的表格 - 相同的網格、過濾器生成器和 SQL 您在生產中使用 Workbench，迴圈上的 AWS 支出為零。

已更新