v1.8.1 — 告警触发 AI 诊断 + 文档大幅扩充

2026年4月23日 · 阅读需 7 分钟

新增了接收外部告警系统事件、一站式完成关联分析 → 自动 AI 根因分析 → Slack 通知的管道。同时新增 ADR 18 篇、Runbook 5 篇、模块 CLAUDE.md 11 个、Web 指南 2 个页面（KO+EN），项目文档得到大幅加强。

核心变化

告警触发 AI 诊断（ADR-009） · 4 种 Webhook（CloudWatch/Alertmanager/Grafana/Generic） · HMAC 认证 · Slack Block Kit · 新增 ADR 18 篇 · 新增 Runbook 5 篇 · Web 指南扩充

告警触发 AI 诊断（ADR-009）

当发生严重程度为 critical 的事件（incident）时，会自动执行局部 AI 诊断。

管道流程

[CloudWatch Alarm] → SNS Topic → SQS Queue
                                    ↓
                            [EC2 Poller (15s)]
                                    ↓
[Alertmanager/Grafana/Generic] → POST /api/alert-webhook
                                    ↓
                            [alert-correlation.ts]
                                    ↓
                         [alert-diagnosis.ts (AI)]
                                    ↓
                          [Slack/SNS 发送]

支持的来源

来源	接收方式	规范化 Schema
CloudWatch Alarms	SNS → SQS → EC2 轮询	CloudWatch 事件
Prometheus Alertmanager	直接 Webhook（HMAC）	Alertmanager v4
Grafana Alerting	直接 Webhook（HMAC）	Grafana unified
Generic JSON	直接 Webhook（HMAC）	自定义 Schema

关联分析引擎

src/lib/alert-correlation.ts 将各个告警分组为事件（incident）：

标准	默认值	说明
时间窗口	5 分钟	合并同一服务 5 分钟内发生的告警
公共服务	1 个以上	`labels.service` 或 `resource` 匹配
公共命名空间	1 个以上	K8s 告警 `labels.namespace` 匹配
去重	1 分钟	抑制相同 `fingerprint` 告警在 1 分钟内的重复
严重程度升级	5 分钟内 3 条 warning	→ 升级为 critical

范围受限的自动诊断

与完整的 15 部分诊断不同，它仅限于触发告警的范围，1~2 分钟内即可完成：

构建 AlertContext — 提取受影响的服务/资源/命名空间、触发时刻（since）
范围受限采集 — 以 since 为基准 ±10 分钟过滤 CloudWatch 指标，仅限相关资源
选择相关部分 — 仅执行 Compute / Network / Container 等 3~5 个部分
变更检测 — 对比 Terraform state / CloudTrail 近期变更
Bedrock Sonnet 分析 — 推断根因 + 提出 Next Steps 建议

// src/lib/alert-diagnosis.ts (核心接口)
interface AlertContext {
  services: string[];
  resources: string[];
  namespaces: string[];
  since: Date;     // 触发时刻 − 10 分钟
  until: Date;     // 触发时刻 + 10 分钟
}

Slack 通知（Block Kit）

按严重程度进行频道路由 + 线程更新：

严重程度	默认频道	颜色
`critical`	`#incidents`	🔴 红色
`warning`	`#alerts`	🟠 橙色
`info`	`#alerts-low`	🔵 蓝色

首次告警为主消息，后续事件（追加告警合并、AI 诊断结果、已解决）作为同一线程内的 reply
Webhook 模式和 Bot Token 模式均支持线程（复用 thread_ts）
收到 CloudWatch OK 或 Alertmanager resolved 时发送 ✅ 已解决通知

HMAC 认证

共享密钥存储在 data/config.json 的 alertWebhookSecret 中：

curl -X POST https://awsops.example.com/awsops/api/alert-webhook \
  -H 'X-Alert-Source: generic' \
  -H "X-Signature-256: sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')" \
  -H 'Content-Type: application/json' \
  -d "$BODY"

告警知识库

诊断记录会永久保存在 data/alert-diagnosis/ 下：

文件	内容
`incidents/<id>.json`	单个事件 + AI 诊断结果
`summary-<YYYY-MM>.json`	月度统计（top services、alert names、resolution time）

可在 UI 的 Knowledge Base 标签页中搜索过去的类似事件，当发生新事件时会基于相似度自动推荐。

文档大幅扩充

新增 ADR 18 篇（011-028）

将 v1.8.0 中新增功能的设计决策正式化：

编号	主题
ADR-011	外部数据源集成（SSRF 防护 + allowlist）
ADR-012	SNS 通知策略
ADR-013	自动采集调查代理
ADR-014	报告生成与调度
ADR-015	AI 路由优先级
ADR-016	Bedrock 模型选择策略
ADR-017	缓存预热器设计
ADR-018	Cognito 认证流程
ADR-019	SSE 流式传输
ADR-020	HMAC Webhook 认证
ADR-021	Admin Email 权限模型
ADR-022	CDK 栈拆分
ADR-023	多路由并行执行
ADR-024	i18n（ko/en）支持
ADR-025	Code Interpreter 沙箱
ADR-026	CloudFront + Lambda@Edge
ADR-027	OpenCost + Prometheus（EKS 成本）
ADR-028	Memory Store（对话历史）

新增 Runbook 5 篇

可在实际运维场景中使用的故障排查/配置指南：

