Mastra 플랫폼의 서버

Mastra 플랫폼의 서버는 Mastra 애플리케이션을 API 서버로 실행하는 프로덕션 배포 대상입니다. 플랫폼에서 Mastra 서버를 구축, 배포, 호스팅 및 관리하려는 경우 이를 사용하세요.

안정적인 API 엔드포인트, 환경 변수 관리, 사용자 정의 도메인 지원, 배포 기록을 즉시 사용할 수 있습니다.

:::notemastra server deploy 은 이전의 분할 배포 방식입니다. 새 프로젝트에서는 통합된 mastra deploy실행 전 검증, 환경 및 CLI 관리 데이터베이스를 추가하는 명령입니다. :::

노트

서버 배포에서는 호스팅된 스토리지를 자동으로 프로비저닝합니다. 다음으로 저장용량을 재정의하는 경우LibSQLStore 과 파일 URL을 사용 중이라면 원격으로 호스팅되는 데이터베이스로 전환하세요. Mastra 플랫폼은 임시 파일 시스템을 사용하기 때문입니다.

빠른 시작

1. 따라가다get started guide to create your first Mastra project.

2. 설치하다mastra CLI globally:

   npm

   npm install -g mastra

   pnpm

   pnpm add -g mastra

   Yarn

   yarn global add mastra

   Bun

   bun add --global mastra

3. 프로젝트를 배포합니다.

   mastra server deploy

   아직 인증되지 않은 경우 CLI에서 로그인하라는 메시지를 표시합니다. 자격 증명을 로컬에 저장하고 이후의 CLI 명령에서는 이러한 자격 증명을 사용합니다.

   명령이 실행됩니다.mastra build을 실행하고, 아티팩트를 업로드하고, Docker 이미지를 빌드한 후 배포합니다. 첫 배포 시 CLI는 .mastra-project.json 파일을 생성하여 로컬 프로젝트를 플랫폼에 연결합니다. 이후 배포와 CI/CD가 동일한 프로젝트를 대상으로 하도록 이 파일을 커밋하세요.

   :::참고 환경 변수.env, .env.local, and .env.production 은 자동으로 포함됩니다. 첫 배포 시 아직 환경 변수가 설정되지 않았다면 이 값으로 프로젝트의 초기 환경 변수를 설정합니다. 이후에는 웹 대시보드에서 환경 변수를 관리하세요. 개발 전용 비밀 정보나 개인 비밀 정보가 업로드되지 않도록 첫 배포 전에 이 파일들을 검토하고 정리하세요. :::

   참조CLI reference for the full list of flags.

4. CLI에서 인쇄된 URL에서 배포를 확인하세요. 추가/api/agents 에서 Agent의 JSON 목록이 반환되는지 확인하세요.

   경고

   설정authentication before exposing your endpoints publicly.

수명주기 배포

배포는 다음을 통해 전환됩니다.queued → uploading → building → deploying → running (or failed, cancelled, crashed, or stopped)에 표시됩니다. 프로젝트별로 한 번에 하나의 빌드만 실행됩니다. 여러 배포가 대기열에 쌓이면 가장 최근 배포만 진행되고 나머지는 취소됩니다. 15분 넘게 실행되는 빌드는 자동으로 실패 처리됩니다. 첫 배포에서는 인프라를 프로비저닝하고 로컬 .env. Your server URL remains stable across deploys.

유휴 동작

Mastra 플랫폼의 서버는 리소스를 절약하기 위해 일정 기간 동안 활동이 없으면 서비스를 잠자기 상태로 만들 수 있습니다. 비활성은 아웃바운드 네트워크 트래픽으로 측정됩니다. 서비스는 아웃바운드 패킷 없이 약 10분 후에만 유휴 상태로 간주됩니다. 반복되는 아웃바운드 트래픽은 이 타이머를 재설정하고 서비스를 활성 상태로 유지합니다.

절대로 잠들지 않는 서버에는 일반적으로 백그라운드 작업이 있거나 타이머에 따라 트래픽을 보내는 장기간 연결이 있습니다. 다음과 같은 일반적인 원인을 확인하세요.

지속적인 데이터베이스 연결

열려 있는 데이터베이스 클라이언트는 서버가 유휴 상태일 때에도 연결을 유지합니다. 또한 많은 드라이버는 아웃바운드 트래픽으로 계산되는 일정 간격으로 데이터베이스를 ping하는 백그라운드 상태 검사를 실행합니다. 예를 들어, 절대 닫히지 않는 MongoDB 클라이언트는 모니터링 소켓을 열어두고 약 10초마다 하트비트를 보냅니다.

