Mastra Cloud에서 Mastra 플랫폼으로 마이그레이션

Mastra 플랫폼은 Mastra Cloud를 별도의 Studio 및 Server 제품, CLI 기반 배포 및 새로운 관찰 시스템으로 대체합니다. 이 가이드는 각 단계를 안내합니다.

무엇이 바뀌었나

면적	마스트라 클라우드	마스트라 플랫폼
Products	Single project	Separate Studio and Server
Deploys	푸시 시 자동 배포	CLI 기반(mastra studio deploy, mastra server deploy)
프로젝트 생성	GitHub 가져오기	CLI가 처음 배포 시 프로젝트 생성
저장	관리형 LibSQL(Cloud Store) 또는 자체 가져오기	자체 호스팅 데이터베이스 가져오기
Observability	로거 기반	Observability수출업자와 함께하는 수업
환경 변수	프로젝트 설정 시 설정	다음에서 시드됨.env첫 번째 배포 시, 이후 대시보드에서 관리됨
URL	단일 URL	별도의 Studio 및 서버 URL

시작하기 전에

1. CLI를 설치하거나 업데이트합니다.

   npm

   npm install -g mastra@latest

   pnpm

   pnpm add -g mastra@latest

   Yarn

   yarn global add mastra@latest

   Bun

   bun add --global mastra@latest

2. 인증:

   mastra auth login

3. 프로젝트가 로컬에서 빌드되었는지 확인합니다.

   mastra build

Mastra Cloud Store를 호스팅된 데이터베이스로 교체

Mastra Cloud는 다음이 지원하는 관리형 libSQL 데이터베이스를 제공했습니다.Turso. Mastra 플랫폼은 데이터베이스를 대신 호스팅하지 않으므로 스토리지가 외부에서 호스팅되는 인스턴스를 가리키도록 설정해야 합니다.

이미 호스팅된 데이터베이스를 사용하고 있는 경우("직접 가져오기") 기존 데이터베이스 구성을 유지하세요. 연결 문자열이 하드코딩되지 않고 대시보드에서 환경 변수로 설정되었는지 확인하세요.

Cloud Store를 사용하는 경우 아래 단계에 따라 데이터를 내보내고 제어하는 ​​새 libSQL 데이터베이스에 로드하세요.

Cloud Store 데이터 내보내기

대시보드에서 다운로드하거나 Turso CLI를 사용하여 수동 덤프를 생성하는 두 가지 방법으로 Cloud Store 데이터를 내보낼 수 있습니다.

옵션 A: 대시보드에서 내보내기(권장)

다음에서 프로젝트를 엽니다.Mastra dashboard and navigate to Runtime → Settings → Storage. Click the Export Database button. The dashboard generates a full .sql 은 Cloud Store의 dump를 생성하여 Downloads 폴더에 바로 다운로드합니다.

다운로드가 완료되면 덤프를 SQLite 데이터베이스 파일로 변환합니다.

sqlite3 mydb.db < ~/Downloads/mastra-cloud-dump.sql

이제 휴대용이 생겼습니다mydb.db 파일은 로컬에서 검사하거나 백업할 수 있으며, 이후 단계에서 새 데이터베이스의 원본으로 사용할 수도 있습니다.

옵션 B: Turso CLI를 통해 내보내기

명령줄에서 작업하는 것을 선호하거나 내보내기 스크립트가 필요한 경우 다음을 사용하여 데이터베이스를 직접 덤프할 수 있습니다.Turso CLI. 이 방법을 사용하려면 데이터베이스 URL과 auth token이 필요하며, 둘 다 dashboard에 표시됩니다.

