butubb
97cec6e211
平台此前出了问题只能靠人盯页面。现在各组件统一走 `notifier.notify(事件, **字段)`， 推到企业微信 / 自建服务；**所有可通知点都登记进事件目录，默认全关，用户按 webhook 勾选**。 ## 架构（`core/notifier.py` + `core/notify_events.py`） 业务线程调 `notify()` → 只做内存操作（读配置快照/匹配订阅/入队）→ 返回； 后台 1 个 dispatcher（聚合 + 每 hook 限流 + 折叠摘要）+ 3 个 sender（真实 HTTP、退避重试） 负责真正发出去。硬约束：**notify 零 DB、零 HTTP、零阻塞、异常不冒泡**——所以任务线程里 可以直接调（不用 app_context、不用 try/except），但**必须放在所有 `with self._lock` 之外**。 - **事件目录 36 条**（任务批次/单设备/设备/Worker/业务/安装/系统/AI），支持 `task.*` 通配订阅； 语义分工避免重复告警：`worker.*` 是单次尝试级，`task.device.success/failed` 是唯一权威结论。 - **适配器可插拔**：`wecom`（markdown，按 4096 **字节**截断、超限不截半个汉字）+ `json`（模板占位符，替换值按 JSON 转义，保存前干跑校验）；钉钉/飞书留了插槽（前端置灰）。 - **防打爆四层**：聚合窗口（默认 30s，同批次合并成一条并带样本）→ 令牌桶限流（默认 18/分， 对齐企微硬限 20）→ 被限流的**折叠成摘要不丢弃** → 有界队列背压。取舍：失败通知最多延迟 一个窗口，换来群不被刷屏。 ## 安全与存储 - 配置只落 `app_meta.notify_webhooks` 一个键（**不建表** → 不涉及备份覆盖红线）。 - URL 本身就是凭据（企微 `?key=`）→ 接口回显/发送记录/日志一律 `mask_url()/scrub()`； 编辑时留空即不修改；secret 永不回显。DATA_MODEL 的明文凭据告警补上了这一条。 - 发送记录：内存环形缓冲 200 条（重启清空）+ 独立 `logs/notify.log`。 ## 接入点（每个都放在锁外、不改 return 顺序） task_manager（批次开始/结束用新增的 `_BatchTracker` 统一在 finally 计数、单设备成功/失败/ 离线/重试/停止/抢占/归还/cron 停止）、device_worker 心跳看门狗、generic 任务选择器连续失效、 apk 安装开始/完成、设备上下线（**状态沿检测**，只报新变化）、备份导出/恢复、经验巡检、 用户登录、服务启停。 ## 前端 系统 Tab 新增「通知 / Webhook」子分栏：多条 webhook 列表（URL 打码）+ 编辑弹窗（格式/URL/ 密钥/事件勾选树带 ★建议/聚合/限流/自定义模板/预览）+ 发送测试 + 发送记录。 ## 自测 - 进程内逻辑 10 组断言全绿：聚合合并、限流+折叠、无配置/全局关静默丢弃、未知事件、 内部异常不外泄、JSON 转义（标题含引号换行仍合法）、URL/异常消息脱敏、配置校验。 - 端到端（假 webhook 接收端）17 项断言全绿：真实事件投递（user.login / task.batch.no_device）、 企微请求体形状、**HTTP 200 + errcode 93000 判为失败**、500 重试 3 次、记录里 URL 打码。 - 韧性：webhook 指向黑洞地址时登录耗时 100~114ms（基线 107~133ms，**异步隔离生效**）； 配置写成坏 JSON 服务照常启动、通知静默不发、日志有 error（服务端实测后已复原）。 - 页面：系统 → 通知 面板/弹窗/36 个事件复选框/预览全部正常，无 JS 报错。 - 自测数据已清理（webhook、自建任务、写坏又复原的配置键）。 文档：新增 doc/NOTIFY.md（事件表/配置/格式约束/防刷屏/加事件三步骤/排障）并登记进 doc/README； API.md §2.11；DATA_MODEL 的 app_meta 键表与明文凭据告警；ARCHITECTURE 线程表/分层/扩展点； 根 README 功能索引与日志表。
167 lines
8.5 KiB
Markdown
167 lines
8.5 KiB
Markdown
# 通知 / Webhook（NOTIFY）
|
||
|
||
> 面向：要给平台接告警的运维、以及往各组件加通知点的开发。
|
||
> 相关：[API.md](API.md)（接口）、[DATA_MODEL.md](DATA_MODEL.md)（配置存哪）、
|
||
> [ARCHITECTURE.md](ARCHITECTURE.md)（线程模型）。
|
||
|
||
---
|
||
|
||
## 1. 它是什么
|
||
|
||
平台各组件（任务、设备、安装、备份、AI 巡检…）在关键时刻调一个统一入口：
|
||
|
||
```python
|
||
from core import notifier
|
||
notifier.notify("task.device.failed", serial="192.168.20.71:5555",
|
||
device_name="A02", job_name="抖音养号", cause="选择器连续 10 次未命中")
|
||
```
|
||
|
||
`notify()` **只做内存操作**（读配置快照 → 匹配订阅 → 丢进队列），真正发 HTTP 的是后台
|
||
daemon 线程。所以：
|
||
|
||
- 任务线程里可以直接调，**不用包 app_context、不用 try/except**（内部全兜住了）
|
||
- **但必须放在所有 `with self._lock` 之外**——别让通知拖住调度锁
|
||
- 通知模块自己出问题（地址写错、对方挂了、配置坏了）**绝不影响任务/设备/备份**，
|
||
最多在日志里留一条警告
|
||
|
||
```
|
||
业务线程 notify() ──入队──▶ dispatcher（1 线程）──▶ sender ×3 ──▶ 企业微信/自建服务
|
||
① 聚合 ② 限流 ③ 折叠
|
||
└─▶ 发送记录（内存 200 条 + logs/notify.log）
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 快速上手（企业微信）
|
||
|
||
1. 企业微信群里 → 群机器人 → 添加 → 复制 Webhook 地址（形如
|
||
`https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxx`）
|
||
2. 后台 → **系统 → 通知 / Webhook → ＋ 新建 Webhook**：名称随便起、格式选「企业微信」、
|
||
粘贴地址、在事件树里勾上关心的事件（★ 是建议开的）
|
||
3. 点该行的 **发送测试** —— 群里立刻能收到一条 markdown；收不到就看返回的 HTTP/errcode
|
||
|
||
---
|
||
|
||
## 3. 事件目录
|
||
|
||
**权威定义在 `core/notify_events.py`**（后台「通知」页也是从它渲染的，不会漂移）。
|
||
所有事件**默认不启用**——登记不等于推送，勾了才发。
|
||
|
||
| 类别 | 事件 |
|
||
|---|---|
|
||
| 任务批次 | `task.batch.started` · `.finished` · `.no_device` · `.unknown_type` · `task.cron.stopped` |
|
||
| 任务·单设备 | `task.device.success` · `.failed` · `.offline` · `.error` · `.retry` · `.stopped` · `.preempted` · `.preempt_timeout` · `.released` |
|
||
| 业务 | `task.selector.invalid`（选择器连续 10 次未命中——"任务成功但什么都没做"的隐蔽故障） |
|
||
| Worker | `worker.connected` · `.attempt.done` · `.attempt.error`（单次尝试级，噪音大，默认没人勾） |
|
||
| 设备 | `device.online` · `.offline` · `.discovered` · `.claimed` · `device.heartbeat_timeout` |
|
||
| 安装 | `apk.install.started` · `.finished` |
|
||
| 系统 | `system.backup.exported` · `.imported` · `.restored` · `.restore_failed` · `service.started` · `.stopping` · `user.login` |
|
||
| AI | `ai.audit.finished` · `.failed` · `.skipped` |
|
||
| 其它 | `notify.test`（测试按钮专用） |
|
||
|
||
订阅支持通配：`*`（全部）、`task.*`、`device.*`。
|
||
|
||
> 语义分工（**避免重复告警**）：`worker.*` 是**单次尝试**层面；`task.device.success/failed`
|
||
> 是"这台设备最终成功/失败"的**唯一权威点**。所以一个设备重试 3 次后失败，只会收到 **1 条**
|
||
> `task.device.failed`，不会收到 3 条噪音。
|
||
|
||
---
|
||
|
||
## 4. 配置
|
||
|
||
存在 `app_meta.notify_webhooks` 一个键里（JSON，**不建表**，因此不涉及备份覆盖清单）：
|
||
|
||
```json
|
||
{
|
||
"version": 1,
|
||
"settings": {"global_enabled": true, "default_agg_window": 30,
|
||
"default_rate_limit": 18, "log_keep": 200, "http_timeout": 5},
|
||
"webhooks": [
|
||
{"id": "wh_ab12cd34", "name": "运维群", "enabled": true, "format": "wecom",
|
||
"url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=…",
|
||
"secret": "", "events": ["task.device.failed", "device.*"],
|
||
"agg_window": 30, "rate_limit_per_min": 18,
|
||
"title_template": "", "body_template": "", "headers": {}}
|
||
]
|
||
}
|
||
```
|
||
|
||
上限（超了**拒绝保存**，不静默截断）：webhook ≤ 20 条、整体 JSON ≤ 60000 字符、URL ≤ 2048。
|
||
|
||
**安全**：URL 里有凭据（企微 `?key=`）→ 接口回显、发送记录、日志一律打码
|
||
（`mask_url`/`scrub`）；编辑时**留空即不修改**；`secret` 永不回显（只回"已配置"）。
|
||
|
||
---
|
||
|
||
## 5. 推送格式
|
||
|
||
| 格式 | 请求体 | 关键约束 |
|
||
|---|---|---|
|
||
| `wecom` 企业微信 | `{"msgtype":"markdown","markdown":{"content":"…"}}` | content **≤4096 字节**（超了按字节截断并加「…(已截断)」，不会截出半个汉字）；**每机器人每分钟 20 条**，超限 `errcode 45009`；成功必须 `errcode==0` |
|
||
| `json` 通用 / Slack | 由 `body_template` 决定 | 保存前**干跑校验**（渲染后必须是合法 JSON） |
|
||
|
||
**字段一律渲染成 `> **字段**：值` 引用行，不用 Markdown 表格**——企业微信/钉钉的 markdown
|
||
子集不支持表格，表格会原样吐出来。
|
||
|
||
通用 JSON 的占位符：`{{event}} {{title}} {{summary}} {{ts}} {{level}} {{markdown}}
|
||
{{fields}} {{fields_json}} {{hook_name}} {{field.<字段名>}}`。
|
||
替换值按 JSON 字符串转义，所以标题里带引号/换行也不会打坏请求体。Slack 直接写
|
||
`{"text":"{{markdown}}"}` 就行。
|
||
|
||
`dingtalk`/`feishu` 在界面上是**置灰**的：适配器留了插槽（`BaseAdapter._sign/_auth_fields/
|
||
_byte_limit`），要接的时候加一个类 + 注册进 `ADAPTERS` 即可；急用可以拿通用 JSON 手搓
|
||
（飞书的 text 格式就是 `{"msg_type":"text","content":{"text":"{{markdown}}"}}`）。
|
||
|
||
---
|
||
|
||
## 6. 防打爆（四层）
|
||
|
||
100 台设备同时失败 = 100 条消息，群里会被刷到静音——**刷屏会让通知彻底失效**。所以：
|
||
|
||
| 层 | 机制 | 默认 |
|
||
|---|---|---|
|
||
| L1 聚合 | 同 webhook、同事件、同聚合键（如 `job_id`）在一个窗口内合并成一条，保留前 3 个样本 | 30s（低频高危事件设 0，立即发） |
|
||
| L2 限流 | 每 webhook 一个令牌桶 | 18 条/分（企业微信硬限 20，留余量） |
|
||
| L3 折叠 | 被限流的事件**不丢弃**，压成一条「被限流折叠 N 条」摘要 | 最多 60s 一条 |
|
||
| L4 背压 | 有界队列（event 2000 / send 1000），满了丢弃并计数 | 溢出会告警一次 |
|
||
|
||
取舍写明白：**失败通知最多延迟一个聚合窗口（默认 30s）**，换来群不被刷屏。
|
||
|
||
---
|
||
|
||
## 7. 开发：给新功能加通知
|
||
|
||
1. 在 `core/notify_events.py` 的 `EVENTS` 里加一条 `_e("模块.对象.动作", "中文标签",
|
||
"分类", ["字段1", "字段2"], "什么时候发", agg_window=…, recommend=…)`
|
||
2. 在触发点调 `notifier.notify("模块.对象.动作", 字段1=…, 字段2=…)`
|
||
—— **放在所有 `with self._lock` 之外**，且不要改变原有 `return` 的顺序
|
||
3. 把事件补进本文档 §3 的表格
|
||
|
||
约定：
|
||
|
||
- `notify()` **不阻塞、不抛异常、不碰 DB**——这是硬约束，别在它里面加 HTTP 或查库
|
||
- 事件的 `fields` 是前端字段表与模板占位符的白名单，只写真正有用的
|
||
- 高频事件（每台设备/每次尝试都会发生的）把 `agg_window` 设大一点或 `recommend=False`
|
||
|
||
---
|
||
|
||
## 8. 排障
|
||
|
||
| 现象 | 看哪里 |
|
||
|---|---|
|
||
| 完全没收到 | ① 全局开关是不是关了（列表页「启用通知」）② 该 webhook 是否启用 ③ 事件勾了没（`task.device.failed` 是**单设备最终失败**，不是每次尝试） |
|
||
| 收到但内容不全 | 消息被 4096 字节截断了（末尾有「…(已截断)」）；把 `cause` 之类长字段在事件侧截短 |
|
||
| 只在群里看到「被限流折叠」 | 短时间内同类事件太多，触发了 L2/L3；调大该 webhook 的限流值（企微上限 20）或调大聚合窗口 |
|
||
| 失败原因 | 后台「通知」页的**发送记录**（内存，重启清空）或 `logs/notify.log`（完整历史）。`errcode 45009`=企微限流、`93000`=Webhook 地址无效、`HTTP 200 + errcode≠0` **也算失败** |
|
||
| 配置坏了 | 服务照常启动（启动日志有 error），通知静默不发；在后台删掉坏配置或直接改 `app_meta.notify_webhooks` |
|
||
|
||
---
|
||
|
||
## 9. 已知限制
|
||
|
||
- 发送记录在**内存**（最近 200 条，重启清空）；持久历史只有 `logs/notify.log` 文本
|
||
- **不支持自定义 webhook 请求头**（`headers` 字段留着但界面没暴露）——需要的话说一声
|
||
- 只做 http/https，**不做内网 IP 黑名单**（内网自建 webhook 是合法用法），但禁止重定向
|
||
（`allow_redirects=False`）
|
||
- `system.backup.restored` 是**重启后**才发（恢复本身就是重启生效的）
|