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

# 노동자

작업자가 API와 별도의 프로세스에서 실행되면 HTTP를 통해 통신합니다. 오케스트레이션 작업자는 API의 단계 실행 엔드포인트를 호출하여 API 서버에서 Workflow 단계를 실행합니다. 푸시 모드 PubSub 브로커(예: 푸시 모드의 Google Cloud Pub/Sub)도 API의 이벤트 엔드포인트에 직접 이벤트를 전달할 수 있습니다. 이는 브로커 자체에서 이벤트를 가져오는 풀 모드 작업자와는 별개의 통합 경로입니다. 인증 공급자가 구성되면 두 HTTP 끝점 모두 인증이 필요합니다.

## 작동 원리

작업자 인증은 나머지 Mastra 서버와 동일한 인증 파이프라인을 사용합니다. 오케스트레이션 작업자는 각 HTTP 요청과 함께 자격 증명을 보내고 서버가 구성한`authenticateToken` provider validates them.

| 엔드포인트                                                                             | 사용자                                    | 목적                    |
| --------------------------------------------------------------------------------- | -------------------------------------- | --------------------- |
| `POST /api/workflows/:workflowId/runs/:runId/steps/execute`                       | `HttpRemoteStrategy`를 사용하는 오케스트레이션 작업자 | API에서 Workflow 단계를 실행 |
| `POST /api/workflows/events`                                                      | 푸시 모드 브로커(GCP Pub/Sub, SNS)            | API에 Workflow 이벤트 전달  |
| 두 경로 모두 `requiresAuth: true`로 설정되어 있습니다. 인증 Provider를 구성하지 않으면 공개적으로 액세스할 수 있습니다. |                                        |                       |

> **경고:** 작업자를 별도의 프로세스로 배포하는 경우 항상 서버에 인증 공급자를 구성하세요. 이것이 없으면 단계 실행 및 이벤트 엔드포인트가 모든 호출자에게 공개됩니다.

## 작업자 인증 설정

### 서버에서 인증 공급자 구성

Mastra 인증 Provider를 사용하세요. 작업자 토큰에는 `SimpleAuth`가 적합합니다.

```typescript
import { Mastra } from '@mastra/core/mastra'
import { SimpleAuth } from '@mastra/core/server'

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      tokens: {
        [process.env.WORKER_TOKEN!]: {
          id: 'worker',
          name: 'Orchestration Worker',
          role: 'worker',
        },
      },
    }),
  },
  // ... storage, pubsub, etc.
})
```

### 작업자 토큰 설정

각 작업자 컨테이너에서 `MASTRA_WORKER_AUTH_TOKEN`을 서버의 인증 Provider가 인식하는 토큰으로 설정하세요.

```yaml
services:
  api:
    environment:
      WORKER_TOKEN: ${WORKER_TOKEN}
      # ... other env vars

  orchestration-worker:
    environment:
      MASTRA_WORKER_AUTH_TOKEN: ${WORKER_TOKEN}
      MASTRA_STEP_EXECUTION_URL: http://api:4111/api # Use HTTPS in production
      # ... other env vars
```

```bash
WORKER_TOKEN=sk-worker-secret-token
```

이 예제에서는 로컬 개발을 위해 `http://`를 사용합니다. 프로덕션에서는 HTTPS URL을 사용하고 서비스 메시 또는 인그레스 컨트롤러로 TLS를 종료하세요. [보안 권장 사항](#security-recommendations)을 참조하세요. 오케스트레이션 작업자는 `MASTRA_WORKER_AUTH_TOKEN`을 읽고 모든 단계 실행 요청의 `Authorization` 헤더에서 `Bearer` 토큰으로 전송합니다.

## 인증 자격 증명 유형

`HttpRemoteStrategy`는 세 가지 자격 증명 형식을 지원합니다. 기본값(`bearer`)은 대부분의 설정에 적합합니다.

### 무기명 토큰

`MASTRA_WORKER_AUTH_TOKEN`을 설정하면 전략에서 `Authorization: Bearer <token>`을 전송합니다.

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

### API 키 헤더

자격 증명을 `Authorization` 대신 `x-worker-api-key`로 전송합니다.

```typescript
import { HttpRemoteStrategy } from '@mastra/core/worker'

const strategy = new HttpRemoteStrategy({
  serverUrl: 'http://api:4111/api', // Use HTTPS in production
  auth: { type: 'api-key', key: process.env.WORKER_API_KEY! },
})
```

이 자격 증명을 검증하려면 서버의 인증 Provider가 `x-worker-api-key` 헤더를 읽어야 합니다.

### 맞춤 헤더

헤더 이름과 값을 사용하십시오.

```typescript
import { HttpRemoteStrategy } from '@mastra/core/worker'

const strategy = new HttpRemoteStrategy({
  serverUrl: 'http://api:4111/api', // Use HTTPS in production
  auth: {
    type: 'header',
    name: 'X-Internal-Service-Key',
    value: process.env.INTERNAL_KEY!,
  },
})
```

## 푸시 모드 브로커 인증

푸시 모드 PubSub(예: Google Cloud Pub/Sub)를 사용하는 경우 브로커가 이벤트를 `/api/workflows/events` 엔드포인트에 직접 게시합니다. 브로커는 자체 자격 증명을 첨부합니다. 예를 들어 Google Cloud Pub/Sub는 Google이 서명한 OIDC 토큰을 전송합니다. 인증 Provider의 `authenticateToken` 콜백은 브로커가 전송하는 자격 증명을 인식해야 합니다. 사용하는 인증 체계는 브로커 문서를 참조하세요.

## 보안 권장 사항

- **작업자 유형마다 서로 다른 토큰을 사용하세요.**&#xC774;렇게 하면 다른 작업자에게 영향을 주지 않고 특정 작업자의 액세스 권한을 취소할 수 있습니다.
- **정기적으로 토큰을 교체하세요.**&#xC5C5;데이트된 `WORKER_TOKEN` 환경 변수를 적용하고 영향을 받는 컨테이너를 다시 시작하세요.
- **프로덕션에서는 TLS를 사용하세요.**&#xC791;업자와 API 간 통신은 전송 중인 토큰을 보호할 수 있도록 HTTPS를 통해 이루어져야 합니다. 이는 Kubernetes 클러스터와 Docker 네트워크를 포함한 모든 환경에 적용됩니다. 서비스 메시(예: Istio, Linkerd) 또는 TLS 종료 인그레스를 사용하여 내부 트래픽을 암호화하세요.
- **네트워크 액세스를 제한하세요.**&#xB2E8;계 실행 및 이벤트 엔드포인트는 내부용입니다. 가능한 경우 네트워크 정책이나 방화벽 규칙을 사용하여 공개 인터넷에서의 액세스를 차단하세요.

## 관련된

- [인증 개요](https://mastra.zisheng.pro/ko/docs/server/auth): 사용 가능한 인증 Provider와 작동 방식
- [토큰 기반 인증](https://mastra.zisheng.pro/ko/docs/server/auth/simple-auth): 토큰-사용자 매핑 인증
- [작업자 배포](https://mastra.zisheng.pro/ko/guides/deployment/mastra-workers): 분리된 작업자 프로세스 설정
- [작업자 레퍼런스](https://mastra.zisheng.pro/ko/reference/workers/overview): 모든 작업자 유형의 구성 세부 정보
- [CLI 레퍼런스](https://mastra.zisheng.pro/ko/reference/cli/mastra): `mastra worker build` 및 `mastra worker start`