跳至主要內容

將 Mastra 部署至 AWS Lambda

使用 Docker 容器和 AWS Lambda Web Adapter，將 Mastra 應用程式部署至 AWS Lambda。此方式會將 Mastra 伺服器當成可自動擴展的容器化 Lambda 函式執行。

資訊

本指南說明如何部署 Mastra 伺服器。若你使用伺服器轉接器或 Web 框架，請依該框架平常的方式部署。

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

你需要：

警告

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 鎖定檔使用）。

建置並推送 Docker 映像檔
「建置並推送 Docker 映像檔」的直接連結

  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 映像檔。停用 BuildKit，確保映像檔與 Lambda 容器 Runtime 相容：

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

    BuildKit 的預設映像檔格式可能造成 Lambda 相容性問題。設定 DOCKER_BUILDKIT=0 會使用傳統建置器，產生 Lambda 能可靠接受的映像檔格式。

  3. 建立 Amazon ECR 儲存庫以存放 Docker 映像檔：

    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. 標記映像檔並推送至 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，按一下 Create function。請確認選取的區域與 ECR 儲存庫所在區域相同。

  2. 選取 Container image 並設定函式：

    • Function name：輸入名稱（例如 mastra-app）
    • Container image URI：按一下 Browse images、選取 ECR 儲存庫，然後選擇 latest 標籤
    • Architecture：選取 arm64

    按一下 Create function 建立 Lambda 函式。

  3. 設定記憶體與逾時。前往 Configuration > General configuration，按一下 Edit：

    • Memory：512 MB（依應用程式需求調整）
    • Timeout：1 分鐘以上（預設 3 秒對大多數 Mastra 應用程式而言太短）

    按一下 Save。

  4. 加入環境變數。前往 Configuration > Environment variables，按一下 Edit。加入 Mastra 應用程式所需的變數：

    • OPENAI_API_KEY：OpenAI API 金鑰（若使用 OpenAI）
    • ANTHROPIC_API_KEY：Anthropic API 金鑰（若使用 Anthropic）
    • 視需要加入其他 Provider 專用 API 金鑰（例如搭配 Turso 使用 LibSQL 時的 TURSO_DATABASE_URL 和 TURSO_AUTH_TOKEN）

    按一下 Save。

  5. 啟用 Function URL 供外部存取。前往 Configuration > Function URL，按一下 Create function URL：

    • Auth type：若要公開存取，請選取 NONE
    • 在 Additional settings 下勾選 Configure cross-origin resource sharing (CORS)，然後設定：
      • Allow origin：*
      • Allow headers：content-type（搭配 CloudFront/API Gateway 等服務使用時也需要 x-amzn-request-context）
      • Allow methods：*

    按一下 Save。

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

  1. 從 Lambda 主控台複製 Function URL，並在瀏覽器中前往 <your-function-url>/api/agents。你應會看到 Agent 的 JSON 清單。

  2. 現在可以透過 HTTP 呼叫 Mastra 端點。

    警告

    正式環境部署時，請先設定驗證再公開端點、將 CORS 來源限制為信任的網域、使用 AWS IAM 角色安全存取其他 AWS 服務，並將敏感環境變數存放於 AWS Secrets Manager 或 Parameter Store。

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

本指南提供將 Mastra 部署至 AWS Lambda 的快速入門。對於正式環境工作負載，建議為 Lambda 函式啟用 CloudWatch 監控、設定 AWS X-Ray 進行分散式追蹤，並設定佈建並行處理以維持一致的效能。

On this page