1. 대시보드에서 Cloud Store 자격 증명을 검색하세요.

   다음에서 프로젝트를 엽니다.Mastra dashboard and navigate to Runtime → Settings → Env Variables. Cloud Store 기반 프로젝트에서는 사용자가 지정한 변수와 함께 다음 두 변수가 주입됩니다:

   • MASTRA_STORAGE_URL: libSQL 연결 문자열(예:libsql://<db-name>-<org>.turso.io).
   • MASTRA_STORAGE_AUTH_TOKEN: 해당 데이터베이스로 범위가 지정된 읽기 가능 인증 토큰입니다.

   각 행은 눈 토글, 편집, 삭제 및 값 복사를 통한 표시/숨기기 등 표준 환경 변수 작업을 지원합니다. 사용Copy Value 을 사용해 아래 dump 명령에 필요한 두 값을 모두 가져옵니다.

   :::참고 이러한 변수는 Cloud Store로 프로비저닝된 프로젝트에만 표시됩니다. 자신의 데이터베이스를 Mastra Cloud로 가져온 경우 이미 이러한 자격 증명을 가지고 있으므로 건너뛸 수 있습니다.Point your Mastra app at the new database. :::

   정보

   변수가 누락된 경우 값이 해독되지 않거나 Turso CLI가 토큰, 이메일을 거부합니다.support@mastra.ai 로 Mastra Cloud 계정에 연결된 이메일 주소에서 문의하여 내보낼 프로젝트의 libSQL URL과 auth token을 요청하세요. 프로젝트 이름/ID를 포함해야 합니다. 네트워크에서 CLI 접근이 차단된 경우 지원팀에서 대신 dump를 실행할 수도 있습니다.

2. Turso CLI를 설치합니다.

   macOS

   brew install tursodatabase/tap/turso

   Linux / WSL

   curl -sSfL https://get.tur.so/install.sh | bash

   참조Turso CLI introduction for Windows and headless-install options.

3. 데이터베이스를 SQL 덤프로 내보냅니다.

   지원에서 제공한 자격 증명을 환경 변수로 설정(또는 이전에 이미 복사한 경우 대시보드 값 사용)한 다음 데이터베이스를 로컬 파일에 덤프합니다. 대시보드에서 URL을 복사한 경우libsql:// scheme for https:// — auth token과 함께 URL을 전달할 때 Turso CLI에는 HTTPS 형식이 필요합니다.

   export MASTRA_STORAGE_URL="https://<db-name>-<org>.turso.io"
   export MASTRA_STORAGE_AUTH_TOKEN="<token-from-dashboard-or-support>"
   
   turso db shell "$MASTRA_STORAGE_URL?authToken=$MASTRA_STORAGE_AUTH_TOKEN" ".dump" > mastra-cloud-dump.sql

   경고

   연결 문자열에 인증 토큰을 포함시키는 것은 Turso의 권장 패턴보다 덜 안전합니다. 전체 URL(토큰 포함)은 셸 기록, 프로세스 목록 및 터미널 로그에 포함될 수 있습니다. Turso는 공식적으로 달리기를 권장합니다.turso auth login and then dumping by database name only: turso db shell <database-name> ".dump" > mastra-cloud-dump.sql. 이 절차를 사용하려면 사용자가 소유한 Turso 계정에 데이터베이스가 있어야 하지만 Cloud Store는 그렇지 않으므로, 이번 일회성 내보내기의 대안으로 위의 환경 변수 예시를 제공합니다. token 보간을 완전히 피하려면 지원팀에 대신 dump를 실행하고 생성된 SQL 파일을 보내 달라고 요청하세요.

   결과mastra-cloud-dump.sql 에는 전체 schema와 데이터, 즉 thread 및 message 기록, Workflow snapshot, Trace, Evals 점수가 포함됩니다. 계속하기 전에 안전한 곳에 보관하세요.

새 libSQL 데이터베이스에 덤프 로드

덤프는 표준 SQL 파일이며 모든 libSQL 호환 데이터베이스에 로드될 수 있습니다. 아래 예에서는 마이그레이션을 유사하게 유지하고 스키마 변환을 방지하는 새로운 Turso 호스팅 데이터베이스를 사용합니다.

1. 자신의 Turso 계정에 대해 Turso CLI를 인증합니다.

   turso auth login

   Turso 계정이 없으면 CLI에서 계정을 생성하라는 메시지를 표시합니다. 보다Turso pricing for plan details.

2. 새 데이터베이스를 생성하고 한 단계로 덤프를 로드합니다.

   turso db create mastra-migrated --from-dump ./mastra-cloud-dump.sql

   --from-dump생성 시 로컬 SQLite/libSQL 덤프를 복원합니다. 이는 파이핑 문보다 빠르고 안전합니다.turso db shell 은 나중에 변경할 수 없습니다. 지연 시간을 최소화하려면 Mastra Server가 실행되는 위치와 가까운 region을 선택하세요. 사용 가능한 region은 다음 명령으로 확인할 수 있습니다: turso db locations and pass --group <group-name> if you manage multiple groups.

   멀티 기가바이트 덤프의 경우 다음을 추가하세요.--wait 을 사용하면 데이터베이스를 완전히 사용할 수 있을 때까지 CLI가 대기합니다.

3. 새 데이터베이스에 대한 연결 자격 증명을 생성합니다.

   turso db show mastra-migrated --url
   turso db tokens create mastra-migrated

   첫 번째 명령은 libSQL URL을 인쇄합니다. 두 번째는 인증 토큰을 인쇄합니다. 둘 다 필요합니다.LibSQLStore.

Mastra 앱이 새 데이터베이스를 가리키도록 하세요.

새 자격 증명을 로컬에서 환경 변수로 설정합니다..env or in the Mastra platform dashboard:

.env

TURSO_DATABASE_URL="libsql://mastra-migrated-<org>.turso.io"
TURSO_AUTH_TOKEN="<token-from-turso-db-tokens-create>"

구성LibSQLStore to read from those variables:

src/mastra/index.ts

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

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'libsql-storage',
    url: process.env.TURSO_DATABASE_URL!,
    authToken: process.env.TURSO_AUTH_TOKEN,
  }),
})

