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

# Mastra 플랫폼에 배포

[`mastra deploy`](https://mastra.zisheng.pro/ko/reference/cli/mastra)Mastra 애플리케이션을 릴리스하기 위한 단일 명령입니다.[마스트라 플랫폼](https://mastra.zisheng.pro/ko/docs/mastra-platform/overview).

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

```bash
mastra deploy
```

:::참고 이 페이지에서는 통합 배포 흐름을 다룹니다. 이전 분할 명령은[`mastra server deploy`](https://mastra.zisheng.pro/ko/docs/mastra-platform/server) and [`mastra studio deploy`](https://mastra.zisheng.pro/ko/docs/mastra-platform/studio), still work but `mastra deploy`권장 경로입니다. :::

## 시작하기 전에

당신은[Mastra application](https://mastra.zisheng.pro/ko/guides/getting-started/quickstart) and a [Mastra platform](https://projects.mastra.ai) 계정입니다. 인증되지 않은 경우 CLI는 처음 사용할 때 로그인하라는 메시지를 표시합니다.

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

## 첫 번째 배포

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

   ```bash
   mastra deploy
   ```

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

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

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

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

   ```text
   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는 이전 동작으로 대체하여 직접 실행할 정확한 명령을 출력합니다.

   ```bash
   mastra env db create production --kind turso
   ```

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

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

   ```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](https://mastra.zisheng.pro/ko/docs/server/auth) before exposing your endpoints publicly.

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

## 다른 환경에 배포

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

```bash
mastra deploy --env staging
```

각 환경에는 별도의 URL과 환경 변수가 있습니다. 그것은 또한 자신의 것을 가질 수 있습니다[hosted database](https://mastra.zisheng.pro/ko/docs/mastra-platform/database).

보다[Environments](https://mastra.zisheng.pro/ko/docs/mastra-platform/environments) for the full model.

## 지역을 선택하세요

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

```bash
mastra deploy --env production --region eu
```

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

## 비행 전 확인

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

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

  ```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` 은 비상 수단으로 제공되지만, 손상된 배포를 방지하는 검사를 건너뜁니다.

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

```bash
mastra lint --preflight
```

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

## 환경변수

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

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

```bash
mastra deploy --env staging --env-file .env.staging
```

재배포 없이 실행 중인 서비스에서 변수를 변경하려면 대시보드에서 업데이트하고 다음을 실행하세요.[`mastra env restart`](https://mastra.zisheng.pro/ko/reference/cli/mastra).

## 프로젝트 해결

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

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`:

```bash
mastra deploy --env production --yes
```

## 관련된

- [환경](https://mastra.zisheng.pro/ko/docs/mastra-platform/environments)
- [지역](https://mastra.zisheng.pro/ko/docs/mastra-platform/regions)
- [호스팅된 데이터베이스](https://mastra.zisheng.pro/ko/docs/mastra-platform/database)
- [`mastra deploy`CLI 참조](https://mastra.zisheng.pro/ko/reference/cli/mastra)
- [구성](https://mastra.zisheng.pro/ko/docs/mastra-platform/configuration)