Workers

當 Workers 在 API 以外的獨立程序中運行時，便會透過 HTTP 通訊。編排 Worker 會呼叫 API 的步驟執行端點，在 API 伺服器上執行 Workflow 步驟。推送模式的 PubSub broker（例如採用推送模式的 Google Cloud Pub/Sub）亦可直接將事件傳送至 API 的事件端點。這是有別於拉取模式 Workers 的整合路徑；拉取模式 Workers 會自行從 broker 拉取事件。設定 auth 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。如未設定 auth provider，任何人均可公開存取這些路由。

注意

將 Workers 部署為獨立程序時，請務必在伺服器上設定 auth provider。否則，任何呼叫者均可存取步驟執行及事件端點。

設定 Worker 身份驗證

在伺服器上設定 auth provider

你可以使用任何 Mastra auth provider。SimpleAuth 很適合用於 Worker token：

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 token

在每個 Worker 容器中，將 MASTRA_WORKER_AUTH_TOKEN 設為伺服器 auth provider 可識別的 token：

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，並以 Bearer token 的形式，在每個步驟執行請求的 Authorization header 中傳送。

身份驗證憑證類型

HttpRemoteStrategy 支援三種憑證格式。預設格式（bearer）適用於大部分設定。

Bearer token

設定 MASTRA_WORKER_AUTH_TOKEN 後，strategy 便會傳送 Authorization: Bearer <token>：

MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token

API 金鑰 header

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

伺服器的 auth provider 必須讀取 x-worker-api-key header，才能驗證此憑證。

自訂 header

使用任何 header 名稱和值：

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 端點，並附上本身的憑證。例如，Google Cloud Pub/Sub 會傳送由 Google 簽署的 OIDC token。

auth provider 的 authenticateToken callback 必須能夠識別 broker 傳送的憑證。請參閱 broker 的文件，了解其使用的身份驗證機制。

安全建議

• 為不同類型的 Worker 使用不同 token。 這樣你便可以撤銷某個 Worker 的存取權，而不會影響其他 Workers。
• 定期輪替 token。 更新 WORKER_TOKEN 環境變數，然後重新啟動受影響的容器。
• 在生產環境中使用 TLS。 Worker 與 API 之間的通訊應透過 HTTPS 進行，以保障傳輸中的 token。這適用於所有環境，包括 Kubernetes cluster 和 Docker 網絡。請使用 service mesh（例如 Istio、Linkerd）或終止 TLS 的 ingress，為內部流量加密。
• 限制網絡存取。 步驟執行及事件端點屬於內部端點。如情況許可，請使用 network policy 或 firewall rule，避免這些端點暴露於公眾互聯網。

相關內容

• 身份驗證概覽：可用的 auth provider 及其運作方式
• Token 身份驗證：使用 token 至使用者映射進行身份驗證
• Worker 部署：設定分拆的 Worker 程序
• Workers 參考資料：所有 Worker 類型的設定詳情
• CLI 參考資料：mastra worker build 和 mastra worker start