> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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-TW/docs/server/mastra-server)。若你使用[伺服器轉接器](https://mastra.zisheng.pro/zh-TW/docs/server/server-adapters)或 [Web 框架](https://mastra.zisheng.pro/zh-TW/docs/deployment/web-framework)，請依該框架平常的方式部署。

## 開始之前

你需要：

- 一個 [Mastra 應用程式](https://mastra.zisheng.pro/zh-TW/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-TW/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 鎖定檔使用）。

## 建置並推送 Docker 映像檔

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

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

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

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

   ```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. 標記映像檔並推送至 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/)，按一下 **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 端點。

   > **警告:** 正式環境部署時，請先設定[驗證](https://mastra.zisheng.pro/zh-TW/docs/server/auth)再公開端點、將 CORS 來源限制為信任的網域、使用 AWS IAM 角色安全存取其他 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) 進行分散式追蹤，並設定[佈建並行處理](https://docs.aws.amazon.com/lambda/latest/dg/provisioned-concurrency.html)以維持一致的效能。

## 相關內容

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