AWS Lambda

使用 Docker 容器和 AWS Lambda Web 适配器将你的 Mastra 应用部署到 AWS Lambda。该方法允许你将 Mastra 服务器作为容器化的 Lambda 函数运行，并实现自动扩展。

🌐 Deploy your Mastra applications to AWS Lambda using Docker containers and the AWS Lambda Web Adapter. This approach allows you to run your Mastra server as a containerized Lambda function with automatic scaling.

note

本指南假设你的 Mastra 应用是使用默认的 npx create-mastra@latest 命令创建的。有关如何创建新的 Mastra 应用的更多信息，请参阅我们的入门指南

先决条件

🌐 Prerequisites

在部署到 AWS Lambda 之前，请确保你已：

🌐 Before deploying to AWS Lambda, ensure you have:

• AWS CLI 已安装并配置
• Docker 已安装并正在运行
• 拥有适当权限的 AWS 账户，用于 Lambda、ECR 和 IAM
• 你的 Mastra 应用已配置了适当的内存存储

内存配置

🌐 Memory Configuration

warning

AWS Lambda 使用的是临时文件系统，这意味着写入文件系统的任何文件都是短暂的，可能会丢失。请从你的 Mastra 配置中移除任何带有文件 URL 的 LibSQLStore 使用。请使用内存存储（:memory:）或像 Turso、PostgreSQL 或 Upstash 这样的外部存储提供商。

Lambda 函数在文件系统存储方面有局限性。请配置你的 Mastra 应用使用内存存储或外部存储提供程序：

🌐 Lambda functions have limitations with file system storage. Configure your Mastra application to use either in-memory or external storage providers:

选项 1：内存（最简单）

🌐 Option 1: In-Memory (Simplest)

src/mastra/index.ts

import { LibSQLStore } from "@mastra/libsql";

const storage = new LibSQLStore({
  id: 'mastra-storage',
  url: ":memory:", // in-memory storage
});

选项 2：外部存储提供商

🌐 Option 2: External Storage Providers

要在 Lambda 调用之间保持持久内存，可以使用 Turso 提供的 LibSQLStore 等外部存储提供商，或其他存储提供商如 PostgreStore：

🌐 For persistent memory across Lambda invocations, use external storage providers like LibSQLStore with Turso or other storage providers like PostgreStore:

src/mastra/index.ts

import { LibSQLStore } from "@mastra/libsql";

const storage = new LibSQLStore({
  id: 'mastra-storage',
  url: "libsql://your-database.turso.io", // External Turso database
  authToken: process.env.TURSO_AUTH_TOKEN,
});

有关更多内存配置选项，请参阅内存文档。

🌐 For more memory configuration options, see the Memory documentation.

创建 Dockerfile

🌐 Creating a Dockerfile

在你的 Mastra 项目根目录中创建一个 Dockerfile：

🌐 Create a Dockerfile in your Mastra project root directory:

Dockerfile

FROM node:22-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY src ./src
RUN npx mastra build
RUN apk add --no-cache gcompat

COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.0 /lambda-adapter /opt/extensions/lambda-adapter
RUN addgroup -g 1001 -S nodejs && \
  adduser -S mastra -u 1001 && \
  chown -R mastra:nodejs /app

USER mastra

ENV PORT=8080
ENV NODE_ENV=production
ENV READINESS_CHECK_PATH="/api"

EXPOSE 8080

CMD ["node", ".mastra/output/index.mjs"]

构建与部署

🌐 Building and Deploying

1. 为部署过程设置环境变量：

   🌐 Set up your environment variables for the deployment process:

   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 镜像：

   🌐 Build your Docker image locally:

   docker build -t "$PROJECT_NAME" .

3. 创建一个 Amazon ECR 仓库来存储你的 Docker 镜像：

   🌐 Create an Amazon ECR repository to store your Docker image:

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

4. 登录到 Amazon ECR：

   🌐 Log in to 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 仓库 URI 标签你的镜像并推送它：

   🌐 Tag your image with the ECR repository URI and push it:

   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

6. 使用 AWS 控制台创建一个 Lambda 函数：

   🌐 Create a Lambda function using the AWS Console:

   1. 导航到 AWS Lambda 控制台
   2. 点击 创建函数
   3. 选择 容器镜像
   4. 配置功能：
      • 函数名：你的函数名（例如，mastra-app）
      • 容器镜像 URI：点击 浏览镜像 并选择你的 ECR 仓库，然后选择 latest 标签
      • 架构：选择与你的 Docker 构建相匹配的架构（通常为 x86_64）

