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

# Workers

如需使用模式與部署拓撲的說明，請參閱 [Workers](https://mastra.zisheng.pro/zh-TW/docs/deployment/workers)。

## 環境變數

### `MASTRA_WORKERS`

控制目前處理程序要啟動哪些 worker。

| 值                           | 行為                                                                          |
| --------------------------- | --------------------------------------------------------------------------- |
| _（未設定）_                     | 根據設定自動建立預設 worker                                                           |
| `"false"`                   | 停用 worker 事件處理。此處理程序仍會處理 HTTP 要求，並可將事件（例如 Workflow 啟動事件）發布至 PubSub，但不會取用事件。 |
| `"orchestration"`           | 僅啟動 orchestration worker                                                    |
| `"scheduler"`               | 僅啟動 scheduler worker                                                        |
| `"backgroundTasks"`         | 僅啟動 background task worker                                                  |
| `"orchestration,scheduler"` | 多個 worker（以逗號分隔）                                                            |

使用此變數，即可從同一份建置產物在不同容器中執行不同類型的 worker。

### `MASTRA_STEP_EXECUTION_URL`

API 伺服器的基底 URL，由 orchestration worker 用來從遠端執行 Workflow step。當 orchestration worker 與 API 分別在不同處理程序中執行時，必須設定此變數。

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

正式環境請使用 HTTPS URL。詳情請參閱[安全性建議](https://mastra.zisheng.pro/zh-TW/docs/server/auth/workers)。

orchestration worker 會將 step 執行要求傳送至：

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

### `MASTRA_WORKER_AUTH_TOKEN`

orchestration worker 呼叫 API 的 step 執行端點時所傳送的 bearer token。API 所設定的驗證 Provider 必須能辨識此 token。詳情請參閱 [Worker 驗證](https://mastra.zisheng.pro/zh-TW/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

輪詢 storage 中已到期的 cron 排程，並發布 `workflow.start` 事件。

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

### BackgroundTaskWorker

執行 Agent 派送的背景 Tool 呼叫。

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

## 支援的 storage 後端

若部署會執行所有類型的 worker，就必須使用實作 `workflows`、`backgroundTasks` 與 `schedules` domain 的 storage 後端。SchedulerWorker 尤其需要 `schedules` domain。若不使用排程 Workflow，缺少此 domain 的後端仍可支援協調與背景工作。下列後端支援全部三種 domain：

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

其他 storage 後端（Upstash、DynamoDB、Cloudflare D1、ClickHouse、Redis）支援 Workflow 與部分 worker 功能，但缺少 `schedules` domain。如果不部署 scheduler，仍可將這些後端用於 orchestration 與 background task worker。