Nightingale 告警静默Alert MuteHTTP API 完整指南面向外部 A2A Agent 与 curl 的接口实战【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale导读Nightingale 的告警静默规则alert_mute用于在指定时间范围内按标签条件压制匹配的告警事件是机房维护窗口、夜间批量任务免打扰、已知问题降噪的标准手段。本文以仓库内面向外部 A2A Agent 的接口说明文档 http-api.md 为主体系统讲解静默规则的 HTTP API 全貌——包括 9 个端点的路径、方法与请求体格式、权限模型、预览与试运行校验接口、过期规则批量清理以及直接修改数据库的兜底方案并结合 router.go、router_mute.go、models/alert_mute.go、alert/mute/mute.go 等源码深入剖析匹配引擎的判定顺序与 9 秒缓存生效机制。读完本文外部 Agent 或运维脚本即可通过 HTTP 完成静默规则的查询、创建、更新、批量改字段、删除、命中预览与试运行全流程。说明应用内 AI 助手in-app assistant不应使用这些 HTTP 端点而应直接调用内置功能工具FC tools本文档面向的是外部 A2A Agent或在给用户提供 curl 命令时使用。一、API 总览一张表看懂 9 个端点所有端点均挂在/api/n9e前缀下路由定义位于 center/router/router.go。完整清单如下操作MethodPath说明列表跨业务组GET/api/n9e/busi-groups/alert-mutes返回当前用户可见的静默规则支持query搜索、分页以及expired1查询已过期规则列表单个业务组GET/api/n9e/busi-group/:id/alert-mutes指定业务组下的静默规则详情GET/api/n9e/busi-group/:id/alert-mute/:amid单条规则详情创建POST/api/n9e/busi-group/:id/alert-mutes请求体是单个AlertMute JSON 对象更新PUT/api/n9e/busi-group/:id/alert-mute/:amid单对象请求体整体替换——先 GET、再修改、再 PUT批量改字段PUT/api/n9e/busi-group/:id/alert-mutes/fields请求体为{ids:[...],fields:{...}}适合批量禁用/续期删除DELETE/api/n9e/busi-group/:id/alert-mutes请求体为{ids:[1,2,3]}命中预览POST/api/n9e/busi-group/:id/alert-mutes/preview预览一条静默规则草稿会命中哪些当前活跃事件创建大范围静默前务必先跑试运行POST/api/n9e/alert-mute-tryrun用规则草稿对某个历史事件做一次匹配试运行批量清理过期DELETE/api/n9e/alert-mutes需要 admin 权限异步在后台清理已过期的定时fixed-period静默规则周期静默不清除从 router.go 的路由定义可以看到每个端点都串联了多个中间件rt.auth()做身份认证、rt.user()注入用户上下文、rt.perm(/alert-mutes)系列做菜单权限校验部分写操作还叠加了rt.bgrw()业务组读写权限与rt.admin()管理员权限。二、认证与权限模型2.1 认证方式所有请求都使用 Bearer Token 认证Authorization: Bearer tokentoken为当前登录用户在 Nightingale 中签发并持久化于user_token表的访问令牌可参考 models/user_token.go。调用前需先通过登录/SSO 流程获取 token。2.2 权限要求创建 / 更新 / 删除需要业务组读写权限bgrw 对应的/alert-mutes/*菜单权限列表 / 详情只读操作仅需业务组只读权限即可。对应到路由中间件router.gort.perm(/alert-mutes)基础菜单权限覆盖列表与详情rt.perm(/alert-mutes/add)创建与试运行rt.perm(/alert-mutes/put)更新与批量改字段rt.perm(/alert-mutes/del)删除rt.bgrw()业务组读写权限创建/删除/批量改字段均要求rt.admin()批量清理过期规则DELETE /api/n9e/alert-mutes额外要求系统管理员身份。简言之只读操作门槛低写操作必须同时具备业务组读写权限与对应菜单权限批量清理则必须是 admin。三、核心数据模型AlertMute 字段与 JSON 序列化http-api.md明确指出直接修改数据库兜底时表名为alert_mute其中tags/periodic_mutes/severities/datasource_ids是 JSON / 序列化字段。其数据模型定义在 models/alert_mute.go关键点DB 存储形态与 API 形态分离DatasourceIds、PeriodicMutes、Severities在 GORM 中映射为字符串JSON 序列化后的文本而对外 JSON 输出分别由DatasourceIdsJson、PeriodicMutesJson、SeveritiesJson承载FE2DB()负责从 API 形态序列化到 DB 形态DB2FE()负责反向解析models/alert_mute.goTags字段以ormx.JSONArr存储是一组TagFilter的 JSON 数组每个元素形如{key:..., func:..., value:...}MuteTimeType0固定时间区间TimeRange1周期静默PeriodicMuteType0屏蔽事件与通知默认命中后事件不产生也不通知1只屏蔽通知事件照常产生记录仅不发送通知Activated是查询时动态计算的展示字段gorm:-表示此刻是否处于生效时间内并非存储状态。Verify()models/alert_mute.go包含两条硬校验datasource_ids为空或包含0时自动归一化为[0]即全部数据源etime btime直接报错oops... etime(%d) btime(%d)——这条校验对周期静默同样生效因此即使周期匹配不读取 btime/etime创建时也必须让两者满足etime btime。四、逐个端点详解与 curl 实战4.1 列表查询跨业务组列表curl -G http://n9e-host:17000/api/n9e/busi-groups/alert-mutes \ -H Authorization: Bearer token \ --data-urlencode queryweb01 \ --data-urlencode expired1返回当前用户可见业务组下的全部静默规则query参数做模糊搜索源码中是对cause字段做like匹配见 models/alert_mute.goexpired1用于查询已过期的固定区间静默规则mute_time_type0 AND etime now。单业务组列表curl -G http://n9e-host:17000/api/n9e/busi-group/12/alert-mutes \ -H Authorization: Bearer token4.2 详情查询curl http://n9e-host:17000/api/n9e/busi-group/12/alert-mute/345 \ -H Authorization: Bearer token返回单条规则完整 JSON包含datasource_ids、severities、periodic_mutes、tags等解析后的数组形态字段以及动态计算的activated字段。更新前务必先 GET见下节。4.3 创建curl -X POST http://n9e-host:17000/api/n9e/busi-group/12/alert-mutes \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d { note: Maintenance window: mute web01 alerts, cause: web01 planned maintenance, expected 2 hours, prod: metric, cate: prometheus, datasource_ids: [], severities: [1, 2, 3], tags: [ {key: ident, func: , value: web01} ], mute_time_type: 0, btime: 1737000000, etime: 1737007200, periodic_mutes: [], cluster: 0 }要点请求体是单个AlertMute 对象不是数组mute_time_type0固定区间时必须满足etime btime否则Verify()直接拒绝datasource_ids为空数组即全部数据源会自动归一化为[0]tags为空数组意味着无条件静默该业务组内全部告警属于高风险配置务必谨慎完整的字段表、时间模式与 tags 运算符说明见配套文档 reference.md。4.4 更新整体替换curl -X PUT http://n9e-host:17000/api/n9e/busi-group/12/alert-mute/345 \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d { note: Maintenance window: mute web01 alerts (extended), cause: maintenance extended, prod: metric, cate: prometheus, datasource_ids: [], severities: [1, 2, 3], tags: [{key: ident, func: , value: web01}], mute_time_type: 0, btime: 1737000000, etime: 1737014400, periodic_mutes: [], cluster: 0 }关键语义PUT 是整体替换replaced wholesale。从源码 models/alert_mute.go 可见Update会把新对象的字段整体Select(*).Updates(arm)覆盖写回仅保留Id、GroupId、CreateAt、CreateBy四个不可变字段。因此标准操作流程是GET 详情 → 在返回 JSON 基础上修改 → 原样 PUT任何漏传字段都会被覆盖为空值切勿只传想改的字段。4.5 批量改字段curl -X PUT http://n9e-host:17000/api/n9e/busi-group/12/alert-mutes/fields \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d { ids: [345, 346, 347], fields: {disabled: 1} }fields支持任意可更新字段的键值对典型场景批量禁用{disabled:1}、批量续期修改etime、批量改标签底层走UpdateFieldsMapmodels/alert_mute.go仅更新传入字段不触碰其他列——与 4.4 的整体替换形成鲜明对比处理器实现见 router_mute.go 的alertMutePutFields。4.6 删除curl -X DELETE http://n9e-host:17000/api/n9e/busi-group/12/alert-mutes \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d {ids: [345, 346, 347]}底层对应models.AlertMuteDelmodels/alert_mute.go按 ID 批量物理删除。应用内 AI 助手场景下删除建议走 UI告警管理 → 告警屏蔽或先disabled:1临时禁用更安全。五、命中预览与试运行创建大范围静默前的安全阀这是http-api.md重点强调的两个校验类端点用于在创建大范围静默前验证影响面避免误伤。5.1 命中预览POST /api/n9e/busi-group/:id/alert-mutes/preview请求体为一条 AlertMute 草稿 JSON与创建时同构group_id取自 URL 路径参数。处理器alertMutePreviewrouter_mute.go的逻辑是f.Verify()校验并解析 tags 为ITags从活跃事件表alert_cur_event中按业务组、产品、严重级别、数据源等条件取出候选事件AlertCurEventGetsFromAlertMute逐个用common.MatchTags做标签匹配返回所有会被这条静默命中的活跃事件列表。curl -X POST http://n9e-host:17000/api/n9e/busi-group/12/alert-mutes/preview \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d { note: check impact before large mute, prod: metric, cate: prometheus, datasource_ids: [], severities: [1,2,3], tags: [], mute_time_type: 0, btime: 1737000000, etime: 1737007200, periodic_mutes: [], cluster: 0 }如果返回的事件数量远超预期例如空 tags 命中了整个业务组说明影响面过大应在创建前调整条件。5.2 试运行POST /api/n9e/alert-mute-tryrun用一个规则草稿对某个具体历史事件做一次匹配试运行返回 event match mute 或 event not match mute。处理器alertMuteTryRunrouter_mute.go的流程绑定表单AlertMute草稿 EventId历史事件 IDPassTimeCheck标志通过AlertHisEventGetById取历史事件并转为当前事件形态、构建 TagsMap若PassTimeChecktrue把静默时间强制改为每天 00:00~00:00的周期形式从而跳过时间窗口判断、只验证业务组/数据源/严重级别/标签是否匹配调用引擎核心函数mute.MatchMute得到匹配结果。curl -X POST http://n9e-host:17000/api/n9e/alert-mute-tryrun \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d { event_id: 98765, pass_time_check: true, alert_mute: { note: tryrun, prod: metric, cate: prometheus, datasource_ids: [], severities: [1,2,3], tags: [{key: ident, func: , value: web01}], mute_time_type: 0, btime: 1737000000, etime: 1737007200, periodic_mutes: [], cluster: 0 } }该端点非常适合排查为什么这条静默不生效——用真实事件逐条验证草稿配置。六、批量清理过期静默DELETE /api/n9e/alert-mutes固定区间的静默规则到期后不会自动删除仅不再加载进匹配缓存长时间运行会积累大量无效数据。管理员可通过该端点异步清理curl -X DELETE http://n9e-host:17000/api/n9e/alert-mutes \ -H Authorization: Bearer token必须 admin 权限路由中带rt.admin()后台异步批量删除已过期的固定区间静默mute_time_type0 AND etime 0 AND etime now AND create_at now周期静默periodic不会被清理底层实现见 models/alert_mute.go 的AlertMuteBatchDelete支持按业务组限制范围与分批 limit处理器为 router_mute.go 的alertMuteBatchDelete。七、兜底方案直接修改数据库当 HTTP API 无法满足需求例如需要跨业务组批量迁移、修复脏数据时http-api.md给出了最后的兜底手段表名alert_muteJSON/序列化字段tagsTagFilter 数组 JSON、periodic_mutesPeriodicMute 数组 JSON、severitiesint 数组 JSON、datasource_idsint 数组 JSON生效机制修改后内存缓存最长约9 秒自动重载见 memsto/alert_mute_cache.go轮询间隔为time.Duration(9000) * time.Millisecond无需重启服务务必先备份再修改。需要注意的语义细节详见配套排障文档 troubleshooting.md已过期的固定区间静默不会加载进匹配缓存直接改 DB 时同样遵循该规则prod/cate/cluster字段仅用于展示不参与匹配不要指望用它们过滤事件。八、源码级原理匹配引擎如何判定命中静默理解这些 HTTP 端点返回结果的前提是掌握底层匹配语义。核心函数MatchMute位于 alert/mute/mute.go按固定顺序逐门校验任一关卡失败即判定未命中顺序关卡源码逻辑失败常见原因0缓存同步内存缓存轮询约 9s 重载memsto/alert_mute_cache.go刚改完规则立即测试缓存尚未刷新1业务组group_id隔离事件与规则不在同一业务组最常见根因2启用状态Disabled 1直接返回 false规则被禁用3数据源datasource_ids非全量时事件datasource_id必须在列表中数据源不匹配4时间固定区间[btime, etime]闭区间判定IsWithinTimeRange周期静默按星期 HH:mm 判定IsWithinPeriodicMutemodels/alert_mute.go触发时间不在窗口内enable_days_of_week写法错误5严重级别severities非空时事件Severity必须在列表中级别不匹配6标签多条 tagsAND 关系common.MatchTagsalert/common/key.go事件缺少任一标签或值不匹配几个值得展开的引擎语义静默发生在事件评估阶段alert/process/process.go命中静默的事件被直接丢弃——不落库不产生当前/历史告警记录、不发送通知仅在服务日志与静默计数指标中留痕不会误判恢复被静默事件的 hash 仍会记入告警集合因此已触发的告警不会因为静默而假装恢复同理静默不会清除已产生的活跃告警——静默生效后历史告警页仍能看到旧事件是正常现象周期静默的时间判定不读取 btime/etime源码 models/alert_mute.go 只看enable_days_of_weekenable_stime/enable_etimebtime/etime 仅为通过etime btime硬校验而存在跨午夜原生支持enable_stime enable_etime如22:00~06:00按 stime或 etime判定星期编号0周日 … 6周六时间判定使用 n9e 进程的本地时区in/not in运算符的值为空格分隔字符串ParseTagFilter用strings.Fields切分models/alert_mute.go写成逗号分隔会匹配失败。prod、cate、cluster三字段在MatchMute中完全不参与判定属于纯展示字段。九、常见坑位速查结合配套排障文档 troubleshooting.md 与源码外部调用方最容易踩的坑现象原因处理etime btime报错Verify()硬校验周期静默同样要求确保etime btime或使用应用内工具传duration参数自动计算周期静默在 btime/etime 边界行为异常周期匹配不读btime/etime只看星期时段想实现仅某个月生效需到期手动禁用/删除enable_days_of_week写1-5或Monday to Friday不生效引擎对空格分隔数字串做 contains 匹配写1 2 3 4 5或用weekday等别名in值写逗号分隔不生效解析用strings.Fields按空白切分改为空格分隔tags 有 key 无 value空值参与精确匹配几乎必然失配先确认真实标签值再填想屏蔽某条告警规则事件标签含rulename用{key:rulename,func:,value:规则名}大范围误静默tags 为空数组 静默整个业务组创建前先跑preview端点核对影响面十、与内置 Agent 工具的分工http-api.md开篇即强调应用内 AI 助手不应使用这些端点而应使用内置 FC 工具如create_alert_mute、update_alert_mute、list_alert_mutes、get_alert_mute_detail工具的完整工作流见 SKILL.md。二者适用边界内置工具运行在 n9e 进程内、已认证为当前用户直接调用即可支持duration参数自动换算时间戳、空业务组时自动弹出选择表单、修改走提案确认机制等高级能力是应用内推荐路径HTTP API面向外部 A2A Agent或用户明确索要 curl 命令时使用需要自行管理 token、自行计算 btime/etime、注意 PUT 整体替换语义。两者共享同一套数据模型与匹配引擎因此本章讲解的字段、校验、匹配顺序与缓存机制对两种调用方式完全一致——这也是理解本 API 全部行为的最佳捷径。延伸阅读http-api.md本文核心文档reference.md静默规则完整字段表、两种时间模式、tags 运算符与完整示例troubleshooting.md静默不生效逐门排障链与行为语义表models/alert_mute.go数据模型、Verify校验、FE2DB/DB2FE序列化与批量删除alert/mute/mute.go匹配引擎MatchMute六道关卡alert/common/key.go标签匹配MatchTags与六种运算符实现center/router/router.go路由与权限中间件定义center/router/router_mute.go预览、试运行、批量清理等处理器实现【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