유휴 연결을 소모하는 연결 풀 설정만으로는 드라이버의 모니터링 연결이 열려 있고 계속 핑을 보내기 때문에 충분하지 않습니다. 서버를 절전 모드로 전환하려면 일정 기간 동안 활동이 없으면 클라이언트를 닫고 다음 요청 시 다시 연결하세요.

:::참고 클라이언트를 닫으면 서버가 깨어난 후 첫 번째 요청에 짧은 재연결 지연이 추가됩니다. 워크로드가 이러한 지연을 견딜 수 없는 경우 연결을 열어두고 유휴 절전 모드에 의존하지 마십시오. :::

예약된 작업 및 타이머

에이setInterval, cron 작업 또는 네트워크 호출을 수행하는 폴링 루프는 서버가 절전 상태로 전환되지 않도록 합니다. 예약 작업이 필요한 경우 별도의 서비스로 실행하거나 요청을 보내 서버를 깨우는 외부 스케줄러를 사용하세요.

외부 핑 및 연결 유지 확인

일정한 간격으로 서버에 도달하는 가동 시간 모니터, 상태 확인 또는 연결 유지 핑은 유휴 타이머를 재설정합니다. 서버를 절전 모드로 전환하려면 이러한 검사를 제거하거나 유휴 창 이상으로 간격을 늘리십시오.

관측 가능성 내보내기

추적, 로그 또는 메트릭을 원격 엔드포인트로 스트리밍하는 내보내기는 아웃바운드 트래픽을 보냅니다. 고정된 간격으로 플러시하는 대신 서버가 유휴 상태일 때 내보내기 프로그램이 일괄 처리하고 전송을 중지하는지 확인합니다.

수명이 긴 스트림

개방형 서버 전송 이벤트(SSE) 스트림, WebSocket 또는 기타 장기 연결은 닫힐 때까지 트래픽을 열어 둡니다. 백그라운드에서 구독 상태를 유지하는 스트리밍 응답은 연결을 활성 상태로 유지합니다. 클라이언트 연결이 끊어지면 스트림이 닫히고 서버가 유휴 상태인 동안에는 스트림이 열려 있지 않은지 확인합니다.

채팅 통합

일부 채팅 통합은 지속적인 연결을 유지하고 정기적인 하트비트를 보내 서버를 활성화시킵니다. 예를 들어 소켓 모드의 Slack 앱은 WebSocket을 열고 약 30초마다 핑을 보내고, Discord 봇은 타이머의 하트비트와 함께 게이트웨이 WebSocket을 열어 둡니다. 오픈 소켓과 하트비트 모두 유휴 상태를 방지합니다.

서버를 절전 모드로 전환하려면 통합이 지원하는 영구 연결 대신 HTTP 웹후크를 통해 이벤트를 수신하세요. 예를 들어 Slack 앱은 소켓 모드 대신 요청 URL과 함께 이벤트 API를 사용할 수 있습니다. 앱에 지속적인 연결이 필요한 경우 다음을 사용하여 서비스를 계속 실행하세요.Persistent Server add-on described below.

활성 연결 검사

서버를 깨운 상태로 유지하는 요소를 찾으려면 유휴 기간 동안 프로세스의 활성 핸들을 검사하십시오. 모든 요청이 완료된 후에도 남아 있는 핸들이 조사의 원인입니다. 열린 소켓은 닫아야 하는 영구 연결을 가리키고 활성 타이머는setInterval or self-rescheduling setTimeout.

다음 도우미를 앱에 추가한 후 트래픽이 중지된 후 로그를 살펴보세요. 서버가 유휴 상태일 때에도 계속 나열되는 항목은 서버를 깨어 있게 유지하는 것입니다.

src/mastra/diagnose-idle.ts

export function logActiveHandles() {
  // process._getActiveHandles is undocumented but useful for diagnosis.
  const handles = (process as any)._getActiveHandles() as Array<any>

  const summary = handles.map(handle => {
    const type = handle?.constructor?.name ?? typeof handle
    if (type === 'Socket') {
      return `Socket -> ${handle.remoteAddress}:${handle.remotePort}`
    }
    return type
  })

  console.log(`[idle] ${handles.length} active handles:`, summary)
}

// Log every 30 seconds so you can see what persists while the server is idle.
setInterval(logActiveHandles, 30_000).unref()

부르다unref() 을 진단 간격에 맞춰 실행하여 헬퍼 자체가 서버를 계속 활성 상태로 유지하지 않도록 하세요.

서비스를 계속 실행하세요

일부 애플리케이션에는 실제로 낮은 첫 번째 요청 대기 시간을 위한 영구 데이터베이스 연결, 백그라운드 스케줄러 또는 수명이 긴 스트림과 같이 위에 설명된 연결이나 작업이 필요합니다. 앱에 이러한 항목이 필요한 경우 서비스를 강제로 절전 모드로 전환하지 마세요. 사용Persistent Server add-on to keep the service running continuously instead.

