> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# 將 Mastra 部署至 AWS Lambda

使用 Docker 容器和 [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter)，將你的 Mastra 應用程式部署至 AWS Lambda。這種方式會把 Mastra 伺服器作為容器化 Lambda 函數運行，並支援自動擴展。

> **資訊:** 本指南涵蓋如何部署 [Mastra 伺服器](https://mastra.zisheng.pro/zh-HK/docs/server/mastra-server)。如果你使用[伺服器 adapter](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters) 或[網絡框架](https://mastra.zisheng.pro/zh-HK/docs/deployment/web-framework)，請按照該框架的一般方式部署。

## 開始之前

你需要：

- 一個 [Mastra 應用程式](https://mastra.zisheng.pro/zh-HK/guides/getting-started/quickstart)
- 一個具備 Lambda、ECR 和 IAM 權限的 [AWS 帳戶](https://aws.amazon.com/)
- 已安裝 **[AWS CLI](https://aws.amazon.com/cli/)**：運行 `aws configure` 進行驗證
- 已安裝並正在運行的 **[Docker](https://www.docker.com/)**

> **注意:** 在 AWS Lambda 上，檔案系統是暫存的，因此任何本機資料庫檔案都會在兩次調用之間遺失。如果你透過本機檔案使用 [LibSQLStore](https://mastra.zisheng.pro/zh-HK/reference/storage/libsql)，請改為設定使用遠端、與 LibSQL 相容的資料庫（例如 [Turso](https://turso.tech/)）。

## 建立 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

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

   ```bash
   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 相容：

   ```bash
   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：

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

4. 登入 Amazon ECR：

   ```bash
   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：

   ```bash
   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 函數

1. 前往 [AWS Lambda Console](https://console.aws.amazon.com/lambda/)，然後按一下 **建立函數**。請確保所選區域與你建立 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 前請先設定[驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth)、將 CORS 來源限制為你信任的網域、使用 AWS IAM role 安全存取其他 AWS 服務，並將敏感的環境變數儲存在 AWS Secrets Manager 或 Parameter Store。

## 後續步驟

本指南提供將 Mastra 部署至 AWS Lambda 的快速入門。對於生產環境工作負載，請考慮為 Lambda 函數啟用 [CloudWatch 監察](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html)、設定 [AWS X-Ray](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) 以進行分散式 tracing，以及設定[預佈並行](https://docs.aws.amazon.com/lambda/latest/dg/provisioned-concurrency.html)以維持一致效能。

## 相關內容

- [部署概覽](https://mastra.zisheng.pro/zh-HK/docs/deployment/overview)
- [Mastra 伺服器](https://mastra.zisheng.pro/zh-HK/docs/server/mastra-server)
- [伺服器 adapter](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters)
- [AWS Lambda 文件](https://docs.aws.amazon.com/lambda/)
- [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter)