> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/zh/mo-kuai-8-kai-fa-yu-devops/06-task-engine.md).

# 任务引擎与 Webhooks

VergeOS 平台 **任务引擎** 是一个内置自动化框架，可在无需外部工具的情况下实现事件驱动和计划驱动操作。与编写脚本或依赖在独立机器上运行的 cron 任务不同，管理员可以定义任务、附加触发器，并让平台自动执行操作。任务引擎是本模块前面介绍的 API 和 IaC 工具的原生补充——Terraform 和 Ansible 负责资源配置，而任务引擎负责运行系统中的日常运维自动化。

## 任务引擎组件

任务引擎使用六个模块化构建块，可灵活组合：

| 组件          | 说明                           |
| ----------- | ---------------------------- |
| **任务**      | 定义要执行的操作（例如，关闭虚拟机、发送通知）      |
| **计划**      | 指定任务运行的时间和频率（例如，每天、每周、一次性）   |
| **事件**      | 定义触发任务的条件（例如，用户登录、同步失败）      |
| **Webhook** | 通过 HTTP POST 实时将数据推送到外部系统    |
| **脚本**      | 在任务仪表板中展示的可编程自动化构建块（见下方脚本部分） |
| **任务日志**    | 记录任务创建和执行历史，用于审计和故障排查        |

所有组件均可通过 **系统 → 任务仪表板** 在 VergeOS 界面中访问。

```mermaid
flowchart LR
    子图 触发器
        E[事件触发器<br/>用户登录，同步错误]
        S[计划触发器<br/>每天、每周、一次性]
    end

    子图 操作
        T1[任务：开启虚拟机]
        T2[任务：发送电子邮件]
        T3[任务：发送 Webhook]
    end

    子图 外部系统
        SL[Slack 频道]
        EM[电子邮件 / SMTP]
        ZP[Zapier / 监控]
    end

    E --> T1
    E --> T2
    E --> T3
    S --> T1
    S --> T2
    T3 --> SL
    T3 --> ZP
    T2 --> EM
```

## 模块化自动化架构

任务引擎的一大优势是其 **多对多** 关系模型。组件不是一对一绑定：

* **多个任务或事件 → 单个 webhook** —— 配置一次 webhook，即可由多个不同事件触发它（同步失败、登录尝试、系统告警）。这将外部集成集中化并减少重复。
* **单个任务 → 多个事件** —— “开启虚拟机”任务可以在特定用户登录时触发 *或* 也可以在计划维护窗口开始时触发。在不同场景间复用任务定义。
* **单个计划 → 多个任务** —— 只需定义一次每周维护窗口，并将其关联到更新、告警和关机任务。保持一致性，避免配置漂移。

这种可组合设计意味着，您可以构建一个可复用的任务、计划和 webhook 库，然后随着运维需求演进将它们连接起来。

## 基于事件的触发器

当检测到特定系统事件时，事件触发器会自动执行任务。创建事件时，您需要选择：

1. **类型** —— 对象类别（例如，用户、虚拟机、告警、租户、外发同步）
2. **事件** —— 具体发生的事件（例如，登录、注销、开机、错误、状态变更）
3. **对象实例或标签** —— 可以是特定对象（某个用户或虚拟机），也可以是与一组对象匹配的标签

### 常见事件触发模式

| 事件类型 | 示例事件    | 典型操作                        |
| ---- | ------- | --------------------------- |
| 用户   | 登录 / 注销 | 为已登录用户开启/关闭 GPU 虚拟机         |
| 外发同步 | 错误      | 发送 Slack 通知 + 电子邮件告警        |
| 虚拟机  | 开机 / 关机 | 通过 webhook 记录到外部监控系统        |
| 告警   | 错误严重级别  | 向运维团队发送电子邮件通知               |
| 告警   | 已触发     | 向 PagerDuty 或值班轮转发送 webhook |

{% hint style="success" %}
**基于标签的触发器**

不要为每台虚拟机分别创建事件，而是分配一个共享的 **标签** （例如， `gpu-workstation`）给相关虚拟机。然后配置事件触发器匹配该标签——任何带有该标签的虚拟机都会激活触发器。这比按对象逐个创建事件更易维护。
{% endhint %}

## 基于计划的触发器

