Workers

當 worker 在 API 以外的獨立處理程序中執行時，兩者會透過 HTTP 通訊。協調 worker 會呼叫 API 的步驟執行端點，在 API 伺服器上執行 Workflow 步驟。推送模式 PubSub broker（例如採用推送模式的 Google Cloud Pub/Sub）也可以將事件直接傳送至 API 的事件端點。這是與提取模式 worker 不同的整合路徑；提取模式 worker 會自行從 broker 提取事件。設定驗證 Provider 後，這兩個 HTTP 端點都需要身分驗證。

運作方式

Worker 驗證使用與 Mastra 伺服器其他部分相同的驗證管線。協調 worker 會在每個 HTTP 請求中傳送認證資訊，而伺服器設定的 authenticateToken Provider 會加以驗證。

端點	使用者	用途
POST /api/workflows/:workflowId/runs/:runId/steps/execute	透過 HttpRemoteStrategy 的協調 worker	在 API 上執行 Workflow 步驟
POST /api/workflows/events	推送模式 broker（GCP Pub/Sub、SNS）	將 Workflow 事件傳送至 API

這兩個路由的 requiresAuth 都是 true。未設定驗證 Provider 時，可公開存取這些路由。

警告

將 worker 部署為獨立處理程序時，請一律在伺服器上設定驗證 Provider。否則，任何呼叫者都能存取步驟執行與事件端點。

設定 worker 驗證

在伺服器上設定驗證 Provider

你可以使用任何 Mastra 驗證 Provider。SimpleAuth 很適合用於 worker 權杖：

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.
})

設定 worker 權杖

在每個 worker 容器上，將 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，並透過 service mesh 或 ingress controller 終止 TLS。請參閱安全性建議。

協調 worker 會讀取 MASTRA_WORKER_AUTH_TOKEN，並在每個步驟執行請求的 Authorization 標頭中，將其作為 Bearer 權杖傳送。

驗證認證資訊類型

HttpRemoteStrategy 支援三種認證資訊格式。預設格式（bearer）可涵蓋大多數設定。

Bearer 權杖

設定 MASTRA_WORKER_AUTH_TOKEN，策略便會傳送 Authorization: Bearer <token>：

MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token

API 金鑰標頭

以 x-worker-api-key 而非 Authorization 傳送認證資訊：

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!,
  },
})

推送模式 broker 驗證

使用推送模式 PubSub（例如 Google Cloud Pub/Sub）時，broker 會將事件直接 POST 至 /api/workflows/events 端點。Broker 會附加自己的認證資訊。例如，Google Cloud Pub/Sub 會傳送由 Google 簽署的 OIDC 權杖。

驗證 Provider 的 authenticateToken 回呼必須能辨識 broker 傳送的認證資訊。請參閱 broker 文件，瞭解其使用的驗證機制。

安全性建議

• **為不同的 worker 類型使用不同權杖。**如此一來，你可以撤銷某個 worker 的存取權，而不影響其他 worker。
• **定期輪替權杖。**更新 WORKER_TOKEN 環境變數，並重新啟動受影響的容器。
• **在正式環境中使用 TLS。**Worker 與 API 之間的通訊應透過 HTTPS，以保護傳輸中的權杖。這適用於所有環境，包括 Kubernetes 叢集和 Docker 網路。使用 service mesh（例如 Istio、Linkerd）或會終止 TLS 的 ingress，以加密內部流量。
• **限制網路存取。**步驟執行與事件端點供內部使用。如有可能，請使用網路原則或防火牆規則，避免其暴露於公用網際網路。

相關內容

• 驗證概覽：可用的驗證 Provider 及其運作方式
• 權杖型驗證：權杖對使用者對應驗證
• Worker 部署：設定分離的 worker 處理程序
• Workers 參考資料：所有 worker 類型的設定詳細資料
• CLI 參考資料：mastra worker build 和 mastra worker start