Nightingale 订阅规则 HTTP API 实战指南：面向外部 A2A Agent 与 curl 调用的完整接口手册-北京尧图网络

Nightingale 订阅规则 HTTP API 实战指南面向外部 A2A Agent 与 curl 调用的完整接口手册【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale本文基于aiagent/skill/embedded/builtin/alert-subscribe-copilot/http-api.md编写并辅以仓库源码路由注册、处理器实现、模型定义、内存缓存进行纵深展开。订阅规则Alert Subscribe是 Nightingale 告警通知阶段的关键机制按条件筛选告警事件后克隆一份副本并按订阅配置改写再走一遍通知链路从而实现跨团队抄送、告警升级持续 N 分钟未处理后通知负责人等典型场景。Nightingale 为这类订阅规则提供了一套完整的 HTTP REST API专门供站外 A2A Agent 集成或为用户生成可执行的 curl 命令使用。读完本文你将掌握全部 7 个端点的请求/响应形态、Bearer Token 鉴权与两级权限模型、Tryrun 逐门校验机制以及绕过 API 直改数据库的兜底方案。订阅规则与这套 HTTP API 的定位在动手调接口之前先明确这套 API 的服务对象。仓库中aiagent/skill/embedded/builtin/alert-subscribe-copilot/SKILL.md明确写道You are the in-app AI assistant for n9e, running inside the n9e process and already authenticated as the current user.Operate directly via the built-in tools — do not log in, do not call HTTP APIs, and do not use http_fetch against your own endpoints(the HTTP flow inhttp-api.mdis for external A2A agents).也就是说Nightingale 内部 AI 助手in-app assistant禁止调用本套 HTTP 端点它应使用内置 Function Calling 工具如create_alert_subscribe、update_alert_subscribe见 aiagent/tools/subscribe.go。本套 HTTP API 是为外部 A2A Agent 和手工 curl 调用而设计的公开能力。订阅本身发生在通知阶段alert/dispatch/dispatch.go中的handleSubs原始事件照常走它自己的通知路径每个匹配的订阅会克隆一份事件副本、按订阅配置改写后再跑一遍通知链路。订阅是叠加式的——它不拦截、不替换原始通知。理解这一点是正确使用增删改查接口的前提。接口总览七个端点一张表所有端点均挂在/api/n9e前缀下路由定义集中在 center/router/router.go。完整清单如下与原始文档保持一致操作方法路径说明列表跨业务组GET/api/n9e/busi-groups/alert-subscribes返回当前用户可见业务组下的订阅列表单业务组GET/api/n9e/busi-group/:id/alert-subscribes指定业务组:id下的订阅详情GET/api/n9e/alert-subscribe/:sid按订阅 ID 获取完整配置创建POST/api/n9e/busi-group/:id/alert-subscribesBody 为单个AlertSubscribeJSON 对象group_id取自 URL更新PUT/api/n9e/busi-group/:id/alert-subscribesBody 为数组[{...}]与创建相反按显式字段列表更新但仍建议先 GET 详情、改完整个对象再 PUT删除DELETE/api/n9e/busi-group/:id/alert-subscribesBody{ids:[1,2,3]}TryrunPOST/api/n9e/alert-subscribe/alert-subscribes-tryrunBody{event_id:历史事件ID,config:{...订阅草稿...}}逐门校验匹配条件新版本notify_version1还会真实发送通知规则测试——编辑后先 Tryrun 再保存从路由源码可以看到每个端点的完整中间件链例如pages.GET(/busi-groups/alert-subscribes, rt.auth(), rt.user(), rt.perm(/alert-subscribes), rt.alertSubscribeGetsByGids) pages.POST(/busi-group/:id/alert-subscribes, rt.auth(), rt.user(), rt.perm(/alert-subscribes/add), rt.bgrw(), rt.alertSubscribeAdd) pages.PUT(/busi-group/:id/alert-subscribes, rt.auth(), rt.user(), rt.perm(/alert-subscribes/put), rt.bgrw(), rt.alertSubscribePut) pages.DELETE(/busi-group/:id/alert-subscribes, rt.auth(), rt.user(), rt.perm(/alert-subscribes/del), rt.bgrw(), rt.alertSubscribeDel) pages.POST(/alert-subscribe/alert-subscribes-tryrun, rt.auth(), rt.user(), rt.perm(/alert-subscribes/add), rt.alertSubscribeTryRun)请求统一要求Authorization: Bearer token头token 为用户令牌用户登录后生成。认证与鉴权Bearer Token 与两级权限模型所有端点都要求Authorization: Bearer token。在此基础上权限是两级叠加的菜单级权限rt.perm(...)对应/alert-subscribes、/alert-subscribes/add、/alert-subscribes/put、/alert-subscribes/del四个操作码。实现见 center/router/router_mw.go 的perm中间件内部调用me.CheckPerm校验。其中查询类接口只要求读权限/alert-subscribes创建要求/alert-subscribes/add更新要求/alert-subscribes/put删除要求/alert-subscribes/delTryrun 挂在/alert-subscribes/add下与创建同级。业务组级权限rt.bgro()/rt.bgrw()对 URL 中的业务组:id做数据级校验。bgro只读调用CanDoBusiGroup检查是否可见bgrw读写调用CanDoBusiGroup(..., rw)检查是否具备读写权限不满足直接返回 403forbidden。实现见 center/router/router_mw.go。因此创建/更新/删除订阅都需要「业务组读写权限bgrw 对应/alert-subscribes/*菜单权限」双重满足纯列表查询只需要业务组可见bgro 读菜单权限。跨业务组列表接口alertSubscribeGetsByGids对非管理员会回退到MyBusiGroupIds只列出自己所属业务组的数据见 center/router/router_alert_subscribe.go。查询类接口列表与详情跨业务组列表curl -H Authorization: Bearer token \ http://n9e-host/api/n9e/busi-groups/alert-subscribes可选查询参数gids逗号分隔的业务组 ID 列表用于精确限定范围不带时对非管理员自动收敛到其可见业务组。返回当前用户可见业务组下的全部订阅服务端不做分页由前端自行搜索分页见alertSubscribeGetsByGids的注释 Return all, front-end search and paging。单业务组列表与详情# 列出业务组 2 下的订阅 curl -H Authorization: Bearer token \ http://n9e-host/api/n9e/busi-group/2/alert-subscribes # 获取订阅 123 的完整详情 curl -H Authorization: Bearer token \ http://n9e-host/api/n9e/alert-subscribe/123单业务组列表与详情处理器alertSubscribeGets/alertSubscribeGet在返回前会做一整套填充见 center/router/router_alert_subscribe.goFillUserGroups把user_group_ids解析为完整用户组对象FillRuleNames把rule_ids解析为告警规则名规则缺失时标记Error: AlertRule not foundFillDatasourceIds与DB2FE把数据库中的 JSON 序列化串还原为前端/API 形态的数组字段。返回结构中的序列化字段理解响应结构的关键在于模型 models/alert_subscribe.go 的字段定义——数据库行里存的是 JSON 字符串API 返回的是 JSON 数组。DB2FEDB→前端/API 形态负责这层转换datasource_idsDB 中是 JSON 字符串API 中是[]int64severitiesDB 中是 JSON 字符串API 中是[]intwebhooksDB 中是 JSON 字符串API 中是[]stringextra_configDB 中是 JSON 字符串API 中是任意 JSON 对象tags/busi_groups本身就是ormx.JSONArrrule_ids/notify_rule_ids使用gorm:serializer:json直接序列化存储。一个典型详情响应片段形如{ id: 123, name: 跨团队抄送-支付核心链路, group_id: 2, disabled: 0, prod: , cate: , datasource_ids: [1, 2], rule_ids: [45, 67], severities: [1, 2, 3], for_duration: 600, tags: [{key: team, func: , value: pay}], busi_groups: [{key: groups, func: , value: 支付中心}], notify_version: 1, notify_rule_ids: [9], note: 支付核心链路告警升级 }创建POST 单对象创建接口的 Body 是单个AlertSubscribeJSON 对象不是数组group_id从 URL 路径取不读 Body。对应处理器alertSubscribeAddcenter/router/router_alert_subscribe.go的关键行为从 URL 取:id作为GroupId 0直接 400group_id invalid从登录态注入CreateBy/UpdateBy调用AlertSubscribe.Add落库。curl -X POST -H Authorization: Bearer token \ -H Content-Type: application/json \ http://n9e-host/api/n9e/busi-group/2/alert-subscribes \ -d { name: 跨团队抄送-支付核心链路, disabled: 0, prod: , cate: , datasource_ids: [1, 2], cluster: 0, rule_ids: [45, 67], severities: [1, 2, 3], for_duration: 600, tags: [{key: team, func: , value: pay}], busi_groups: [{key: groups, func: , value: 支付中心}], notify_version: 1, notify_rule_ids: [9], note: 支付核心链路告警升级 }落库前的校验逻辑集中在AlertSubscribe.Verify()models/alert_subscribe.go外部 Agent 组装请求时应遵循这些规则severities必填新旧版本都校验缺省报severities is required[1,2,3]表示全部严重级别新版本notify_version1要求notify_rule_ids非空否则报no notify rules selected且该校验会清空旧版改写字段redefine_severity/redefine_channels/webhooks/user_group_ids/new_channels等旧版本notify_version0默认要求若指定了user_group_ids则new_channels新告警通知渠道必须指定否则可能因告警规则未配置通知渠道而导致订阅通知发不出去同时NotifyRuleIds会被强制置空datasource_ids为空数组会自动规范化为[0]FE 表示全部数据源的哨兵值Verify中的IsAllDatasource分支处理该归一化。更新PUT 数组与显式字段列表更新接口与创建相反Body 必须是数组[{...}]可批量更新多条。对应处理器alertSubscribePutcenter/router/router_alert_subscribe.go的语义要点按显式字段列表更新Update只更新服务端白名单列——name, disabled, prod, cate, datasource_ids, cluster, rule_id, rule_ids, tags, redefine_severity, new_severity, redefine_channels, new_channels, user_group_ids, update_at, update_by, webhooks, for_duration, redefine_webhooks, severities, extra_config, busi_groups, note, notify_rule_ids, notify_versionrule_id被强制清零源码注释说明批量订阅告警规则功能上线后改用rule_ids而非rule_id更新时置rule_id0防止遗留的旧字段引发错误订阅服务端自动覆盖UpdateBy/UpdateAt。# 先 GET 详情拿到完整对象修改后再 PUT推荐做法 curl -X PUT -H Authorization: Bearer token \ -H Content-Type: application/json \ http://n9e-host/api/n9e/busi-group/2/alert-subscribes \ -d [{ id: 123, name: 跨团队抄送-支付核心链路, disabled: 0, prod: , cate: , datasource_ids: [1, 2], cluster: 0, rule_ids: [45, 67], severities: [1, 2, 3], for_duration: 1200, tags: [{key: team, func: , value: pay}], busi_groups: [{key: groups, func: , value: 支付中心}], notify_version: 1, notify_rule_ids: [9] }]之所以强烈建议先 GET 详情 → 改完整个对象 → 再 PUT由于tags/busi_groups/webhooks/extra_config/notify_rule_ids等是序列化字段且数组字段在更新时是整体替换语义若只传部分字段未触及的序列化字段会被空值清掉。这也是站内内置工具update_alert_subscribe采用DB2FE 后再合并 patch、整行替换式UpdateFull的原因见 aiagent/tools/subscribe.go 中updateAlertSubscribe的注释merge 底座必须是 FE 形态否则未修改的序列化字段会被空 FE 值清掉。删除ids 数组curl -X DELETE -H Authorization: Bearer token \ -H Content-Type: application/json \ http://n9e-host/api/n9e/busi-group/2/alert-subscribes \ -d {ids: [123, 124, 125]}处理器alertSubscribeDel将 Body 绑定到idsForm{ids:[...]}后调用AlertSubscribeDel按主键批量删除center/router/router_alert_subscribe.go、models/alert_subscribe.go。Tryrun先验证后保存POST /api/n9e/alert-subscribe/alert-subscribes-tryrun是本套 API 中最具实战价值的端点——编辑订阅后、正式保存前先用一个历史事件试跑逐门校验匹配条件。请求体为{ event_id: 123456, config: { ...订阅草稿... } }其中event_id必须是历史告警事件 IDconfig是待验证的订阅草稿与创建接口的单个对象同构。处理器alertSubscribeTryRuncenter/router/router_alert_subscribe.go的执行顺序就是引擎实际的匹配顺序curl -X POST -H Authorization: Bearer token \ -H Content-Type: application/json \ http://n9e-host/api/n9e/alert-subscribe/alert-subscribes-tryrun \ -d { event_id: 123456, config: { name: 草稿-支付链路升级, datasource_ids: [1, 2], rule_ids: [45, 67], severities: [1, 2], tags: [{key: team, func: , value: pay}], busi_groups: [{key: groups, func: , value: 支付中心}], notify_version: 1, notify_rule_ids: [9] } }逐门校验顺序配置自检先执行Verify()配置不合法如缺severities直接报错事件存在性按event_id查历史事件不存在返回 404event not found数据源门MatchCluster比对事件DatasourceId与datasource_ids不匹配报event datasource not match告警规则门rule_ids非空时要求事件RuleId在列表中否则报event rule id not match标签门MatchTags比对事件标签与tags不匹配报event tags not match业务组名门MatchGroupsName比对事件业务组名与busi_groups注意这里匹配的是事件所属业务组的名称不匹配报event group name not match严重级别门severities含 0 表示通配否则要求事件 Severity 命中列表不匹配报event severity not match。任一扇门失败即返回对应错误信息这正是订阅没生效排查时最有用的反馈。新版本的真实通知测试如果草稿是新版本notify_version1且notify_rule_ids非空Tryrun 会进一步真实执行通知规则的发信测试逐个加载notify_rule_ids指向的通知规则对其每一个NotifyConfig调用SendNotifyChannelMessage真正发送测试通知。全部成功返回event match subscribe and notification test ok通知规则不存在返回 404发信失败返回notify rule send error: ...。如果草稿是旧版本notify_version0则走ModifyEvent逻辑校验new_channels是否选择了渠道、user_group_ids对应的用户是否为所选渠道配置了 token如钉钉/企业微信/飞书等见 center/router/router_alert_subscribe.go 对非默认渠道的跳过逻辑返回event match subscribe and notify settings ok。所以工作流应该是编辑草稿 → Tryrun 验证必要时结合返回的错误逐门修正→ 确认所有门通过后再 PUT 正式保存。生效与一致性约 9 秒缓存轮询调用写接口落库后订阅不会立刻生效——Nightingale 采用内存缓存轮询同步机制。缓存实现在 memsto/alert_subscribe_cache.goloopSyncAlertSubscribes每9000ms9 秒轮询一次通过AlertSubscribeStatistics的total/last_updated判断数据是否变化变了才全量重载见StatChanged与Set的配合重载时Disabled 1的订阅被直接过滤不进入内存表因此置disabled:1等于立刻失能置回disabled:0后最多 9 秒恢复缓存按rule_ids建索引rule_ids为空时归入 key0表示订阅所有规则的事件CompatibleWithOldRuleId保证老数据rule_id字段也能兼容见 memsto/alert_subscribe_cache.go。这意味着任何通过 API 或直接改库的变更最迟约 9 秒后生效无需重启服务。兜底方案直接修改数据库当 API 无法覆盖例如批量导入、脚本修复、极端场景下的紧急处置时可以直改数据库。约束如下与原始文档一致数据表名为alert_subscribe模型TableName()见 models/alert_subscribe.go以下列为JSON / 序列化字段修改时必须按 JSON 格式写入不能写裸字符串tagsormx.JSONArr标签过滤数组busi_groupsormx.JSONArr业务组名过滤数组webhooks回调 URL 的 JSON 字符串extra_config扩展配置 JSON 字符串notify_rule_ids/rule_idsserializer:jsondatasource_ids/severitiesDB 中为 JSON 字符串API 中为数组二者由FE2DB/DB2FE互转见 models/alert_subscribe.go直改数据库后无需重启内存缓存约 9 秒后自动重载轮询周期见上节修改前务必备份数据——序列化字段格式错误会导致该条订阅在缓存同步时被跳过syncAlertSubscribes中Parse/DB2FE失败仅记 warning 并continue见 memsto/alert_subscribe_cache.go从而静默失效。边界说明站内助手与外部 Agent 的分工最后重申这套 API 的使用边界避免误用场景正确做法Nightingale 站内 AI 助手in-app assistant使用内置 FC 工具create_alert_subscribe/update_alert_subscribe/list_alert_subscribes/get_alert_subscribe_detail不调用 HTTP API、不登录、不对自身端点发起 http_fetch外部 A2A Agent / 自动化脚本使用本文的 HTTP API携带Authorization: Bearer token给用户提供可复制执行的命令按本文 curl 模板提供仅在用户明确要求 curl 时输出不要替用户执行外部 Agent 若要完整操作订阅建议的调用序列是GET /busi-groups/alert-subscribes或GET /alert-subscribe/:sid获取现状 → 组装/修改对象 →POST /alert-subscribe/alert-subscribes-tryrun逐门验证 → 通过后再POST创建或PUT更新 → 等待约 9 秒缓存刷新后生效。这套先验证、后保存、再确认生效的闭环能把订阅误配造成的告警漏发/错发风险降到最低。参考资料仓库内接口规范原文aiagent/skill/embedded/builtin/alert-subscribe-copilot/http-api.md路由注册与中间件链center/router/router.go、权限中间件 center/router/router_mw.go处理器实现含 Tryrun 逐门校验center/router/router_alert_subscribe.go数据模型与序列化字段定义models/alert_subscribe.go内存缓存与 9 秒轮询memsto/alert_subscribe_cache.go站内内置工具实现外部 Agent 可对照参考字段形状aiagent/tools/subscribe.go【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Nightingale 订阅规则 HTTP API 实战指南：面向外部 A2A Agent 与 curl 调用的完整接口手册

相关推荐

Rust编写的嵌入式烧录与串口调试一体化工具

Milkdown 插件驱动的 Markdown 编辑器：3 步接入，5 行代码跑通

数字职业转型指南：技术路径与核心能力解析

更多资讯

Hindsight Supabase 租户扩展深度解析：本地 JWKS 验证、按用户 Schema 隔离与内置版本迁移

SpringBoot智能健康管理平台开发实践

UVR 完整教程：一键人声消除与AI音频分离

ArduPilot DroneCAN 总线嗅探器实战：用 AP_DroneCAN 例程抓取 UAVCAN 报文并解析 1Hz 统计输出

C语言指针与内存管理核心技术与实践

Cilium Gateway API 外部鉴权实战：用 ExternalAuth 过滤器把 HTTP/gRPC 鉴权下沉到独立 Auth Service

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？