配置 Slack 通知
Excubius 在 Slack 中发布警报:警报打开时、严重性升高时和解决时。你按实体选择频道,下级的每个实体都会继承这些频道,直到它设置自己的频道。本指南介绍如何一次性连接 Slack 应用、为实体添加频道、测试频道,以及消息如何路由。
开始之前
- 若要添加频道,你需要在该实体上具有 Entity admin 角色。
- 若要创建 Slack 应用,你需要有权在 Slack 工作区中安装应用。
- 若要向 Excubius 提供应用的令牌,你需要访问服务器:在服务器上具有
sudo权限,或拥有安装程序包。
连接 Slack 应用
每个安装只需执行一次。
-
转到
https://api.slack.com/apps,选择 Create New App,选择 From scratch,为其指定一个团队能够识别的名称,然后选择你的工作区。 -
在 OAuth & Permissions 下,添加机器人令牌范围
chat:write。Excubius 不需要其他任何范围。 -
选择 Install to Workspace 并允许。复制 Bot User OAuth Token,它以
xoxb-开头。 -
在服务器上,使用
sudo -iu excubius切换到服务账户,并在/opt/excubius/.env中设置令牌:SLACK_BOT_TOKEN=xoxb-…SLACK_DEFAULT_CHANNEL=#alertsSLACK_DEFAULT_CHANNEL接收所有在其上级没有任何自有频道的实体的警告和严重警报。如果省略,则为#alerts。 -
重启平台:
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,并且不会发送任何内容。
为实体添加频道
- 在 Slack 中打开该频道,例如
#ciguapa-alerts,并邀请应用加入,例如使用/invite @Monitoring。应用只能在其所属的频道中发布消息。 - 在 Excubius 中,打开 Settings › Notifications,在选取器中选择实体,例如高密物流。
- 选择 Add Slack channel。
- 填写字段:
- Name:供你的团队使用,例如 高密物流警报。
- Slack channel:小写的
#name,或频道 ID,例如C0123456789。 - Minimum:发布的最低严重性,Info、Warning 或 Critical。低于它的警报不会发布。
- Message language:English 或 Español。西班牙语需要功能开关
ui.i18n;如果没有,该字段会说明消息为英语。
- 选择 Add Slack channel。
- 在新频道上选择 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"
}'