计划触发器会在预定义的时间或间隔运行任务。VergeOS 包含多个默认计划，并支持创建自定义计划。

### 计划配置选项

* **周期性** —— 每 N 天、小时、分钟、周、月或年重复一次，并可选择具体日期/时间
* **一次性** —— 选择“不重复”，并指定单个开始日期和时间
* **结束日期** —— 周期性计划默认永久有效；也可设置结束日期

### 常见计划模式

| 计划        | 使用场景              |
| --------- | ----------------- |
| 每周六下午 5 点 | 检查并下载系统更新         |
| 每周五下午 6 点 | 在工作结束时关闭资源密集型虚拟机  |
| 未来某个具体日期  | 在创建 30 天后禁用临时员工账户 |
| 每天午夜      | 运行租户备份验证检查        |
| 每月第一天     | 生成资源利用率报告         |

## Webhook

Webhook 使任务执行时可向外部系统进行推送式消息传递。外部系统无需轮询 VergeOS 获取状态；当满足配置条件时，平台会主动向预定义 URL 发送 HTTP POST 请求。

### Webhook 配置

创建 webhook 时，您需要配置：

| 字段          | 说明                                                 |
| ----------- | -------------------------------------------------- |
| **名称**      | webhook 的描述性标识                                     |
| **URL**     | 外部系统上接受 HTTP POST 请求的 API 端点                       |
| **授权类型**    | Bearer Token、API Key、Basic（用户名/密码）或无               |
| **请求头**     | 自定义 HTTP 请求头（默认： `content-type: application/json`) |
| **允许不安全证书** | 适用于开发/测试环境中的自签名证书                                  |
| **超时**      | 等待响应的最长秒数（最少 3 秒）                                  |
| **重试**      | 失败或无响应时的重试次数                                       |

### 负载变量

Webhook 任务负载支持在执行时解析的动态变量：

| 可变             | 值                                                    |
| -------------- | ---------------------------------------------------- |
| `${DATE}`      | 当前日期/时间的完整字符串格式（例如， `Thu, 16 Oct 2025 11:38:07 EDT`) |
| `${TIMESTAMP}` | 当前日期/时间的 Unix 时间戳整数（例如， `1760629087`)                |
| `${RANDOM}`    | 随机生成的整数                                              |
| `${NAME}`      | 适用的 VergeOS 对象名称                                     |

### Webhook 使用场景

* 发送一个 **Slack 通知** 当同步任务产生错误时发送到管理员频道
* 发布到一个 **会计系统** 当租户上线时，触发自动计费
* 触发一个 **Zapier 工作流** 当特定虚拟机开机时，启动跨应用操作

## 示例 1：GPU 虚拟机自动开机/关机

该示例展示标签、任务、事件和计划如何协同管理资源密集型 GPU 工作负载。

**场景：** 用户 JThompson 使用多台配备 GPU 的虚拟机进行 3D 建模。这些虚拟机消耗大量计算和内存——在空闲时让它们继续运行是一种浪费。

**目标：** 当 JThompson 登录时开启这些虚拟机，注销时关闭它们，并通过周五下午 6 点的关机作为安全保障。

### 配置步骤

1. **创建标签** —— 在 系统 → 标签 下创建一个类别 `虚拟机` 并使用标签 `JThompson-GPU`。将此标签分配给目标虚拟机。
2. **创建“开机”任务** —— 系统 → 任务仪表板 → 新任务。将对象类型设置为 `虚拟机`，选择标签 `JThompson-GPU`，并将操作设置为 `开机`.
3. **添加登录事件触发器** —— 在任务仪表板中添加事件触发器：类型 = `用户`，事件 = `登录`，对象 = `JThompson`.
4. **创建“关机”任务** —— 新任务，标签选择相同，但操作 = `关机`.
5. **添加注销事件触发器** —— 在关机任务上添加事件触发器：类型 = `用户`，事件 = `注销`，对象 = `JThompson`.
6. **创建周五计划** —— 新计划：每 1 周重复一次，时间为周五下午 6:00。
7. **添加计划触发器** —— 将周五计划作为计划触发器附加到“关机”任务。