참조libSQL storage reference for the full set of options.

마이그레이션 확인

클라우드 프로젝트를 폐기하기 전에 새 데이터베이스가 앱에서 기대하는 데이터를 제공하는지 확인하세요.

• 달리다turso db shell mastra-migrated "SELECT name FROM sqlite_master WHERE type='table';" 을 사용해 table 목록을 확인합니다. 출력에는 Mastra가 관리하는 table(예: mastra_threads, mastra_messages, mastra_workflow_snapshot, mastra_traces).
• 예를 들어 알려진 채워진 테이블에 대해 행 개수를 실행합니다.turso db shell mastra-migrated "SELECT COUNT(*) FROM mastra_messages;", 그 결과를 Cloud Store URL에 대해 실행한 동일한 쿼리의 결과와 비교합니다.
• 새 자격 증명에 대해 Mastra 앱을 시작하고 기존 스레드 또는 Workflow 실행이 예상대로 로드되는지 확인합니다.Studio.

관측 가능성 구성 업데이트

Mastra Cloud는 로거 기반 추적을 사용했습니다. Mastra 플랫폼은Observability class with explicit exporters.

Observability 패키지를 설치합니다.

npm

npm install @mastra/observability

pnpm

pnpm add @mastra/observability

Yarn

yarn add @mastra/observability

Bun

bun add @mastra/observability

이전(마스트라 클라우드):

src/mastra/index.ts

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

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'my-app', level: 'info' }),
  // traces appear in Cloud dashboard automatically
})

이후(Mastra 플랫폼):

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

• MastraStorageExporterMastra Storage에 대한 관측 가능성 이벤트를 지속합니다.Studio.
• MastraPlatformExporter다음과 같은 경우 관측 가능성 이벤트를 Mastra 플랫폼으로 보냅니다.MASTRA_PLATFORM_ACCESS_TOKEN is set.
• SensitiveDataFilter내보내기 전에 스팬 데이터에서 비밀번호, 토큰, 키를 수정합니다.

참조observability overview 메트릭용 DuckDB를 사용하는 복합 스토리지를 포함한 전체 구성은 다음을 참조하세요.

스튜디오 배포

호스팅된 Studio 인스턴스를 배포합니다.

mastra studio deploy

