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

# Workers

當 worker 在 API 以外的獨立處理程序中執行時，兩者會透過 HTTP 通訊。協調 worker 會呼叫 API 的步驟執行端點，在 API 伺服器上執行 Workflow 步驟。推送模式 PubSub broker（例如採用推送模式的 Google Cloud Pub/Sub）也可以將事件直接傳送至 API 的事件端點。這是與提取模式 worker 不同的整合路徑；提取模式 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，並透過 service mesh 或 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 網路。使用 service mesh（例如 Istio、Linkerd）或會終止 TLS 的 ingress，以加密內部流量。
- \*\*限制網路存取。\*\*步驟執行與事件端點供內部使用。如有可能，請使用網路原則或防火牆規則，避免其暴露於公用網際網路。

## 相關內容

- [驗證概覽](https://mastra.zisheng.pro/zh-TW/docs/server/auth)：可用的驗證 Provider 及其運作方式
- [權杖型驗證](https://mastra.zisheng.pro/zh-TW/docs/server/auth/simple-auth)：權杖對使用者對應驗證
- [Worker 部署](https://mastra.zisheng.pro/zh-TW/guides/deployment/mastra-workers)：設定分離的 worker 處理程序
- [Workers 參考資料](https://mastra.zisheng.pro/zh-TW/reference/workers/overview)：所有 worker 類型的設定詳細資料
- [CLI 參考資料](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)：`mastra worker build` 和 `mastra worker start`