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

# 구성

Mastra 플랫폼에 배포하면 CLI가`.mastra-project.json`config 파일을 분석하고 플랫폼 및 선택적으로 로컬에서 환경 변수를 확인합니다.`.env`파일.

이 페이지에서는 두 가지 메커니즘을 모두 설명합니다.

## 프로젝트 구성

`.mastra-project.json` 파일은 첫 번째 [`mastra deploy`](https://mastra.zisheng.pro/ko/docs/mastra-platform/deploy) 실행 시 자동으로 생성됩니다. 이 파일은 로컬 프로젝트를 플랫폼 프로젝트에 연결합니다. [GitHub 통합](https://mastra.zisheng.pro/ko/docs/mastra-platform/github)도 연결된 리포지토리에 같은 파일을 작성합니다. 후속 배포(CI 포함)에서 올바른 프로젝트를 대상으로 하도록 버전 제어에 커밋합니다.

파일은 다음과 같습니다.

```json
{
  "projectId": "06daaac4-89b1-40f0-9e3f-0993e039a627",
  "projectName": "my-project",
  "organizationId": "org_01KNA5YSP52SX4M6YVSXC2MAHP"
}
```

| 필드      | 설명                                                       |
| ------- | -------------------------------------------------------- |
| 프로젝트 ID | 프로젝트의 UUID입니다. 프로젝트가 생성될 때 할당됩니다.                        |
| 프로젝트이름  | 사람이 읽을 수 있는 프로젝트 이름입니다. 대시보드 및 CLI 출력에서 ​​표시 레이블로 사용됩니다. |
| 조직ID    | 프로젝트를 소유한 조직입니다. 모든 배포, API 키 및 리소스의 범위는 이 조직으로 지정됩니다.   |

## 환경변수

로컬 env 파일은 선택 사항입니다. [`mastra deploy`](https://mastra.zisheng.pro/ko/docs/mastra-platform/deploy)는 다음 세 가지 소스에서 변수를 결정합니다.

- **관리되는 변수**: [호스팅된 데이터베이스](https://mastra.zisheng.pro/ko/docs/mastra-platform/database)와 같은 플랫폼 리소스에서 주입됩니다. 플랫폼에서 정의하므로 편집할 수 없습니다.
- **저장된 변수**: 대시보드를 통해 프로젝트나 환경에 저장됩니다. 로컬 파일이 필요하지 않으며 모든 배포에서 그대로 사용됩니다.
- **로컬 환경 파일**: 명시적인 `--env-file` 또는 주변의 `.env` 및 `.env.local` 파일 값을 배포 구성 위에 계층화합니다. `.env.local`의 변수는 `.env`의 변수를 재정의합니다. 기본 선택에 의존하는 대신 특정 env 파일에 배포를 고정하려면 다음을 전달합니다.`--env-file`:

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

개발 전용 또는 개인 비밀이 업로드되지 않도록 배포하기 전에 로컬 env 파일을 검토하고 정리하세요.

### Observability

다음 환경 변수는 Mastra 플랫폼에서 Observability 제품을 구성합니다.

| 변수                                                                                | 설명                                                                                                                                                     |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `MASTRA_PLATFORM_ACCESS_TOKEN`                                                    | 조직 범위 액세스 토큰입니다. CLI는 Observability 프로비저닝 중 이 값을 작성하고 플랫폼 인증에 사용합니다.                                                                                   |
| `MASTRA_PROJECT_ID`                                                               | 플랫폼 프로젝트의 UUID입니다. `MastraPlatformExporter`는 이 값을 사용하여 Observability 데이터를 플랫폼 프로젝트에 연결합니다. Studio 및 Server 배포는 `.mastra-project.json`에서 프로젝트 ID를 읽습니다. |
| `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`                                          | 선택적인 Observability 엔드포인트 재정의 값입니다. 로컬 플랫폼 개발에서만 자동으로 설정됩니다. 기본값은 `https://observability.mastra.ai`입니다.                                                 |
| `MASTRA_ORG_ID`                                                                   | CLI 명령의 활성 조직을 재정의합니다. 지원되는 명령에서 `--org` 플래그로 설정할 수도 있습니다.                                                                                             |
| `MastraPlatformExporter`는 플랫폼 내보내기를 인증하기 위해 `MASTRA_PLATFORM_ACCESS_TOKEN`을 읽습니다. |                                                                                                                                                        |

## 다양한 환경

단일 프로젝트는 `production` 및 `staging`과 같은 여러 [환경](https://mastra.zisheng.pro/ko/docs/mastra-platform/environments)에서 동일한 코드베이스를 실행합니다. 각 환경에는 고유한 URL과 저장된 변수뿐 아니라 자체 배포 기록도 있습니다. 하나의 `.mastra-project.json` 파일이 모든 환경에 적용됩니다.

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

:::참고 이전 플랫폼 버전에서는 환경당 하나의 프로젝트가 필요했습니다. 환경은 해당 패턴을 대체하므로 하나의 프로젝트를 유지하고 대신 환경에 배포하세요. :::