CLI는 프로젝트를 빌드하고 배포하기 전에 아티팩트를 업로드합니다. 처음 배포할 때.mastra-project.json 파일이 생성되어 로컬 프로젝트를 플랫폼에 연결합니다. 이 파일을 리포지토리에 커밋하세요.

로컬 env 파일은 선택 사항입니다. 언제.env or .env.* 파일이 프로젝트 디렉터리에 있으면 배포 시 해당 환경 변수가 번들에 포함됩니다.

비대화형 단계에서 새 플랫폼 프로젝트를 생성하려면(실행하는 대신)mastra studio projects create separately), pass a name with --project and accept defaults with --yes:

mastra studio deploy --project "my-new-project" --yes

보다Studio deployment for details.

다양한 환경

단일 Mastra 플랫폼 프로젝트는 여러 프로젝트에서 동일한 코드베이스를 실행합니다.environments, such as production and staging. Deploy to each with the unified mastra deploy command:

mastra deploy --env production --yes
mastra deploy --env staging --env-file .env.staging --yes

각 환경에는 별도의 배포 기록과 함께 전용 URL 및 환경 변수가 있습니다.

서버 배포(선택 사항)

프로덕션 API 엔드포인트가 필요한 경우 서버를 배포하세요.

mastra server deploy

이렇게 하면 안정적인 API URL, 환경 변수 관리 및 사용자 지정 도메인 지원을 갖춘 별도의 배포가 생성됩니다. 참조Server deployment guide for the full walkthrough.

:::참고 환경 변수.env, .env.local, and .env.production 는 첫 배포 시 자동으로 포함됩니다. 이후에는 다음을 통해 환경 변수를 관리하세요: web dashboard. 개발 전용 또는 개인용 비밀 정보가 업로드되지 않도록 첫 배포 전에 이러한 파일을 검토하고 민감한 정보를 제거하세요. :::

CI 설정(선택사항)

푸시 시 Mastra Cloud가 자동 배포됩니다. Mastra 플랫폼은 모든 CI 제공자에서 실행할 수 있는 CLI 기반 배포를 사용합니다.

전제조건

1. API 토큰을 만듭니다.

   mastra auth tokens create ci-deploy

2. 토큰을 GitHub Actions 비밀로 저장합니다(예:MASTRA_API_TOKEN).

3. 저지르다.mastra-project.json 를 리포지토리에 커밋하세요(첫 수동 배포 시 생성됨).

언제MASTRA_API_TOKEN 가 설정되면 CLI가 헤드리스 모드로 실행되고 모든 대화형 Prompt를 건너뜁니다.

기본으로 푸시 시 서버 배포

서버 배포는 다음의 조직 및 프로젝트를 허용합니다..mastra-project.json이므로 토큰 외에 추가 환경 변수는 필요하지 않습니다:

.github/workflows/deploy-server.yml

name: Deploy to Mastra Server

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: pnpm install
      - run: pnpm mastra server deploy --yes --config .mastra-project.json
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}

메인으로 푸시 시 Studio 배포

Studio 배포에는 다음이 필요합니다.MASTRA_ORG_ID and MASTRA_PROJECT_ID as env vars in headless mode, even when --config is provided:

.github/workflows/deploy-studio.yml

name: Deploy to Mastra Studio

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: pnpm install
      - run: pnpm mastra studio deploy --yes --config .mastra-project.json
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}
          MASTRA_ORG_ID: ${{ secrets.MASTRA_ORG_ID }}
          MASTRA_PROJECT_ID: ${{ secrets.MASTRA_PROJECT_ID }}

오래된 Cloud 프로젝트 폐기

이전 Mastra Cloud URL을 가리키는 모든 클라이언트를 새 서버 또는 Studio URL로 업데이트하세요. 다음을 확인하여 새 플랫폼에 추적이 나타나는지 확인하세요.Studio observability dashboard. 모든 항목이 정상적으로 작동하는지 확인한 후 기존 Mastra Cloud 프로젝트를 삭제하세요.

관련된

• 마스트라 플랫폼 개요
• Observability 개요
• 스튜디오 배포
• 서버 배포
• CLI 참조