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

# 将 Mastra 部署到 AWS Lambda

使用 Docker 容器和 [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) 将 Mastra 应用部署到 AWS Lambda。这种方式会将 Mastra Server 作为可自动扩缩的容器化 Lambda 函数运行。

> **信息:** 本指南介绍如何部署 [Mastra Server](https://mastra.zisheng.pro/docs/server/mastra-server)。如果你使用的是 [Server 适配器](https://mastra.zisheng.pro/docs/server/server-adapters)或 [Web 框架](https://mastra.zisheng.pro/docs/deployment/web-framework)，请按该框架的常规方式进行部署。

## 开始之前

你需要：

- 一个 [Mastra 应用](https://mastra.zisheng.pro/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/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 镜像

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` 会使用经典 builder，生成 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. 为镜像添加 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 控制台](https://console.aws.amazon.com/lambda/)，然后单击 **Create function（创建函数）**。请确保所选区域与创建 ECR 仓库的区域相同。

2. 选择 \*\*Container image（容器镜像）\*\*并配置函数：

   - **Function name（函数名称）**：输入名称（例如 `mastra-app`）
   - **Container image URI（容器镜像 URI）**：单击 **Browse images（浏览镜像）**，选择 ECR 仓库，然后选择 `latest` tag
   - **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 Key（使用 OpenAI 时）
   - `ANTHROPIC_API_KEY`：Anthropic API Key（使用 Anthropic 时）
   - 根据需要添加其他 Provider 专用 API Key（例如将 LibSQL 与 Turso 配合使用时的 `TURSO_DATABASE_URL` 和 `TURSO_AUTH_TOKEN`）

   单击 **Save（保存）**。

5. 启用 Function URL 供外部访问。前往 **Configuration（配置）** > **Function URL**，然后单击 **Create function URL（创建函数 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/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) 进行分布式 tracing，并配置[预置并发](https://docs.aws.amazon.com/lambda/latest/dg/provisioned-concurrency.html)以获得稳定性能。

## 相关内容

- [部署概览](https://mastra.zisheng.pro/docs/deployment/overview)
- [Mastra Server](https://mastra.zisheng.pro/docs/server/mastra-server)
- [Server 适配器](https://mastra.zisheng.pro/docs/server/server-adapters)
- [AWS Lambda 文档](https://docs.aws.amazon.com/lambda/)
- [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter)