Workers

当 Worker 在与 API 不同的进程中运行时，它们通过 HTTP 进行通信。编排 Worker 会调用 API 的步骤执行端点，在 API 服务器上运行 Workflow 步骤。推送模式的 PubSub broker（例如采用推送模式的 Google Cloud Pub/Sub）也可以将事件直接传递到 API 的事件端点。这与拉取模式 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，并通过服务网格或 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 网络。请使用服务网格（例如 Istio、Linkerd）或终止 TLS 的 ingress 来加密内部流量。
• 限制网络访问。 步骤执行端点和事件端点属于内部端点。如有可能，请使用网络策略或防火墙规则阻止其暴露在公共互联网上。

相关内容

• 身份验证概览：可用的身份验证 Provider 及其工作原理
• 基于令牌的身份验证：令牌到用户映射身份验证
• Worker 部署：设置拆分的 Worker 进程
• Workers 参考：所有 Worker 类型的配置详情
• CLI 参考：mastra worker build 和 mastra worker start