SLS 飞书只读监控

用途

供测试环境运维人员以最小只读权限监控应用错误，并在飞书中接收低噪的告警与恢复通知。

使用前准备

监控依赖 Worker、Redis、阿里云 SLS 和飞书自定义机器人。为独立 RAM 用户创建 AccessKey，只授予目标 Project 和 Logstore 的日志读取权限；不需要创建告警、写入日志或修改 SLS 资源的权限。Webhook 与签名密钥必须由部署平台 Secret 注入，不得写入仓库或镜像。

配图占位

• 页面：飞书群中的 SLS 通道测试卡片
• 状态：明确显示“通道测试”和合成命中数
• 重点区域：运行环境和评估时间
• 脱敏要求：隐藏 Webhook、签名密钥、AccessKey 和群成员信息

当前默认范围是测试环境：

其他环境启用前必须显式覆盖全部五项，避免查询测试环境。

操作步骤

1. 配置 SLS_MONITOR_ACCESS_KEY_ID、SLS_MONITOR_ACCESS_KEY_SECRET、SLS_MONITOR_FEISHU_WEBHOOK_URL 和 SLS_MONITOR_FEISHU_SIGNING_SECRET。
2. 保持 SLS_MONITOR_ENABLED=false，先执行 npm run monitor:sls:once。该命令查询三类聚合命中数；存在命中时还会读取全部匹配原始日志，但不读写告警状态，也不发送业务通知。
3. 需要验证飞书通道时执行 npm run monitor:sls:once -- --send-test。三条查询全部成功后只发送一条明确标注为“通道测试”的合成消息。
4. 在测试环境 Worker 部署中设置 SLS_MONITOR_ENABLED=true 并重启 Worker。启动时会校验全部配置，每个监控实例注册一个 5 分钟 scheduler。

查询规则为：运行时错误和 API 服务端错误在最近 6 分钟命中一次即告警；配置错误在最近 11 分钟命中至少 3 次才告警。告警卡片使用颜色区分告警、查询异常、恢复和通道测试，并只显示状态、类别、命中数、运行环境和评估时间；错误区使用飞书原生表格逐行显示全部匹配日志原文，每页 5 条并支持翻页，不截断单条内容。查询异常卡片同样完整显示各类别的查询错误原文。卡片不显示 Endpoint、Project、Logstore 或内部 transition_id。原始日志可能包含业务上下文，接收群应限制成员范围。

结果与状态

首次命中发送一次告警，持续命中不重复通知。告警后连续两个空窗口发送一次恢复；恢复后再次命中才开始新的告警周期。三条查询中任一失败时，成功类别仍正常评估，失败类别保持原状态；连续三轮查询不完整会发送一次监控查询异常，全部恢复后发送一次恢复通知。

通知采用至少一次投递。通常不会重复；但进程在飞书已接收、Redis 尚未提交 transition_id 的极小窗口内崩溃时，下一轮可能重发相同标识。

每轮完成日志会在存在异常时附带 queryErrors 或 notificationErrors，便于直接查看 SLS 查询或飞书投递失败原文。

停用与变更目标

先使用旧的查询范围和旧 Webhook 配置执行：

npm run monitor:sls:stop

命令只删除当前 monitor_id 的 scheduler 和未开始的下一轮任务，并输出仍在执行的任务数。已经开始的任务不会被强制中断。确认停用后再更换范围或 Webhook；仅把 SLS_MONITOR_ENABLED 改为 false 不会主动删除旧 scheduler。

权限和限制

• 轮询器依赖同一套 Worker 和 Redis，因此不能检测 Worker、Redis、Pod 或集群整体不可用；这些故障需要独立的集群外监控。
• Redis 状态被清空后，仍在命中的异常会重新通知一次。
• Webhook 只接受 https://open.feishu.cn/open-apis/bot/v2/hook/...，请求体超过 20 KB 会拒绝发送。
• 普通 dry-run 不需要飞书配置；停用不需要已经撤销的 SLS AccessKey 或飞书签名密钥。

常见问题

为什么错误没有重复通知？

这是预期行为。状态保持为 firing 时不会周期性提醒；连续两个正常窗口恢复后，后续新错误才会再次告警。

为什么监控完全没有消息？

先确认 Worker 和 Redis 可用，再运行 dry-run 检查 SLS 权限与查询范围。轮询器无法在自身 Worker 已停止时发送故障消息。

相关文档

• 消息与异步任务
• 故障排查