跳至主要內容

將 Mastra 部署至 AWS Lambda

使用 Docker 容器和 AWS Lambda Web Adapter，將你的 Mastra 應用程式部署至 AWS Lambda。這種方式會把 Mastra 伺服器作為容器化 Lambda 函數運行，並支援自動擴展。

資訊

本指南涵蓋如何部署 Mastra 伺服器。如果你使用伺服器 adapter 或網絡框架，請按照該框架的一般方式部署。

開始之前
開始之前 的直接連結

你需要：

注意

在 AWS Lambda 上，檔案系統是暫存的，因此任何本機資料庫檔案都會在兩次調用之間遺失。如果你透過本機檔案使用 LibSQLStore，請改為設定使用遠端、與 LibSQL 相容的資料庫（例如 Turso）。

建立 Dockerfile
建立 Dockerfile 的直接連結

在項目根目錄建立 Dockerfile：

Dockerfile
FROM node:22-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci

# Copy source and build Mastra
COPY src ./src
RUN npx mastra build

# Alpine compatibility for some native deps
RUN apk add --no-cache gcompat

# Add the Lambda Web Adapter
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.1 /lambda-adapter /opt/extensions/lambda-adapter

# Run as non-root
RUN addgroup -g 1001 -S nodejs && \
  adduser -S mastra -u 1001 && \
  chown -R mastra:nodejs /app

USER mastra

# Adapter / app configuration
ENV PORT=8080
ENV NODE_ENV=production
ENV AWS_LWA_READINESS_CHECK_PATH="/api"

# Start the Mastra server
CMD ["node", ".mastra/output/index.mjs"]
備註

此 Dockerfile 使用 npm。如果你使用 pnpm、yarn 或其他套件管理工具，請相應調整命令（例如 npm ci 不適用於 pnpm lockfile）。

建置並推送 Docker image
建置並推送 Docker image 的直接連結

  1. 為部署設定環境變數。所有 AWS 服務（ECR、Lambda）應使用同一區域，以免資源因跨區域而無法顯示：

    export PROJECT_NAME="your-mastra-app"
    export AWS_REGION="us-east-1"
    export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

  2. 建置 Docker image。停用 BuildKit，確保 image 與 Lambda 的容器 runtime 相容：

    export DOCKER_BUILDKIT=0
    docker build --platform linux/arm64 -t "$PROJECT_NAME" .
    備註

    BuildKit 的預設 image 格式可能會導致 Lambda 相容性問題。設定 DOCKER_BUILDKIT=0 會使用傳統 builder，產生 Lambda 能可靠接受的 image 格式。

  3. 建立 Amazon ECR repository，以儲存你的 Docker image：

    aws ecr create-repository --repository-name "$PROJECT_NAME" --region "$AWS_REGION"

  4. 登入 Amazon ECR：

    aws ecr get-login-password --region "$AWS_REGION" | \
      docker login --username AWS --password-stdin \
      "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com"

  5. 為 image 加上 tag，然後推送至 ECR：

    docker tag "$PROJECT_NAME":latest \
      "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest

    docker push \
      "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest

建立 Lambda 函數
建立 Lambda 函數 的直接連結

  1. 前往 AWS Lambda Console，然後按一下 建立函數。請確保所選區域與你建立 ECR repository 的區域相同。

  2. 選擇 容器 image 並設定函數：

    • 函數名稱：輸入名稱（例如 mastra-app）
    • 容器 image URI：按一下 瀏覽 image，選擇你的 ECR repository，然後選擇 latest tag
    • 架構：選擇 arm64

    按一下 建立函數，建立 Lambda 函數。

  3. 設定記憶體和逾時。前往 設定 > 一般設定，然後按一下 編輯：

    • 記憶體：512 MB（按照應用程式需要調整）
    • 逾時：1 分鐘或以上（預設的 3 秒對大多數 Mastra 應用程式而言太短）

    按一下 儲存。

  4. 加入環境變數。前往 設定 > 環境變數，然後按一下 編輯。加入 Mastra 應用程式所需的變數：

    • OPENAI_API_KEY：你的 OpenAI API 金鑰（如使用 OpenAI）
    • ANTHROPIC_API_KEY：你的 Anthropic API 金鑰（如使用 Anthropic）
    • 按需要加入其他 Provider 專用的 API 金鑰（例如透過 Turso 使用 LibSQL 時所需的 TURSO_DATABASE_URL 和 TURSO_AUTH_TOKEN）

    按一下 儲存。

  5. 啟用函數 URL，以供外部存取。前往 設定 > 函數 URL，然後按一下 建立函數 URL：

    • 驗證類型：選擇 NONE，允許公開存取
    • 在 其他設定 下，勾選 設定跨來源資源共用 (CORS)，然後設定：
      • 允許來源：*
      • 允許標頭：content-type（與 CloudFront/API Gateway 等服務配合使用時，亦需要 x-amzn-request-context）
      • 允許方法：*

    按一下 儲存。

驗證部署
驗證部署 的直接連結

  1. 從 Lambda console 複製 函數 URL，然後在瀏覽器前往 <your-function-url>/api/agents。你應會看到 Agent 的 JSON 清單。

  2. 現在你可以透過 HTTP 調用 Mastra endpoint。

    注意

    在生產環境部署中，公開 endpoint 前請先設定驗證、將 CORS 來源限制為你信任的網域、使用 AWS IAM role 安全存取其他 AWS 服務，並將敏感的環境變數儲存在 AWS Secrets Manager 或 Parameter Store。

後續步驟
後續步驟 的直接連結

本指南提供將 Mastra 部署至 AWS Lambda 的快速入門。對於生產環境工作負載，請考慮為 Lambda 函數啟用 CloudWatch 監察、設定 AWS X-Ray 以進行分散式 tracing，以及設定預佈並行以維持一致效能。

On this page