alert-pipeline-troubleshoot.md — Webhook 收不到时、关联分析无法生成事件时、Slack 不显示时
cache-warmer-operations.md — 缓存预热器调试、查询的添加/移除
cognito-auth-troubleshoot.md — Lambda@Edge、HttpOnly Cookie、OAuth2 回调问题
deploy-flow.md — 11 步部署脚本运维手册
multi-account-setup.md — Aggregator 配置、跨账户 IAM 角色、验证流程

新增模块 CLAUDE.md 11 个

将各源码模块的职责/规则/主要文件整理为 Claude 上下文文件：

路径	说明
`docs/CLAUDE.md`	文档结构
`runbooks/CLAUDE.md`	Runbook 索引
`decisions/CLAUDE.md`	ADR 索引
`agent/CLAUDE.md`	Strands Agent + 19 Lambda
`scripts/CLAUDE.md`	11 步部署脚本
`tests/CLAUDE.md`	Vitest 结构
`infra-cdk/CLAUDE.md`	CDK 栈构成
`src/app/ai-diagnosis/CLAUDE.md`	AI 综合诊断页面
`src/app/alert-settings/CLAUDE.md`	告警设置页面
`src/app/k8s/CLAUDE.md`	K8s 页面
`src/lib/collectors/CLAUDE.md`	7 种 Auto-Collect 代理

Web 指南扩充

在 Docusaurus 指南中反映了 v1.8 的功能：

monitoring/ai-diagnosis.md — 15 部分诊断、导出格式（DOCX/MD/PDF/PPTX）、调度、成本控制技巧
monitoring/alerts.md — 告警管道整体流程、HMAC、关联分析、Slack 线程、知识库
intro.md — 反映 40 页面 / 18 API / 11 AI 路由，新增「AI 综合诊断 & 告警管道」功能块
faq/troubleshooting.md — Slack 通知失败 / AI 诊断部分失败案例
韩语（docs/）+ 英语（i18n/en/docusaurus-plugin-content-docs/current/）双语均已更新

Bug 修复亮点

项目	说明
Webpack 动态 import	在采集器动态 import 中添加 `/* webpackInclude: /\.(ts\|tsx\|js)$/ */` 魔法注释 — 解决 CLAUDE.md 被包含进 webpack context 导致构建失败的问题
Bedrock 模型 ID	告警诊断使用 `global.anthropic.claude-sonnet-4-6`
Slack 线程复用	在 Webhook 模式下也保存 `thread_ts`，后续事件以 reply 发送
报告下载	使用代理 URL 代替 S3 presigned URL — 解决 STS 会话过期时的 404
SNS 邮件	将 Markdown 转换为纯文本后再发送
缓存预热器	排除 Monitoring 查询（CloudWatch FDW 调用会耗尽 pg Pool）
静默 Cookie 删除	HttpOnly Cookie 通过 `POST /api/auth` 在服务器端删除

主要文件变更

文件	变更内容
`src/app/api/alert-webhook/route.ts`	4 种来源 Webhook 接收 + HMAC 验证 + 关联分析触发 + 活动事件 GET
`src/app/api/notification/route.ts`	Slack Block Kit / SNS 发送（严重程度频道路由、Markdown→纯文本）
`src/lib/alert-types.ts`	各来源的规范化函数（CloudWatch/Alertmanager/Grafana/Generic）
`src/lib/alert-correlation.ts`	关联分析引擎（30 秒缓冲区、时间/服务/资源匹配）
`src/lib/alert-diagnosis.ts`	诊断编排器（策略选择、并行采集器、AlertContext 范围）
`src/lib/alert-knowledge.ts`	知识库（JSONL 存储、月度摘要、相似度检索）
`src/lib/slack-notification.ts`	Slack 客户端（Bot Token/Webhook、线程更新）
`src/lib/alert-sqs-poller.ts`	SQS 后台轮询器（SNS→SQS→EC2、DLQ、Rate Limit）
`src/app/alert-settings/page.tsx`	告警设置管理页面（仅限 Admin）
`docs/decisions/ADR-011~028.md`	新增 18 篇 ADR
`docs/runbooks/*.md`	新增 5 篇 Runbook
`web/docs/monitoring/ai-diagnosis.md`	AI 综合诊断指南
`web/docs/monitoring/alerts.md`	告警管道指南

版本对比

项目	v1.8.0	v1.8.1	变更
告警管道	—	Webhook + 关联分析 + AI 诊断	新增
支持的告警来源	—	4 种（CloudWatch/Alertmanager/Grafana/Generic）	新增
Slack 通知	—	Block Kit + 线程更新	新增
ADR	10 篇（001-010）	28 篇（001-028）	+18
Runbook	—	5 篇	新增
模块 CLAUDE.md	7 个	18 个	+11
Web 指南页面	39	41	+2（ai-diagnosis、alerts）

参考

ADR-009: 告警触发 AI 诊断
ADR-012: SNS 通知策略
ADR-013: 自动采集调查代理
ADR-020: HMAC Webhook 认证

告警触发 AI 诊断（ADR-009）​

管道流程​

支持的来源​

关联分析引擎​

范围受限的自动诊断​

Slack 通知（Block Kit）​

HMAC 认证​

告警知识库​

文档大幅扩充​

新增 ADR 18 篇（011-028）​

新增 Runbook 5 篇​

新增模块 CLAUDE.md 11 个​

Web 指南扩充​

Bug 修复亮点​

主要文件变更​

版本对比​

参考​