와 함께Persistent Server add-on 이 활성화되면 트래픽이 없어도 서비스가 활성 상태로 유지되므로 영구 연결, 예약 작업 및 열린 스트림이 유휴 절전으로 중단되지 않고 계속 작동합니다.

CI/CD

GitHub Actions, GitLab CI 또는 모든 CI 공급자의 배포를 자동화합니다. 첫 번째 대화형 배포 후 CI/CD에는 API 토큰과 API 토큰이라는 두 가지가 필요합니다..mastra-project.json file committed to your repository.

팁

코드가 GitHub에 있는 경우GitHub integration 을 사용하면 Workflow 파일을 작성하지 않고도 푸시하여 배포할 수 있습니다. GitLab이나 다른 CI Provider가 필요하거나 배포 전에 사용자 지정 빌드 단계를 실행해야 하는 경우 아래의 CLI 기반 CI/CD 흐름을 사용하세요.

API 토큰 만들기

1. 다음 명령을 로컬로 실행합니다.

   mastra auth tokens create ci-deploy

   CLI는 토큰을 한 번 인쇄합니다. 즉시 복사하세요. 다시 검색할 수 없습니다.

2. CI 제공자에 토큰을 비밀로 추가하세요. GitHub Actions에서 다음으로 이동합니다.Settings → Secrets and variables → Actions and create a secret named MASTRA_API_TOKEN.

3. 귀하의.mastra-project.json 파일이 저장소에 커밋되어 있어야 합니다. CLI는 이 파일에서 organizationId and projectId 을 읽어 CI 배포 중에 올바른 프로젝트를 대상으로 지정합니다.

그만큼--yes flag

통과하다--yes (or -y)을 사용하여 모든 확인 메시지를 건너뛰세요. 이 옵션이 없으면 CLI가 대화형 입력을 기다리므로 CI 작업이 멈춥니다.

mastra server deploy --yes

GitHub 작업

다음 Workflow는 푸시할 때마다 배포됩니다.main:

.github/workflows/deploy-mastra.yml

name: Deploy to Mastra platform

on:
  push:
    branches: [main]
    paths: ['src/mastra/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - name: Install dependencies
        run: npm install
      - name: Deploy to Mastra platform
        run: npx mastra server deploy --yes
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}

조정하다paths filter and working-directory 을 사용하세요. Mastra 프로젝트가 하위 디렉터리(예: 모노레포)에 있는 경우 필요합니다.

노트

Studio 배포의 경우 교체mastra server deploy with mastra studio deploy을 사용해도 됩니다. 플래그와 환경 변수는 동일합니다.

GitLab CI

다음 파이프라인은 푸시 시 배포됩니다.main:

.gitlab-ci.yml

deploy:
  image: node:22
  stage: deploy
  only:
    - main
  before_script:
    - npm install
  script:
    - npx mastra server deploy --yes

추가하다MASTRA_API_TOKEN as a CI/CD variable in Settings → CI/CD → Variables.

기타 CI Provider

Node.js 및 셸 명령을 실행하는 모든 CI 시스템은 Mastra와 함께 작동합니다.

1. 종속성을 설치합니다.
2. 세트MASTRA_API_TOKEN as an environment variable.
3. 달리다mastra server deploy --yes (or mastra studio deploy --yes).

배포 확인

Workflow가 완료된 후 상태 엔드포인트를 눌러 배포를 확인합니다.

curl -f https://<your-project>.server.mastra.cloud/health

또는 Agent의 JSON 목록을 반환하는 Agent 엔드포인트를 확인하세요.

curl -f https://<your-project>.server.mastra.cloud/api/agents

다음 예에서는 GitHub Actions Workflow에 확인 단계를 추가합니다.

- name: Verify deployment
  run: |
    sleep 30
    curl -f https://<your-project>.server.mastra.cloud/health

환경 변수로 프로젝트 구성 재정의

CLI는 다음을 읽습니다.organizationId and projectId from .mastra-project.json 을 기본값으로 사용합니다. 이러한 값을 재정의하려면(예: 동일한 저장소에서 다른 프로젝트로 배포하려는 경우) 다음 환경 변수를 설정하세요:

변수	설명
MASTRA_ORG_ID	Overrides the organization ID from .mastra-project.json.
MASTRA_PROJECT_ID	Overrides the project ID from .mastra-project.json.

관련된

• mastra server deploy
• mastra server pause
• mastra server restart
• mastra studio deploy
• mastra auth tokens