Mastra 서버 배포

Mastra는 Node.js, Bun 또는 Deno를 지원하는 모든 플랫폼에서 실행할 수 있는 독립형 Node.js 서버로 애플리케이션을 컴파일합니다.

팁

이 가이드에서는 mastra build로 생성된 독립 실행형 서버를 배포하는 방법을 다룹니다. 기존 Express 또는 Hono 애플리케이션에 Mastra를 통합해야 한다면 대신 서버 어댑터를 참조하세요.

애플리케이션 구축

프로젝트 루트에서 빌드 명령을 실행합니다.

mastra build

이 명령은 프로덕션 준비가 완료된 서버가 포함된 .mastra 디렉터리를 생성합니다. 사용 가능한 모든 플래그는 mastra build 레퍼런스를 참조하세요.

빌드 출력

구축 후 Mastra는 다음 구조를 생성합니다.

.mastra/
├── .build/                # Intermediate build artifacts (module maps, analysis)
└── output/
    ├── index.mjs          # Server entry point
    ├── mastra.mjs         # Your bundled Mastra configuration
    ├── tools.mjs          # Aggregated tool exports
    ├── tools/             # Individual tool bundles
    ├── package.json       # Production dependencies
    ├── node_modules/      # Installed dependencies
    ├── .npmrc             # Copied from your project (if present)
    ├── public/            # Static assets (if src/mastra/public exists)
    └── playground/        # Studio UI (if --studio flag used)

output 디렉터리는 독립적으로 실행할 수 있습니다. 어느 서버에든 복사해 직접 실행할 수 있습니다.

서버 실행

Mastra CLI를 사용하여 서버를 시작합니다.

mastra start

또는 Node.js로 직접 실행하세요.

node .mastra/output/index.mjs

그만큼mastra start command provides additional features:

• .env.production과 .env에서 환경 변수를 로드합니다.
• 누락된 모듈에 대해 유용한 오류 메시지를 제공합니다.
• 정상적인 종료를 위해 프로세스 신호를 처리합니다. 사용 가능한 모든 플래그는 mastra start 레퍼런스를 참조하세요.

빌드 구성

빌드 시간 구성

Mastra는 애플리케이션을 빌드할 때 bundler, deployer, server 옵션을 읽습니다. 빌드가 해당 옵션을 추출할 수 있도록 new Mastra()에 전달하는 객체의 직접 속성으로 유지하세요. 다음 항목 파일 형태가 작동합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'

export const mastra = new Mastra({
  bundler: {
    externals: ['sharp'],
  },
  server: {
    port: 4111,
  },
})

각 옵션의 값은 변수, 가져오기 또는 함수 호출에서 나올 수 있습니다. 옵션 자체는 직접 속성으로 유지되어야 합니다. 팩토리 호출이나 객체 확산 뒤에 빌드 타임 옵션을 숨기지 마세요.

src/mastra/index.ts

const options = {
  bundler: {
    externals: ['sharp'],
  },
}

// These patterns prevent Mastra from extracting `bundler` during the build.
export const mastra = new Mastra(createMastraOptions())
export const otherMastra = new Mastra({ ...options })

Mastra가 옵션을 추출할 수 없으면 해당 옵션에 기본 빌드 동작을 사용합니다. 사용 가능한 bundler, deployer, server 설정은 구성 레퍼런스를 참조하세요.

공용 폴더

Mastra 디렉터리(src/mastra/public)에 public 폴더가 있으면 빌드 중 해당 내용이 출력 디렉터리로 복사됩니다. 서버는 이 파일들을 정적 에셋으로 제공합니다.

마스트라 구성

빌드 프로세스는 Mastra 인스턴스의 구성을 따릅니다. CORS, 시간 초과, 미들웨어 같은 서버 동작은 서버 개요를 참조하세요. 사용 가능한 모든 옵션은 구성 레퍼런스를 참조하세요.

빌드 프로세스

빌드는 다음 단계를 따릅니다.

1. 진입점 파일 찾기: Mastra 디렉터리에서 index.ts 또는 index.js를 찾습니다.
2. Tool 검색: 테스트 파일을 제외하고 {mastraDir}/tools/**/*.{js,ts}와 일치하는 Tool 파일을 검색합니다.
3. 종속성 분석: 번들에 포함할 패키지와 외부에 설치할 패키지를 결정합니다.
4. 코드 번들링: 트리 셰이킹과 선택적 소스 맵을 적용해 Rollup으로 번들링합니다.
5. 서버 생성: Hono 기반 HTTP 서버를 index.mjs로 생성합니다.
6. 종속성 설치: 출력 디렉터리에서 npm install을 실행합니다.
7. 에셋 복사: public 폴더와 .npmrc가 있으면 복사합니다.

환경변수

변수	설명
PORT	서버 포트(기본값: 4111)
MASTRA_STUDIO_PATH	Studio 빌드 디렉터리 경로(기본값: ./playground)
MASTRA_SKIP_DOTENV	설정된 경우 .env 파일 로드를 건너뜀
NODE_OPTIONS	Node.js 옵션(예: 빌드 메모리 문제에는 --max-old-space-size=4096)

서버 엔드포인트

구축된 서버는 상태 확인, Agent, Workflow 등에 대한 엔드포인트를 노출합니다.

엔드포인트	설명
GET /health	상태 확인 엔드포인트이며 200 OK 반환
GET /api/openapi.json	OpenAPI 명세(server.build.openAPIDocs가 활성화된 경우)
GET /swagger-ui	대화형 API 문서(server.build.swaggerUI가 활성화된 경우)
이 목록은 전체 목록이 아닙니다. 모든 엔드포인트를 보려면 mastra dev를 실행하고 http://localhost:4111/swagger-ui를 방문하세요.
고유한 엔드포인트를 추가하려면 다음을 참조하세요.Custom API Routes.

문제 해결

빌드 중 Memory 오류

당신이 만난다면JavaScript heap out of memory errors:

NODE_OPTIONS="--max-old-space-size=4096" mastra build

관련된

• 서버 개요: 서버 동작, 미들웨어, 인증 구성
• 서버 어댑터: 대신 Express나 Hono를 사용하세요.mastra build
• 사용자 정의 API 경로: 사용자 정의 HTTP 엔드포인트 추가
• 구성 참조: 전체 구성 옵션