본문으로 건너뛰기

노동자

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

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

작업자 인증 설정
작업자 인증 설정에 대한 직접 링크

서버에서 인증 공급자 구성
서버에서 인증 공급자 구성에 대한 직접 링크

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

src/mastra/index.ts
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가 인식하는 토큰으로 설정하세요.

docker-compose.yml
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
.env
WORKER_TOKEN=sk-worker-secret-token

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

인증 자격 증명 유형
인증 자격 증명 유형에 대한 직접 링크

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

무기명 토큰
무기명 토큰에 대한 직접 링크

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

MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token

API 키 헤더
API 키 헤더에 대한 직접 링크

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

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 헤더를 읽어야 합니다.

맞춤 헤더
맞춤 헤더에 대한 직접 링크

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

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 콜백은 브로커가 전송하는 자격 증명을 인식해야 합니다. 사용하는 인증 체계는 브로커 문서를 참조하세요.

보안 권장 사항
보안 권장 사항에 대한 직접 링크

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