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

# Workers

有關使用模式及部署拓撲，請參閱 [Workers](https://mastra.zisheng.pro/zh-HK/docs/deployment/workers)。

## 環境變數

### `MASTRA_WORKERS`

控制在目前程序中啟動哪些 Workers。

| 值                           | 行為                                                                       |
| --------------------------- | ------------------------------------------------------------------------ |
| _（未設定）_                     | 根據設定自動建立預設 Workers                                                       |
| `"false"`                   | 停用 Worker 事件處理。程序會繼續處理 HTTP 請求，亦可將事件發佈至 PubSub（例如啟動 Workflow），但不會取用這些事件。 |
| `"orchestration"`           | 只啟動編排 Worker                                                             |
| `"scheduler"`               | 只啟動排程 Worker                                                             |
| `"backgroundTasks"`         | 只啟動背景任務 Worker                                                           |
| `"orchestration,scheduler"` | 多個 Workers（以逗號分隔）                                                        |

使用此變數，即可透過同一個建置產物，在不同容器中執行不同類型的 Worker。

### `MASTRA_STEP_EXECUTION_URL`

API 伺服器的基礎 URL，供編排 Worker 遙距執行 Workflow 步驟。當編排 Worker 與 API 在不同程序中執行時，必須設定此變數。

```text
MASTRA_STEP_EXECUTION_URL=http://api:4111/api
```

在生產環境中請使用 HTTPS URL。請參閱[安全建議](https://mastra.zisheng.pro/zh-HK/docs/server/auth/workers)。

編排 Worker 會將步驟執行請求傳送至：

```text
${MASTRA_STEP_EXECUTION_URL}/workflows/:workflowId/runs/:runId/steps/execute
```

### `MASTRA_WORKER_AUTH_TOKEN`

編排 Worker 呼叫 API 的步驟執行端點時所傳送的 bearer token。API 設定的身份驗證 Provider 必須能識別此 token。請參閱 [Worker 身份驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth/workers)。

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

## Worker 類型

### OrchestrationWorker

處理來自 PubSub `workflows` topic 的 Workflow 事件。必須配置支援 pull subscription 的 PubSub，例如 `@mastra/redis-streams` 或 `@mastra/google-cloud-pubsub`。

- **名稱**：`orchestration`
- **PubSub topic**：`workflows`
- **Consumer group**：`mastra-orchestration`

### SchedulerWorker

輪詢儲存空間中已到期的 cron 排程，並發佈 `workflow.start` 事件。

- **名稱**：`scheduler`
- **只限單一執行個體**：只執行一個執行個體，以免重複觸發

### BackgroundTaskWorker

執行由 Agent 分派的背景 Tool 呼叫。

- **名稱**：`backgroundTasks`
- **PubSub topic**：`background-tasks`
- **Consumer group**：`background-task-workers`
- **支援多個副本**：各執行個體共用同一個 Consumer group

## 支援的儲存後端

如要在部署中執行所有 Worker 類型，儲存後端必須實作 `workflows`、`backgroundTasks` 及 `schedules` domain。SchedulerWorker 尤其需要 `schedules` domain。如果你不使用排程 Workflow，沒有實作此 domain 的後端仍可支援編排及背景任務。以下後端支援全部三個 domain：

| 後端         | 依賴套件                                                                            |
| ---------- | ------------------------------------------------------------------------------- |
| PostgreSQL | [`@mastra/pg`](https://mastra.zisheng.pro/zh-HK/reference/storage/postgresql)   |
| LibSQL     | [`@mastra/libsql`](https://mastra.zisheng.pro/zh-HK/reference/storage/libsql)   |
| MySQL      | `@mastra/mysql`                                                                 |
| MongoDB    | [`@mastra/mongodb`](https://mastra.zisheng.pro/zh-HK/reference/storage/mongodb) |
| Spanner    | [`@mastra/spanner`](https://mastra.zisheng.pro/zh-HK/reference/storage/spanner) |
| Convex     | [`@mastra/convex`](https://mastra.zisheng.pro/zh-HK/reference/storage/convex)   |

其他儲存後端（Upstash、DynamoDB、Cloudflare D1、ClickHouse、Redis）支援 Workflow 及部分 Worker 功能，但並未實作 `schedules` domain。如果不部署排程器，仍可將它們用於編排及背景任務 Worker。