7. 启用功能 URL 以便外部访问：

   🌐 Enable Function URL for external access:

   1. 在 Lambda 函数配置中，转到 配置 > 函数 URL
   2. 点击 创建函数 URL
   3. 将 身份验证类型 设置为 无（用于公共访问）
   4. 配置 CORS 设置：
      • 允许来源: *（在生产环境中限制为你的域名）
      • 允许的头：content-type（在与 Cloudfront/API Gateway 等服务一起使用时，也需要 x-amzn-request-context）
      • 允许的方法: *（在生产环境中进行审计和限制）
   5. 点击 保存

8. 在 Lambda 函数配置中添加你的环境变量：

   🌐 Add your environment variables in the Lambda function configuration:

   1. 转到 配置 > 环境变量
   2. 为你的 Mastra 应用添加所需的变量：
      • OPENAI_API_KEY：你的 OpenAI API 密钥（如果使用 OpenAI）
      • ANTHROPIC_API_KEY：你的 Anthropic API 密钥（如果使用 Anthropic）
      • TURSO_AUTH_TOKEN：你的 Turso 认证令牌（如果在 Turso 中使用 libSQL）
      • 根据需要的其他提供商特定 API 密钥

9. 配置函数的内存和超时设置：

   🌐 Configure the function's memory and timeout settings:

   1. 进入 配置 > 常规配置
   2. 设置以下推荐值：
      • 内存：512 MB（根据你的应用需求进行调整）
      • 超时：30秒（根据你的应用需求进行调整）
      • 临时存储：512 MB（可选，用于临时文件）

测试你的部署

🌐 Testing your deployment

部署后，测试你的 Lambda 函数：

🌐 Once deployed, test your Lambda function:

1. 从 Lambda 控制台复制 函数 URL
2. 在浏览器中访问该 URL 以查看你的 Mastra 服务器主屏幕
3. 使用生成的 API 端点测试你的代理和工作流

有关可用 API 端点的更多信息，请参阅服务器文档。

🌐 For more information about available API endpoints, see the Server documentation.

正在连接你的客户端

🌐 Connecting your client

更新你的客户端应用以使用 Lambda 函数 URL：

🌐 Update your client application to use the Lambda function URL:

src/client.ts

import { MastraClient } from "@mastra/client-js";

const mastraClient = new MastraClient({
  baseUrl: "https://your-function-url.lambda-url.us-east-1.on.aws",
});

故障排除

🌐 Troubleshooting

函数超时错误

🌐 Function timeout errors

如果你的 Lambda 函数超时：

🌐 If your Lambda function times out:

• 在 配置 > 常规配置 中增加超时时间
• 优化你的 Mastra 应用以实现更快的冷启动
• 考虑使用预置并发以实现稳定的性能

内存问题

🌐 Memory issues

如果你遇到与内存相关的错误：

🌐 If you encounter memory-related errors:

• 在 配置 > 常规配置 中增加内存分配
• 在 CloudWatch 日志中监控内存使用情况
• 优化你的应用的内存使用

跨域请求问题

🌐 CORS issues

如果在访问端点时遇到 CORS 错误，但访问主页没有问题：

🌐 If you encounter CORS errors when accessing endpoints but not the home page:

• 验证 CORS 头是否在你的 Mastra 服务器配置中正确设置
• 检查 Lambda 函数 URL 的 CORS 配置
• 确保你的客户端正在向正确的 URL 发送请求

容器镜像问题

🌐 Container image issues

如果 Lambda 函数启动失败：

🌐 If the Lambda function fails to start:

• 验证 Docker 镜像能否在本地成功构建
• 检查你的 Dockerfile 中的 CMD 指令是否正确
• 检查 CloudWatch 日志以查找容器启动错误
• 确保 Lambda Web 适配器已正确安装在容器中

生产考虑

🌐 Production considerations

用于生产部署：

🌐 For production deployments:

安全

🌐 Security

• 将 CORS 来源限制为你信任的域
• 使用 AWS IAM 角色安全访问其他 AWS 服务
• 将敏感环境变量存储在 AWS Secrets Manager 或 Parameter Store 中

监控

🌐 Monitoring

• 为你的 Lambda 函数启用 CloudWatch 监控
• 为错误和性能指标设置 CloudWatch 警报
• 使用 AWS X-Ray 进行分布式追踪

缩放

🌐 Scaling

• 配置预置并发以获得可预测的性能
• 监控并发执行情况，并根据需要调整限制
• 考虑使用应用负载均衡器来满足更复杂的路由需求

下一步

🌐 Next steps

• Mastra 客户端 SDK
• AWS Lambda 文档
• AWS Lambda 网络适配器