使用 LocalStack 和 Docker 開發和測試 AWS 雲端應用程式

目錄

在現代應用程式開發中，在將雲端應用程式部署到實際環境之前，先在本機進行測試，可以幫助您更快、更有信心地發佈應用程式。這種方法包括在本機模擬服務、及早發現和修復問題，以及快速迭代，而無需產生成本或面臨完整雲端環境的複雜性。像 LocalStack 之類的工具已在此過程中變得 invaluable，讓您能夠模擬 AWS 服務並將應用程式容器化，以獲得一致、隔離的測試環境。

在本指南中，您將學習如何

  • 使用 Docker 啟動 LocalStack 容器
  • 從非容器化應用程式連線到 LocalStack
  • 從容器化應用程式連線到 LocalStack

什麼是 LocalStack？

LocalStack 是一個雲端服務模擬器，可在您筆記型電腦上的單個容器中運行。它提供了一種強大、靈活且經濟高效的方式來在本機測試和開發基於 AWS 的應用程式。

為什麼要使用 LocalStack？

在本機模擬 AWS 服務，您可以測試您的應用程式如何與 S3、Lambda 和 DynamoDB 等服務互動，而無需連線到真正的 AWS 雲端。您可以快速迭代您的開發，避免在此階段部署到雲端的成本和複雜性。

透過在本機模擬這些服務的行為，LocalStack 可實現更快的回饋迴圈。您的應用程式可以與外部 API 互動，但一切都運行在本機，無需處理雲端佈建或網路延遲。

這使得驗證整合和測試基於雲端的場景變得更容易，而無需在實際環境中設定 IAM 角色或策略。您可以在本機模擬複雜的雲端架構，並僅在準備就緒時才將變更推送至 AWS。

將 LocalStack 與 Docker 搭配使用

LocalStack 的官方 Docker 映像 提供了一種在開發機器上運行 LocalStack 的便捷方式。它免費使用，不需要任何 API 金鑰即可運行。您甚至可以使用 LocalStack Docker 擴充功能 透過圖形使用者介面使用 LocalStack。

先決條件

