跳到主要内容
版本:0.4 · 当前版

配置 Slack 通知

操作指南审阅日期:2026年10月11日
适用于:Excubius 0.4角色: 实体管理员
计划Free · Core · Pro · Enterprise部署自托管

Excubius 在 Slack 中发布警报:警报打开时、严重性升高时和解决时。你按实体选择频道,下级的每个实体都会继承这些频道,直到它设置自己的频道。本指南介绍如何一次性连接 Slack 应用、为实体添加频道、测试频道,以及消息如何路由。

开始之前​

  • 若要添加频道,你需要在该实体上具有 Entity admin 角色。
  • 若要创建 Slack 应用,你需要有权在 Slack 工作区中安装应用。
  • 若要向 Excubius 提供应用的令牌,你需要访问服务器:在服务器上具有 sudo 权限,或拥有安装程序包。

连接 Slack 应用​

每个安装只需执行一次。

  1. 转到 https://api.slack.com/apps,选择 Create New App,选择 From scratch,为其指定一个团队能够识别的名称,然后选择你的工作区。

  2. 在 OAuth & Permissions 下,添加机器人令牌范围 chat:write。Excubius 不需要其他任何范围。

  3. 选择 Install to Workspace 并允许。复制 Bot User OAuth Token,它以 xoxb- 开头。

  4. 在服务器上,使用 sudo -iu excubius 切换到服务账户,并在 /opt/excubius/.env 中设置令牌:

    SLACK_BOT_TOKEN=xoxb-…
    SLACK_DEFAULT_CHANNEL=#alerts

    SLACK_DEFAULT_CHANNEL 接收所有在其上级没有任何自有频道的实体的警告和严重警报。如果省略,则为 #alerts。

  5. 重启平台:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    systemctl --user restart excubius.service

安装程序也会询问 Slack 机器人令牌和默认频道;sudo ./install.sh --reconfigure 会再次询问。在设置令牌之前,Settings › Notifications 会显示 Slack is not configured on the server,并且不会发送任何内容。

为实体添加频道​

  1. 在 Slack 中打开该频道,例如 #ciguapa-alerts,并邀请应用加入,例如使用 /invite @Monitoring。应用只能在其所属的频道中发布消息。
  2. 在 Excubius 中,打开 Settings › Notifications,在选取器中选择实体,例如高密物流。
  3. 选择 Add Slack channel。
  4. 填写字段:
    • Name:供你的团队使用,例如 高密物流警报。
    • Slack channel:小写的 #name,或频道 ID,例如 C0123456789。
    • Minimum:发布的最低严重性,Info、Warning 或 Critical。低于它的警报不会发布。
    • Message language:English 或 Español。西班牙语需要功能开关 ui.i18n;如果没有,该字段会说明消息为英语。
  5. 选择 Add Slack channel。
  6. 在新频道上选择 Test。

Slack 频道中会出现一条测试消息,Excubius 显示 Test message sent。如果 Slack 拒绝该消息,错误会指明原因,例如 not_in_channel:请邀请应用加入频道,检查频道名称,然后重新测试。

高密物流及其下所有内容的警报现在都会发送到该频道。一个实体可以有多个频道,例如一个用于警告,另一个仅用于严重警报。

关闭、更改或删除频道​

在频道所在的行上:

  • 使用其开关可在不删除频道的情况下将其关闭,以后可再次打开。当一个实体的所有频道都关闭时,该实体会使用从上级继承的频道。
  • 选择 Edit 可更改任何字段,然后选择 Save。
  • 选择 Remove 可停止向其发送。频道本身仍保留在 Slack 中。

消息如何找到其频道​

该页面在 Where alerts go 下显示所选实体的结果:它自己的频道,或继承的频道及其来源实体,或服务器的默认频道。

情况警报的去向
警报所属的实体有已启用的频道它自己的频道,每个频道按其 Minimum 过滤
它没有频道,但某个上级有拥有频道的最近上级的频道
路径上没有任何实体有频道SLACK_DEFAULT_CHANNEL,用于警告和严重警报
没有频道,也没有默认频道无处可发;页面会说明这一点

每条消息都包含资源及其实体路径、检查、值与阈值的对比以及该阈值的设置位置、情况已持续多长时间、检查目录中的建议措施(如果有)以及指向警报的链接。消息从不提及产品名称。

让频道保持安静的机制:

  • 每个情况一条警报。 重复出现只会更新警报,不会发送任何内容。
  • 静默期。 每个情况每 10 分钟最多一条消息,除非严重性升高。服务器设置 EXCUBIUS_NOTIFY_QUIET_MINUTES 可更改该时长。
  • 根本原因。 当无法访问某个资源时,只发送一条严重的 Cannot reach 警报,该资源的其他警报会等待,直到它解决。
  • 静默和维护时段。 在它们持续期间不会发送任何内容;频道尚未收到的消息,会在它们结束时发出(如果仍然适用)。
  • 不发送降级通知。 从严重降为警告,只记录在警报的时间线中,不发送。只有在发送过开启通知时,才会发送解决通知。
  • 已关闭的功能。 功能已关闭的模块的警报永远不会发送,安全建议也不会发送。

Slack 绝不会妨碍监视:结果会先存储和评估,消息随后立即发出,并由每 15 秒一次的后台扫描发出。投递失败会记录在警报的时间线中,并由后续扫描重试,总共尝试三次。

使用 API 执行​

任务请求
查看实体的频道及其有效路由GET /api/v1/entities/{id}/channels
添加频道POST /api/v1/entities/{id}/channels
更改、关闭或打开PATCH /api/v1/channels/{id},可带 name、config、min_severity、locale、enabled 中的任意字段
删除DELETE /api/v1/channels/{id}
发送测试消息POST /api/v1/channels/{id}/test。返回 {"ok": true},或返回带有 Slack 所给原因的 {"ok": false, "error": "not_in_channel"}
curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/channels" -d '{
"kind": "slack", "name": "Ciguapa alerts", "config": {"channel": "#ciguapa-alerts"},
"min_severity": "warning", "locale": "es"
}'