**结果：** JThompson 登录时虚拟机自动开机，注销时自动关机，并且无论登录状态如何都保证每周五下午 6 点关机。此模式适用于任何高资源负载——机器学习训练平台、CAD 渲染工作站、集成测试环境或金融建模集群。

## 示例 2：同步错误时的 Slack + 电子邮件告警

该示例展示 webhook、任务和事件如何结合，为 DR/BC 操作提供多渠道告警。

**场景：** 当夜间同步任务遇到错误时，服务提供商需要通过 Slack 和电子邮件立即收到通知。

### 配置步骤

1. **创建 webhook** —— 系统 → 任务仪表板 → 新建 Webhook。配置 Slack 入站 webhook URL，并将授权类型设置为 `Bearer Token` 使用 Slack bot 令牌，并将 content-type 设置为 `application/json`.
2. **创建电子邮件任务** —— 新任务：对象类型 = `电子邮件`，配置收件地址和告警消息正文。
3. **创建 webhook 任务** —— 新任务：对象类型 = `Webhook`，选择 Slack webhook，操作 = `发送`。定义 JSON 负载：

   ```json
   {
     "text": "同步错误告警：${NAME} 于 ${DATE} 失败"
   }
   ```
4. **为 webhook 任务添加事件触发器** —— 类型 = `外发同步`，事件 = `错误`，选择特定同步任务（或使用标签来覆盖多个同步）。
5. **为电子邮件任务添加相同的事件触发器** —— 与步骤 4 配置相同，关联到电子邮件任务。

**结果：** 当任何受监控的同步任务产生错误时，Slack 频道和电子邮件收件箱都会同时收到告警。管理员可以及时排查，从而最大化在可用窗口内完成同步的机会。

{% hint style="success" %}
**使用标签扩展**

如果你希望同一触发器适用于所有外发同步，请分配一个共享标签（例如， `critical-sync`）给这些同步任务。配置触发器在任何带有该标签的同步上触发——无需为每个同步单独创建触发器。
{% endhint %}

## 创建任务：快速参考

每个任务都遵循相同的创建模式：

1. 导航至 **系统 → 任务仪表板 → 新任务**
2. 配置： **名称**, **对象类型**, **对象** （特定实例或标签）， **操作**, **设置**
3. 附加一个或多个 **事件触发器** 和/或 **计划触发器**
4. 在……中验证 **任务日志** 该任务是否正确触发

任务具有一个 **已启用** 标志；如果需要在激活前验证配置，可以暂时禁用任务，准备好后再重新启用。

### 任务字段

**名称** —— 描述性标识 **对象类型** —— 应用程序中的部分（虚拟机、网络、用户、Webhook 等） **对象** —— 具体目标或标签 **操作** —— 要执行的操作 **运行后删除** —— 一次性执行选项

### 任务日志

每次任务执行都会记录：- 时间戳和持续时间 - 成功/失败状态 - 触发事件或计划 - 目标对象详情。日志可从任务仪表板访问，用于审计。

## 脚本（预览）

该 **脚本** 此功能在 VergeOS 26 中引入，为未来管理员定义的自动化工作流奠定基础。虽然目前仅用于内部系统操作，但其设计考虑了可扩展性。未来版本将扩展 Scripts，使其可直接在平台内支持自定义管理员自动化——以可编程逻辑补充现有的任务引擎。

{% hint style="info" %}
**来自 VMware 或 Nutanix？**

任务引擎在 VergeOS 的各个层级（包括租户内部）都已内置——无需单独的编排设备，也无需额外的自动化许可。您可以在与虚拟机和存储相同的界面中配置事件触发器、计划和 webhook。
{% endhint %}

## 要点总结

### 事件驱动

通过系统事件触发自动化——用户登录/注销、同步错误、虚拟机状态变化、告警条件——无需轮询或外部调度器。

### 计划驱动

使用内置或自定义计划在特定时间运行任务。可一次性或周期性，并可选结束日期。

### 外部集成

通过可配置的认证、请求头和重试逻辑，使用 webhook 将通知推送到 Slack、电子邮件、Zapier 或任何 HTTP 端点。

### 模块化且可复用

任务、事件、计划和 webhook 之间采用多对多关系。一次构建，自由组合。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/zh/mo-kuai-8-kai-fa-yu-devops/06-task-engine.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.