開始學習本操作指南之前，您需要滿足以下先決條件

  • 啟動 LocalStack

    執行以下指令以啟動 LocalStack。

    $ docker compose -f compose-native.yml up -d

    此 Compose 檔案也包含必要的 Mongo 資料庫規格。 您可以透過瀏覽 Docker Desktop Dashboard 來驗證服務是否已啟動並正在執行。

    Diagram showing the LocalStack and Mongo container up and running on Docker Desktop

  • 選擇容器並檢查日誌，以驗證 LocalStack 是否已啟動並正在執行。

    Diagram showing the logs of LocalStack container

  • 建立本機 Amazon S3 儲存貯體

    當您使用 LocalStack 建立本機 S3 儲存貯體時，實際上是在模擬在 AWS 上建立 S3 儲存貯體。 這讓您無需實際的 AWS 帳戶即可測試和開發與 S3 互動的應用程式。

    要建立本機 Amazon S3 儲存貯體，您需要在系統上安裝 awscli-local 套件。 此套件提供 awslocal 指令，它是 AWS 命令列介面的精簡包裝器，可與 LocalStack 搭配使用。 它讓您可以在本機機器上針對模擬環境進行測試和開發，而無需存取真正的 AWS 服務。 您可以在這裡

    $ pip install awscli-local

    • 使用以下指令在 LocalStack 環境中建立新的 S3 儲存貯體

    $ awslocal s3 mb s3://mysamplebucket

    指令 s3 mb s3://mysamplebucket 告訴 AWS CLI 建立一個名為 mysamplebucket 的新 S3 儲存貯體 (mb 代表 make bucket)。

    您可以透過在 Docker Desktop Dashboard 上選擇 LocalStack 容器並檢視日誌來驗證 S3 儲存貯體是否已建立。 日誌表示您的 LocalStack 環境已正確設定，您現在可以使用 mysamplebucket 來儲存和擷取物件。

    Diagram showing the logs of LocalStack that highlights the S3 bucket being created successfully

    在開發中使用 LocalStack

    現在您已熟悉 LocalStack，接下來讓我們實際操作看看。 在此示範中，您將使用一個具有 React 前端和 Node.js 後端的範例應用程式。 此應用程式堆疊使用以下元件

    Diagram showing the tech stack of the sample todo-list application that includes LocalStack, frontend and backend services

    從非容器化應用程式連線到 LocalStack

    現在是時候將您的應用程式連接到 LocalStack 了。 位於 backend/ 目錄中的 index.js 檔案做為後端應用程式的主要進入點。

    程式碼與 LocalStack 的 S3 服務互動，該服務透過 S3_ENDPOINT_URL 環境變數定義的端點進行存取，通常設定為 http://localhost:4556 以進行本機開發。

    AWS SDK 中的 S3Client 設定為使用此 LocalStack 端點，以及測試憑證（AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY），這些憑證也來自環境變數。 此設定允許應用程式在本機模擬的 S3 服務上執行操作，如同與真正的 AWS S3 互動一樣，使程式碼能夠彈性地適應不同的環境。

    程式碼使用 multer 和 multer-s3 來處理檔案上傳。 當使用者透過 /upload 路由上傳影像時，檔案會直接儲存在 LocalStack 模擬的 S3 儲存貯體中。 儲存貯體名稱是從環境變數 S3_BUCKET_NAME 中擷取的。 每個上傳的檔案都會被賦予一個唯一的名稱，方法是將目前的時間戳記附加到原始檔名。 然後，路由會傳回已上傳檔案在本機 S3 服務中的 URL，使其可以像託管在真正的 AWS S3 儲存貯體中一樣進行存取。

    讓我們實際操作看看。 首先啟動 Node.js 後端服務。

    1. 切換到 backend/ 目錄

      $ cd backend/

    2. 安裝必要的依賴項

      $ npm install

    3. 設定 AWS 環境變數

      位於 backend/ 目錄中的 .env 檔案已經包含 LocalStack 用於模擬 AWS 服務的預留位置憑證和設定值。 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 是預留位置憑證，而 S3_BUCKET_NAME 和 S3_ENDPOINT_URL 是設定設定。 無需進行任何更改，因為這些值已針對 LocalStack 正確設定。

      提示

      由於您在 Docker 容器中執行 Mongo，而後端 Node 應用程式在本機主機上原生執行，請確保在您的 .env 檔案中設定 MONGODB_URI=mongodb://localhost:27017/todos。

      MONGODB_URI=mongodb://localhost:27017/todos
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
S3_BUCKET_NAME=mysamplebucket
S3_ENDPOINT_URL=http://localhost:4566
AWS_REGION=us-east-1

      雖然 AWS SDK 通常使用以 AWS_ 開頭的環境變數，但此特定應用程式會直接參考 index.js 檔案（位於 backend/ 目錄下）中的以下 S3_* 變數來設定 S3Client。

      const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT_URL, // Use the provided endpoint or fallback to defaults
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID || 'default_access_key', // Default values for development
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || 'default_secret_key',  
  },
});

    4. 啟動後端伺服器

      $ node index.js

      您將看到後端服務已在連接埠 5000 成功啟動的訊息。

    啟動前端服務

    要啟動前端服務，請開啟新的終端機並按照以下步驟操作

    1. 瀏覽至 frontend 目錄

      $ cd frontend

    2. 安裝必要的依賴項

      $ npm install

    3. 啟動前端服務

      $ npm run dev

      到目前為止，您應該會看到以下訊息

      VITE v5.4.2  ready in 110 ms
