Workers

beta

在 API 稳定之前，可能会出现无需主版本号升级的破坏性变更。

当 worker 在独立于 API 的进程中运行时，它们通过 HTTP 通信。编排 worker 调用 API 的步骤执行端点，在 API 服务器上运行工作流步骤。推送模式的 PubSub broker（例如推送模式下的 Google Cloud Pub/Sub）也可以将事件直接投递到 API 的事件端点。这是与拉取模式 worker 不同的集成路径，后者自行从 broker 拉取事件。配置了 auth 提供商时，两个 HTTP 端点都需要身份验证。

工作原理

Worker 身份验证使用与 Mastra 服务器其余部分相同的 auth 流水线。编排 worker 在每个 HTTP 请求中发送凭证，服务器配置的 authenticateToken 提供商对其进行验证。

端点	使用者	用途
POST /api/workflows/:workflowId/runs/:runId/steps/execute	编排 worker，通过 HttpRemoteStrategy	在 API 上执行工作流步骤
POST /api/workflows/events	推送模式 broker（GCP Pub/Sub、SNS）	将工作流事件投递到 API

两个路由都设置了 requiresAuth: true。未配置 auth 提供商时，它们是公开可访问的。

注意

将 worker 作为独立进程部署时，务必在服务器上配置 auth 提供商。否则，步骤执行和事件端点对任何调用方开放。

设置 worker auth

在服务器上配置 auth 提供商

使用任何 Mastra auth 提供商。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 设置为服务器 auth 提供商可识别的令牌：

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 控制器终止 TLS。参见安全建议。

编排 worker 读取 MASTRA_WORKER_AUTH_TOKEN，并在每个步骤执行请求的 Authorization 头中将其作为 Bearer 令牌发送。

Auth 凭证类型

HttpRemoteStrategy 支持三种凭证格式。默认的 bearer 覆盖大多数场景。

Bearer token

设置 MASTRA_WORKER_AUTH_TOKEN，策略会发送 Authorization: Bearer <token>：

MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token

API key 头

将凭证作为 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 提供商必须读取 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 auth

使用推送模式 PubSub（例如 Google Cloud Pub/Sub）时，broker 直接将事件 POST 到 /api/workflows/events 端点。broker 会附加自己的凭证。例如，Google Cloud Pub/Sub 会发送 Google 签名的 OIDC 令牌。

auth 提供商的 authenticateToken 回调必须识别 broker 发送的任何凭证。关于其使用的身份验证方案，请参阅 broker 的文档。

安全建议

• 为不同 worker 类型使用不同令牌。 这让你能够撤销某个 worker 的访问权限而不影响其他 worker。
• 定期轮换令牌。 更新 WORKER_TOKEN 环境变量并重启受影响的容器。
• 生产环境使用 TLS。 Worker 到 API 的通信应通过 HTTPS 进行，以保护传输中的令牌。这适用于所有环境，包括 Kubernetes 集群和 Docker 网络。使用服务网格（如 Istio、Linkerd）或终止 TLS 的 ingress 来加密内部流量。
• 限制网络访问。 步骤执行和事件端点是内部端点。如有可能，使用网络策略或防火墙规则使其不暴露在公网。

相关内容

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