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

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

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

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

```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，並透過 service mesh 或 ingress controller 終止 TLS。請參閱[安全建議](#security-recommendations)。

編排 Worker 會讀取 `MASTRA_WORKER_AUTH_TOKEN`，並以 `Bearer` token 的形式，在每個步驟執行請求的 `Authorization` header 中傳送。

## 身份驗證憑證類型

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

### Bearer token

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

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

### API 金鑰 header

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

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

### 自訂 header

使用任何 header 名稱和值：

```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` 端點，並附上本身的憑證。例如，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，避免這些端點暴露於公眾互聯網。

## 相關內容

- [身份驗證概覽](https://mastra.zisheng.pro/zh-HK/docs/server/auth)：可用的 auth provider 及其運作方式
- [Token 身份驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth/simple-auth)：使用 token 至使用者映射進行身份驗證
- [Worker 部署](https://mastra.zisheng.pro/zh-HK/guides/deployment/mastra-workers)：設定分拆的 Worker 程序
- [Workers 參考資料](https://mastra.zisheng.pro/zh-HK/reference/workers/overview)：所有 Worker 類型的設定詳情
- [CLI 參考資料](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)：`mastra worker build` 和 `mastra worker start`