Mastra 플랫폼에 배포

mastra deployMastra 애플리케이션을 릴리스하기 위한 단일 명령입니다.마스트라 플랫폼.

하나의 명령은 프로젝트를 빌드하고 포함하기 전에 유효성을 검사하며, 처음 실행 시 플랫폼 프로젝트와 환경을 생성하고, 배포하고, 빌드 로그를 스트리밍하고, 배포가 트래픽을 제공하면 공개 URL을 인쇄합니다.

mastra deploy

:::참고 이 페이지에서는 통합 배포 흐름을 다룹니다. 이전 분할 명령은mastra server deploy and mastra studio deploy, still work but mastra deploy권장 경로입니다. :::

시작하기 전에

당신은Mastra application and a Mastra platform 계정입니다. 인증되지 않은 경우 CLI는 처음 사용할 때 로그인하라는 메시지를 표시합니다.

현지인.env 파일은 선택 사항입니다. 플랫폼에 저장된 환경 변수는 배포 시 그대로 사용되며, 다음과 같은 관리형 리소스도 마찬가지입니다: hosted databases inject their own variables. Pass --env-file 로컬 값을 그 위에 추가하려는 경우에만 사용하세요.

첫 번째 배포

1. 프로젝트 디렉터리에서 다음을 실행합니다.

   mastra deploy

   처음 실행 시 CLI는 플랫폼 프로젝트(이름을 따서 명명)를 생성하라는 메시지를 표시합니다.package.json) and the production environment. Accept the prompts, or pass --yes to accept defaults without confirmation.

2. CLI는 배송 전 실행 전 검사를 실행합니다. 로컬 파일 경로(플랫폼의 임시 파일 시스템에서 유지되지 않음)로 대체되는 스토리지는 일반적으로 배포를 차단합니다.

   file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set

   오류가 발생하는 대신 CLI는 인라인으로 문제를 해결하도록 제안합니다.

   Preflight needs TURSO_DATABASE_URL for the production environment. Create a managed turso database now and attach it? (Y/n)

   Prompt를 수락하면 프로비저닝하는 데 몇 초가 걸립니다. 데이터베이스의 연결 변수는 배포에 자동으로 삽입되며, 데이터베이스에 복사할 내용은 없습니다..env 파일입니다. 이를 거부하거나 비대화형 셸(CI, --yes)에서 실행하면 CLI는 이전 동작으로 대체하여 직접 실행할 정확한 명령을 출력합니다.

   mastra env db create production --kind turso

   환경 슬러그(production 위의 항목)이 CLI가 배포했을 환경과 일치해야 합니다. 이는 mastra env db create 프로젝트에 환경이 둘 이상 있는 경우 비대화형 셸에서는 환경 인수가 필요하기 때문입니다.

   :::참고 프리플라이트가 대신 하드 코딩된 로컬 경로를 보고하는 경우(Build contains a host-local storage URL)에서는 인라인 수정 옵션을 제공할 수 없습니다. 먼저 환경 변수로 경로를 보호하여 로컬 개발 중에만 파일이 사용되도록 하세요:

   src/mastra/index.ts

   new LibSQLStore({
     id: 'mastra-storage',
     // Uses the hosted database when deployed, a local file during development
     url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
     authToken: process.env.TURSO_AUTH_TOKEN,
   })

   :::

3. 달리다mastra deploy 다시 실행하세요. 사전 검사가 통과되면 빌드가 업로드되고, 배포가 라이브 상태가 될 때까지 CLI가 빌드 로그를 스트리밍합니다. 전체 빌드 및 배포에는 30초에서 몇 분 정도 걸립니다. 새 버전이 트래픽을 처리하기 시작한 경우에만 성공 메시지가 출력됩니다.

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

   경고

   설정authentication before exposing your endpoints publicly.

첫 번째 배포에서는 다음을 작성합니다..mastra-project.json 파일이 생성되어 디렉터리와 플랫폼 프로젝트를 연결합니다. 이후 배포, CI 실행 및 mastra env 명령이 추가 플래그 없이 동일한 프로젝트를 대상으로 하도록 이 파일을 커밋하세요.

다른 환경에 배포

