> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 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 令牌：

```typescript
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 能识别的令牌：

```yaml
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
```

```bash
WORKER_TOKEN=sk-worker-secret-token
```

这些示例在本地开发中使用 `http://`。在生产环境中，请使用 HTTPS URL，并通过服务网格或 ingress controller 终止 TLS。请参阅[安全建议](#security-recommendations)。

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

## 身份验证凭据类型

`HttpRemoteStrategy` 支持三种凭据格式。默认格式（`bearer`）适用于大多数设置。

### Bearer 令牌

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

```bash
MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token
```

### API 密钥标头

通过 `x-worker-api-key` 而非 `Authorization` 发送凭据：

```typescript
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` 标头才能验证此凭据。

### 自定义标头

使用任意标头名称和值：

```typescript
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 来加密内部流量。
- **限制网络访问。** 步骤执行端点和事件端点属于内部端点。如有可能，请使用网络策略或防火墙规则阻止其暴露在公共互联网上。

## 相关内容

- [身份验证概览](https://mastra.zisheng.pro/docs/server/auth)：可用的身份验证 Provider 及其工作原理
- [基于令牌的身份验证](https://mastra.zisheng.pro/docs/server/auth/simple-auth)：令牌到用户映射身份验证
- [Worker 部署](https://mastra.zisheng.pro/guides/deployment/mastra-workers)：设置拆分的 Worker 进程
- [Workers 参考](https://mastra.zisheng.pro/reference/workers/overview)：所有 Worker 类型的配置详情
- [CLI 参考](https://mastra.zisheng.pro/reference/cli/mastra)：`mastra worker build` 和 `mastra worker start`