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

# 노동자

사용 패턴 및 배포 토폴로지는 다음을 참조하세요.[Workers](https://mastra.zisheng.pro/ko/docs/deployment/workers).

## 환경변수

### `MASTRA_WORKERS`

현재 프로세스에서 시작할 작업자를 제어합니다.

| 값                                                 | 동작                                                                                                  |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| _(설정하지 않음)_                                       | 구성에 따라 기본 Worker가 자동으로 생성됩니다                                                                        |
| `"false"`                                         | Worker 이벤트 처리를 비활성화합니다. 프로세스는 HTTP 요청을 처리하며, 이벤트를 소비하지 않고도 PubSub에 이벤트(예: Workflow 시작)를 게시할 수 있습니다. |
| `"orchestration"`                                 | 오케스트레이션 Worker만 시작합니다                                                                               |
| `"scheduler"`                                     | 스케줄러 Worker만 시작합니다                                                                                  |
| `"backgroundTasks"`                               | 백그라운드 작업 Worker만 시작합니다                                                                              |
| `"orchestration,scheduler"`                       | 여러 Worker를 시작합니다(쉼표로 구분)                                                                            |
| 이를 사용하여 동일한 빌드 아티팩트의 별도 컨테이너에서 다양한 작업자 유형을 실행합니다. |                                                                                                     |

### `MASTRA_STEP_EXECUTION_URL`

오케스트레이션 작업자가 원격으로 Workflow 단계를 실행하는 데 사용하는 API 서버의 기본 URL입니다. 오케스트레이션 작업자가 API와 별도의 프로세스에서 실행되는 경우 필요합니다.

```text
MASTRA_STEP_EXECUTION_URL=http://api:4111/api
```

프로덕션에서는 HTTPS URL을 사용하세요. 보다[Security recommendations](https://mastra.zisheng.pro/ko/docs/server/auth/workers).

오케스트레이션 작업자는 다음 대상으로 단계 실행 요청을 보냅니다.

```text
${MASTRA_STEP_EXECUTION_URL}/workflows/:workflowId/runs/:runId/steps/execute
```

### `MASTRA_WORKER_AUTH_TOKEN`

API의 단계 실행 엔드포인트를 호출할 때 오케스트레이션 작업자가 보낸 전달자 토큰입니다. API에 구성된 인증 공급자는 이 토큰을 인식해야 합니다. 보다[Worker authentication](https://mastra.zisheng.pro/ko/docs/server/auth/workers).

```text
MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token
```

## 작업자 유형

### 오케스트레이션작업자

PubSub의 `workflows` 토픽에서 Workflow 이벤트를 처리합니다. 풀 구독으로 구성된 `@mastra/redis-streams` 또는 `@mastra/google-cloud-pubsub`처럼 풀을 지원하는 PubSub가 필요합니다.

- **이름**: `orchestration`
- **PubSub 주제**: `workflows`
- **소비자 그룹**: `mastra-orchestration`

### 스케줄러작업자

예정된 크론 일정 및 게시를 위해 스토리지를 폴링합니다.`workflow.start` events.

- **이름**: `scheduler`
- **단일 인스턴스만 해당**: 중복 발생을 방지하려면 정확히 하나의 인스턴스를 실행하세요.

### 배경작업작업자

Agent가 디스패치한 백그라운드 Tool 호출을 실행합니다.

- **이름**: `backgroundTasks`
- **PubSub 주제**: `background-tasks`
- **소비자 그룹**: `background-task-workers`
- **여러 복제본 지원**: 인스턴스는 소비자 그룹을 공유합니다.

## 지원되는 스토리지 백엔드

모든 Worker 유형을 실행하는 배포에는 `workflows`, `backgroundTasks`, `schedules` 도메인을 구현하는 스토리지 백엔드가 필요합니다. `schedules` 도메인은 SchedulerWorker에 특별히 필요합니다. 예약된 Workflow를 사용하지 않는다면 이 도메인이 없는 백엔드도 오케스트레이션 및 백그라운드 작업을 지원할 수 있습니다. 다음 백엔드는 세 도메인을 모두 지원합니다.

| 백엔드      | 패키지                                                                          |
| -------- | ---------------------------------------------------------------------------- |
| 포스트그레SQL | [`@mastra/pg`](https://mastra.zisheng.pro/ko/reference/storage/postgresql)   |
| LibSQL   | [`@mastra/libsql`](https://mastra.zisheng.pro/ko/reference/storage/libsql)   |
| MySQL    | `@mastra/mysql`                                                              |
| MongoDB  | [`@mastra/mongodb`](https://mastra.zisheng.pro/ko/reference/storage/mongodb) |
| Spanner  | [`@mastra/spanner`](https://mastra.zisheng.pro/ko/reference/storage/spanner) |
| Convex   | [`@mastra/convex`](https://mastra.zisheng.pro/ko/reference/storage/convex)   |

다른 스토리지 백엔드(Upstash, DynamoDB, Cloudflare D1, ClickHouse, Redis)는 Workflow와 일부 Worker 기능을 지원하지만 `schedules` 도메인은 지원하지 않습니다. 스케줄러를 배포하지 않는다면 오케스트레이션 및 백그라운드 작업 Worker에 계속 사용할 수 있습니다.