> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dkron 告警集成

> 通过 Dkron 的 Webhook 通知，将定时任务的失败和恢复事件同步到 Flashduty On-call。

Dkron 在每次任务执行结束后，都可以向一个 Webhook 地址发送一条通知。把这个地址设为 Flashduty 的推送地址后，任务执行失败会在 Flashduty 产生一条告警；同一任务下一次执行成功时，这条告警自动恢复。

<div className="hide">
  ## 在 Flashduty On-call

  ***

  您可通过以下两种方式获取集成推送地址，任选其一即可。

  ### 使用专属集成

  1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间
  2. 选择 **配置** → **集成数据** → **专属集成**，点击 **新增一个集成**
  3. 选择 **Dkron**，点击 **保存**
  4. 打开生成的集成卡片，复制 **推送地址**

  ### 使用共享集成

  1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**
  2. 选择 **Dkron**，填写集成名称
  3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则
  4. 点击 **保存**，复制生成的 **推送地址**
</div>

## 在 Dkron 中配置

***

Dkron 没有固定格式的 Webhook 请求体，而是按您配置的 `webhook-payload` Go 模板渲染后发送。Flashduty 只解析下面这份模板产生的字段，请原样使用。Webhook 是 Dkron 服务端的全局配置，对所有任务生效；它在选出的 Leader 节点上、每个任务执行结束（重试次数用完后）时发送一次，成功和失败都会发送。

<Steps>
  <Step title="配置 Webhook">
    在 Dkron 配置文件（如 `/etc/dkron/dkron.yml`）中加入下面三项，把 `webhook-endpoint` 换成 Flashduty 的完整推送地址：

    ```yaml theme={null}
    webhook-endpoint: "https://api.flashcat.cloud/event/push/alert/dkron?integration_key=YOUR_INTEGRATION_KEY"
    webhook-headers:
      - "Content-Type:application/json"
    webhook-payload: '{"job_name":{{printf "%q" .JobName}},"success":{{.Success}},"node":{{printf "%q" .NodeName}},"reporting_node":{{printf "%q" .ReportingNode}},"started_at":"{{.StartTime}}","finished_at":"{{.FinishedAt}}"}'
    ```

    也可以用命令行参数 `--webhook-endpoint`、`--webhook-headers`、`--webhook-payload`，或环境变量 `DKRON_WEBHOOK_ENDPOINT`、`DKRON_WEBHOOK_HEADERS`、`DKRON_WEBHOOK_PAYLOAD`。

    <Warning>
      * 请保留 `job_name` 和 `success`，缺少其中任何一个，Flashduty 会拒绝该请求。
      * 不要在模板里加入 `{{.Output}}`：任务输出可能包含引号、控制字符或敏感信息，Dkron 不会为 JSON 转义，一个未转义的字符就会让整条请求体失效。
      * 模板中的 `{{printf "%q" ...}}` 用来给任务名等文本加引号并转义，不要改成 `"{{.JobName}}"`。
    </Warning>
  </Step>

  <Step title="重启 Dkron">
    重启 Dkron 服务端使配置生效。集群部署时，所有服务端节点使用相同配置，这样 Leader 切换后仍会发送通知。
  </Step>

  <Step title="验证生命周期">
    创建一个会失败的任务并手动运行，例如执行命令 `false`，确认 Flashduty 出现一条 Critical 告警；再把任务改成会成功的命令并再次运行，确认原告警恢复。Dkron 没有 Webhook 测试按钮，只能通过真实执行来验证。
  </Step>
</Steps>

## Alert Key

***

Flashduty 使用任务名 `job_name`（Dkron 的 `JobName`）作为 Alert Key。Dkron 中任务名是任务的唯一标识，同一个任务的每次执行结果，无论成功或失败，都带有相同的任务名，所以失败和之后的成功会落在同一条告警上。节点、开始和结束时间、成功与否的变化都不会改变 Alert Key。

## 状态和告警等级

***

| Dkron 的执行结果 | Flashduty 状态或等级 |
| :- | :- |
| `success` 为 `false` | Critical |
| `success` 为 `true` | 恢复，原等级为 Critical |

Dkron 不提供告警等级，任务失败一律按 Critical 处理。`success` 为空或不是 `true`、`false` 时请求会被拒绝，避免把无法判断状态的请求写入错误的告警生命周期。

## 告警标签

***

| 标签 | 来源 |
| :- | :- |
| `job_name`、`check`、`resource` | 任务名 |
| `node` | 执行任务的节点 |
| `reporting_node` | 发送通知的 Leader 节点 |
| `started_at`、`finished_at` | 本次执行的开始和结束时间 |

## 排查问题

***

* **Flashduty 没有收到告警**：Dkron 只在日志里记录 Webhook 的发送错误，不会重发。确认服务端能访问 `api.flashcat.cloud`，推送地址完整且包含 `integration_key`
* **Dkron 日志出现 `notifier: error parsing template`**：`webhook-payload` 模板有语法错误，对照上面的模板检查引号和花括号
* **Flashduty 返回参数错误**：确认请求体是有效 JSON，且包含非空的 `job_name` 和值为 `true`、`false` 的 `success`
* **告警没有恢复**：恢复由同一任务的下一次成功执行触发。如果任务一直失败，或任务只运行一次，告警会保持打开；可在协作空间启用超时自动关闭作为兜底，参见[创建协作空间](/zh/on-call/channel/create-edit)
* **任务重试**：Dkron 只在重试用完后发送通知，重试过程中的失败不会产生告警

更多配置项请参阅 [Dkron Configuration](https://dkron.io/docs/basics/configuration/)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.