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

# AWS Lambda에 Mastra 배포

Docker 컨테이너와[AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter). 이 접근 방식은 자동 조정 기능을 갖춘 컨테이너화된 Lambda 함수로 Mastra 서버를 실행합니다.

> **정보:** 이 가이드에서는[Mastra server](https://mastra.zisheng.pro/ko/docs/server/mastra-server). If you're using a [server adapter](https://mastra.zisheng.pro/ko/docs/server/server-adapters)또는[웹 프레임워크](https://mastra.zisheng.pro/ko/docs/deployment/web-framework), 해당 프레임워크에 대해 일반적인 방식으로 배포합니다.

## 시작하기 전에

다음이 필요합니다.

- 에이[Mastra application](https://mastra.zisheng.pro/ko/guides/getting-started/quickstart)
- 안[AWS account](https://aws.amazon.com/) with permissions for Lambda, ECR, and IAM
- **[AWS CLI](https://aws.amazon.com/cli/)**설치됨: 실행`aws configure` to authenticate
- **[도커](https://www.docker.com/)**설치 및 실행 중

> **경고:** AWS Lambda에서 파일 시스템은 임시적이므로 호출 사이에 로컬 데이터베이스 파일이 손실됩니다. 당신이 사용하는 경우[LibSQLStore](https://mastra.zisheng.pro/ko/reference/storage/libsql) 로컬 파일과 함께 사용하는 경우, 원격 LibSQL 호환 데이터베이스(예: [Turso](https://turso.tech/)) instead.

## Dockerfile 만들기

만들기`Dockerfile` in your project root:

```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` won't work with pnpm lockfiles). :::

## 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 이미지를 빌드하세요. 이미지가 Lambda의 컨테이너 런타임과 호환되는지 확인하려면 BuildKit을 비활성화합니다.

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

   :::참고 BuildKit의 기본 이미지 형식은 Lambda와의 호환성 문제를 일으킬 수 있습니다. 환경`DOCKER_BUILDKIT=0` 는 Lambda가 안정적으로 허용하는 형식의 이미지를 생성하는 클래식 빌더를 사용합니다. :::

3. Docker 이미지를 저장할 Amazon ECR 리포지토리를 생성합니다.

   ```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/) and click **Create function**. ECR 리포지토리를 생성한 리전과 동일한 리전이 선택되어 있는지 확인하세요.

2. 선택하다**Container image** and configure the function:

   - **기능 이름**: 이름을 입력하세요(예:`mastra-app`)
   - **컨테이너 이미지 URI**: 클릭**Browse images**, select your ECR repository, and choose the `latest` tag
   - **건축학**: 선택하다**arm64**

   딸깍 하는 소리**Create function** to create the Lambda function.

3. Memory 및 시간 초과를 구성합니다. 이동**Configuration** > **General configuration** and click **Edit**:

   - **Memory**: 512MB(애플리케이션 요구 사항에 따라 조정)
   - **시간 초과**: 1분 이상(기본 3초는 대부분의 Mastra 애플리케이션에서 너무 낮음)

   딸깍 하는 소리**Save**.

4. 환경 변수를 추가합니다. 이동**Configuration** > **Environment variables** and click **Edit**. Add the variables your Mastra application needs:

   - `OPENAI_API_KEY`: OpenAI API 키(OpenAI를 사용하는 경우)
   - `ANTHROPIC_API_KEY`: 귀하의 Anthropic API 키(Anthropic을 사용하는 경우)
   - 필요에 따라 기타 공급자별 API 키(예:`TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN` if using LibSQL with Turso)

   딸깍 하는 소리**Save**.

5. 외부 액세스를 위해 함수 URL을 활성화합니다. 이동**Configuration** > **Function URL** and click **Create function URL**:

   - **인증 유형**: 선택하다**NONE** for public access

   - 아래에**Additional settings**, check **Configure cross-origin resource sharing (CORS)**, then configure:

     - **원산지 허용**: `*`
     - **헤더 허용**: `content-type` (`x-amzn-request-context` 는 CloudFront/API Gateway 같은 서비스와 함께 사용할 때도 필요합니다.)
     - **메소드 허용**: `*`

   딸깍 하는 소리**Save**.

## 배포 확인

1. 복사**Function URL** from the Lambda console and visit `<your-function-url>/api/agents` 를 브라우저에서 여세요. Agent의 JSON 목록이 표시되어야 합니다.

2. 이제 HTTP를 통해 Mastra 엔드포인트를 호출할 수 있습니다.

   > **경고:** 프로덕션 배포의 경우 다음을 설정합니다.[authentication](https://mastra.zisheng.pro/ko/docs/server/auth) 엔드포인트를 공개하기 전에 CORS 출처를 신뢰할 수 있는 도메인으로 제한하고, 다른 AWS 서비스에 안전하게 액세스할 수 있도록 AWS IAM 역할을 사용하며, 민감한 환경 변수는 AWS Secrets Manager 또는 Parameter Store에 저장하세요.

## 다음 단계

이 가이드는 Mastra를 AWS Lambda에 배포하기 위한 빠른 시작을 제공합니다. 프로덕션 워크로드의 경우 활성화를 고려하세요.[CloudWatch monitoring](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html) for your Lambda function, setting up [AWS X-Ray](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) for distributed tracing, and configuring [provisioned concurrency](https://docs.aws.amazon.com/lambda/latest/dg/provisioned-concurrency.html) for consistent performance.

## 관련된

- [배포 개요](https://mastra.zisheng.pro/ko/docs/deployment/overview)
- [마스트라 서버](https://mastra.zisheng.pro/ko/docs/server/mastra-server)
- [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters)
- [AWS 람다 문서](https://docs.aws.amazon.com/lambda/)
- [AWS Lambda 웹 어댑터](https://github.com/awslabs/aws-lambda-web-adapter)