➜  Local: http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

      您現在可以透過 http://localhost:5173 來存取應用程式。現在就選擇一個影像檔案，然後點擊上傳按鈕來上傳影像。

      Diagram showing a working todo-list application

      您可以透過檢查 LocalStack 容器日誌來驗證影像是否已上傳到 S3 儲存桶。

      Diagram showing the logs of the LocalStack that highlights image uploaded to the emulated S3 bucket

      狀態碼 200 表示 putObject 操作（將物件上傳到 S3 儲存桶）已在 LocalStack 環境中成功執行。LocalStack 記錄此項目是為了提供正在執行的操作的可見性。它有助於除錯並確認您的應用程式正在與模擬的 AWS 服務正確互動。

      由於 LocalStack 的設計目的是在本地模擬 AWS 服務，因此此日誌項目顯示您的應用程式在本地沙盒環境中執行雲端操作時功能正常。

    從容器化的 Node 應用程式連線到 LocalStack

    現在您已經學會如何將非容器化的 Node.js 應用程式連接到 LocalStack，接下來將探討在容器化環境中運行完整應用程式堆疊所需的變更。為了達成此目標，您將建立一個 Compose 檔案，指定所有必要的服務：前端、後端、資料庫和 LocalStack。

    1. 檢查 Docker Compose 檔案。

      以下 Docker Compose 檔案定義了四個服務：backend、frontend、mongodb 和 localstack。backend 和 frontend 服務是您的 Node.js 應用程式，而 mongodb 提供資料庫，localstack 模擬 AWS 服務，例如 S3。

      backend 服務依賴於 localstack 和 mongodb 服務，確保它們在啟動之前正在運行。它還使用 .env 檔案來設定環境變數。前端服務依賴於後端並設定 API URL。mongodb 服務使用永久性磁碟區來儲存資料，而 localstack 設定為運行 S3 服務。此設定允許您使用類似 AWS 的服務在本地開發和測試您的應用程式。

      services:
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - 5000:5000
    depends_on:
      - localstack
      - mongodb
    env_file:
      - backend/.env

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    ports:
      - 5173:5173
    depends_on:
      - backend
    environment:
      - REACT_APP_API_URL=http://backend:5000/api

  mongodb:
    image: mongo
    container_name: mongodb
    volumes:
      - mongodbdata:/data/db
    ports:
      - 27017:27017

  localstack:
    image: localstack/localstack
    container_name: localstack
    ports:
      - 4566:4566
    environment:
      - SERVICES=s3
      - GATEWAY_LISTEN=0.0.0.0:4566
    volumes:
      - ./localstack:/docker-entrypoint-initaws.d"

volumes:
  mongodbdata:

    2. 修改 backend/ 目錄下的 .env 檔案，讓資源使用內部網路名稱進行連線。

      提示

      根據先前的 Compose 檔案，應用程式將使用主機名稱 localstack 連接到 LocalStack，而 Mongo 將使用主機名稱 mongodb 進行連線。

      MONGODB_URI=mongodb://mongodb:27017/todos
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
S3_BUCKET_NAME=mysamplebucket
S3_ENDPOINT_URL=http://localstack:4566
AWS_REGION=us-east-1

    3. 停止正在運行的服務。

      請確保您透過在終端機中按下「Ctrl+C」來停止上一步驟中的 Node 前端和後端服務。此外，您還需要在 Docker Desktop Dashboard 中選取 LocalStack 和 Mongo 容器，然後選擇「刪除」按鈕來停止它們。

    4. 在您複製的專案目錄的根目錄執行以下命令來啟動應用程式堆疊。

      $ docker compose -f compose.yml up -d --build

      應用程式很快就會啟動並運行。

    5. 手動建立一個 S3 儲存桶。

      Compose 檔案不會事先建立 AWS S3 儲存桶。請執行以下命令在 LocalStack 環境中建立一個新的儲存桶。

      $ awslocal s3 mb s3://mysamplebucket

      此命令將建立一個名為 mysamplebucket 的 S3 儲存桶。

      開啟 http://localhost:5173 來存取完整的待辦事項清單應用程式，並開始將影像上傳到 Amazon S3 儲存桶。

      提示

      為了在開發過程中最佳化效能並縮短上傳時間，請考慮上傳較小的影像檔案。較大的影像可能需要更長的時間來處理，並且可能會影響應用程式的整體回應速度。

    摘要

    本指南已引導您完成使用 LocalStack 和 Docker 設定本地開發環境的步驟。您已經學會如何在本地測試基於 AWS 的應用程式，從而降低成本並提高開發工作流程的效率。