mastra deploy목표로production environment by default. Pass --env 을 사용하여 다른 환경을 대상으로 지정하세요. 환경이 아직 존재하지 않으면 CLI에서 생성을 제안합니다:

mastra deploy --env staging

각 환경에는 별도의 URL과 환경 변수가 있습니다. 그것은 또한 자신의 것을 가질 수 있습니다hosted database.

보다Environments for the full model.

지역을 선택하세요

통과하다--region 을 사용하여 배포에서 새 환경을 생성할 때 실행 위치를 제어하세요. us or eu shorthand:

mastra deploy --env production --region eu

지역은 환경이 생성될 때 고정됩니다. 환경에 연결된 데이터베이스는 해당 환경의 지역 근처에 자동으로 배치되고 관측 가능성 데이터는 환경의 상주 영역과 일치하는 수집 지역으로 라우팅됩니다. 보다Regions 에서 지원되는 전체 리전 목록, 데이터베이스 배치 및 Observability 공동 배치에 관한 내용을 확인하세요.

비행 전 확인

Preflight는 무엇이든 포함하기 전에 빌드된 출력의 유효성을 검사하고 사용자 코드의 문제에만 플래그를 지정합니다.

• 로컬 저장소 경로: 하드 블록. 파일 지원 스토리지(예:file:./mastra.db)의 데이터는 배포할 때마다 손실됩니다. 로컬에 설정되어 있거나 플랫폼에 저장되어 있거나 관리형 데이터베이스에서 제공하는 환경 변수로 경로를 보호하면 사전 검사를 통과합니다:

  src/mastra/storage.ts

  import { LibSQLStore } from '@mastra/libsql'
  
  export const storage = new LibSQLStore({
    id: 'mastra-storage',
    // Uses the hosted database when deployed, a local file during development
    url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
    authToken: process.env.TURSO_AUTH_TOKEN,
  })

• 환경 변수가 누락되었습니다.: 코드에서 읽히지만 소스가 제공하지 않는 변수에 대한 경고입니다. 라이브러리 코드에서만 참조되는 변수는 제외됩니다.

실행 전 블록에 대해 권장되는 대응은 일반적으로 호스팅된 데이터베이스를 연결하거나 플랫폼에 변수를 저장하여 원인을 수정하는 것입니다.--skip-preflight 은 비상 수단으로 제공되지만, 손상된 배포를 방지하는 검사를 건너뜁니다.

배포하지 않고 검사를 실행합니다.

mastra lint --preflight

mastra lint로컬 env 파일만 볼 수 있습니다. 플랫폼에 저장되거나 관리형 데이터베이스에 의해 주입된 변수는 표시되지 않으므로 배포는 Lint가 여전히 오류를 보고하는 프리플라이트를 전달할 수 있습니다.

환경변수

배포는 세 가지 소스에서 환경 변수를 확인합니다.

• 관리되는 변수: 호스팅된 데이터베이스와 같은 플랫폼 리소스에 의해 주입됩니다(예:TURSO_DATABASE_URL)입니다. 플랫폼에서 이를 정의하며 사용자가 편집할 수 없습니다.
• 저장된 변수: 대시보드를 통해 프로젝트나 환경에 저장됩니다. 로컬 파일이 필요하지 않고 모든 배포에서 있는 그대로 사용됩니다.
• 로컬 환경 파일: 명시적인 배포 계층--env-file or the ambient .env and .env.local files on top.

mastra deploy --env staging --env-file .env.staging

재배포 없이 실행 중인 서비스에서 변수를 변경하려면 대시보드에서 업데이트하고 다음을 실행하세요.mastra env restart.

프로젝트 해결

모든 배포는 다음 순서로 대상 프로젝트를 해결합니다.

1. 그만큼MASTRA_PROJECT_ID environment variable
2. 그만큼--project <name|slug|id> flag
3. 그만큼.mastra-project.json file in the current directory

CI에서 설정MASTRA_PROJECT_ID and MASTRA_API_TOKEN and pass --yes:

mastra deploy --env production --yes

관련된

• 환경
• 지역
• 호스팅된 데이터베이스
• mastra deployCLI 참조
• 구성