Yaph123/AI-Incident-Response-System.
GitHub: Yaph123/AI-Incident-Response-System.
通过 webhook 接入告警并利用 AI 自动收集运维上下文、生成总结和复盘草稿的结构化事件响应系统。
Stars: 0 | Forks: 0
# AI 事件响应系统
接入告警，收集运维上下文，运行 AI 辅助的分诊 pipeline，并确保每个事件步骤都可追溯——从 webhook 到复盘草稿。
这是一个活跃的个人项目，旨在探索 AI 如何在不变成不透明聊天机器人的情况下支持**结构化的事件响应**。由 [Yaphet Bekele](https://github.com/Yaph123) 构建 —— USC 计算机科学与认知科学专业（理学/文学学士，2027 年 12 月）。如果你尝试了它、fork 了它，或者有任何想法，请使用 [GitHub Issues](https://github.com/Yaph123/AI-Incident-Response-System./issues) 分享反馈。
## 为什么开发这个系统
大多数 on-call 工作流仍然将上下文分散在 Slack 讨论串、监控 dashboard、GitHub 和 runbook wiki 中。当凌晨 2 点出现问题并发生故障时，最困难的部分不仅仅是*看到*告警，而是足够快地将正确的上下文汇集起来以便采取行动。
我想要一个这样的系统：
- **告警成为事件**，并拥有持久的记录，而不是被遗忘的通知。
- **上下文被自动收集**——最近的部署、PR、匹配的 runbook——在任何人在此之前从零开始写总结之前。
- **AI 提供协助但不取代人类判断**——总结和复盘草稿都是你可以审查、编辑和批准的建议。
- **每一步都被记录为**事件时间线上的一个事件，这样你就可以回答：发生了什么，什么时候发生的，以及系统做了什么？
这个仓库是该愿景的第一部分——一个全栈 MVP 脚手架，在生产环境加固之前端到端验证整个 pipeline。
## 适用人群
AI 事件响应是一个**运维分诊和文档系统**——而不是你的 on-call 轮值或 incident commander 的替代品。
**典型用户**
- 希望通过自动收集上下文来实现 webhook 驱动的事件接入的 **SRE 和平台工程师**
- 希望将 AI 生成的总结和复盘草稿与真实事件记录关联起来的 **On-call 负责人**
- 在投资企业级工具之前，原型化 AI 辅助事件工作流的**小团队**
**它不是什么**
- 不是 PagerDuty、Datadog 或你现有告警 stack 的替代品——它通过 webhook 从它们那里接入数据
- 不是一个完全自主的事件解决器——你需要审查 AI 的输出并控制 Slack 的发布
- 开箱即用并不具备生产环境的健壮性——auth、RBAC、幂等性和 observability 仍需完善
**如何使用它（愿景）**
1. 在目录中注册服务和 runbook。
2. 将你的监控工具指向告警 webhook。
3. 系统创建一个事件，将 Celery worker 加入队列，并运行 pipeline。
4. 审查 dashboard、事件详情 API、AI 总结、evidence 和复盘草稿。
5. 根据需要更新状态、重新运行 pipeline 或批准 Slack 发布。
## 它的功能
当告警 webhook 到达时，系统会创建一个**事件**和**告警**记录，记录一个 `alert_received` 事件，并将异步处理任务加入队列。然后，Celery worker 会推动事件进入调查阶段：GitHub 上下文获取、runbook 匹配、AI 总结生成、Slack 通知（或批准关卡）以及复盘草稿创建。
- 接受来自任何来源的 webhook 告警（`POST /api/alerts/webhook`）。
- 在 PostgreSQL 中持久化事件、告警、事件、evidence、Slack 消息、复盘草稿、服务、runbook 和审批记录。
- 当服务配置了 repo 时，获取最近的 GitHub commits 和 PR。
- 通过关键字搜索匹配 runbook 并将其作为 evidence 附加。
- 生成 AI 事件总结和复盘草稿（配置后使用 OpenAI；否则使用安全的存根 stub）。
- 通过 webhook 或 bot token 发布到 Slack——或者在 `REQUIRE_APPROVAL_FOR_SLACK=true` 时将其暂存以供批准。
- 渲染一个简单的 Next.js dashboard，列出活跃事件和 AI 总结。
## 核心功能
- **Webhook 接入** — 将来自 Datadog、PagerDuty、Grafana 或自定义来源的告警标准化为事件
- **事件时间线** — 每个 pipeline 步骤都记录为一个 `incident_event`，包含类型、消息和 payload
- **Evidence 模型** — 将 GitHub commits/PR、匹配的 runbook 以及未来的手动/AI evidence 集中在一处
- **服务目录** — 将服务映射到负责团队、GitHub repo 和 Slack 频道
- **Runbook 存储** — 创建带有可选 pgvector embeddings 的 runbook，用于未来的语义搜索
- **AI 推理层** — 由 OpenAI 驱动的总结和复盘草稿，带有结构化的 fallback stub
- **Slack 协作** — 将事件更新发布到频道，或要求先进行审批
- **异步编排** — Celery + Redis，确保 webhook 响应保持快速，同时处理在后台运行
- **Dashboard** — 在 `http://localhost:3000` 的 Next.js UI，用于一目了然地监控事件
- **Docker Compose** — 一条命令即可在本地运行 Postgres、Redis、API、worker 和前端
## 当前状态
**已实现**
- 带有 health、alerts、incidents、runbooks 和 services 路由的 FastAPI 后端
- 所有核心实体的 SQLAlchemy 模型（见下表）
- 带有 `process_incident` 任务的 Celery worker
- 事件 pipeline：状态 → GitHub 上下文 → AI 总结 → Slack → 复盘草稿
- OpenAI、Slack 和 GitHub 集成（对于本地开发都是可选的）
- Next.js dashboard（事件列表 + 状态徽章 + AI 总结预览）
- Docker Compose stack（Postgres + pgvector，Redis，后端，worker，前端）
- GitHub Actions CI（后端 import 冒烟测试 + 前端构建）
- 后端启动时自动创建表（启用 pgvector 扩展）
**计划中**
- Alembic 迁移（替换启动时的 `create_all`）
- Runbook 的向量相似度搜索（已存储 embeddings；目前仅支持关键字搜索）
- 前端的事件详情页（API 已支持 `GET /api/incidents/{id}`）
- Auth、RBAC 和多租户隔离
- Webhook 签名验证和幂等键
- 审批工作流 UI（批准/拒绝暂存的 Slack 发布）
- 超越通用 webhook 的 PagerDuty / Datadog 原生集成
- Observability：平台自身的结构化指标、tracing 和告警
该仓库演进迅速；其核心模式——告警 → 事件 → 异步 pipeline → 可追溯事件——是稳定的，但针对生产环境的加固仍处于早期阶段。
## 架构
包含两个视图：**(1) 事件响应 pipeline**——告警触发时会发生什么——以及 **(2) 应用 stack**——软件是如何构建的。
### 事件 pipeline（告警 → 解决）
每个**事件**都是核心记录。每个 **pipeline 步骤**都会写入事件和 evidence。处理任务在 webhook 返回后通过 Celery 异步运行。
```
flowchart TB
WH["Webhook Alert
POST /api/alerts/webhook"] WH -->|"Ingest ✅"| INC["Incident + Alert
status: open"] INC -->|"Celery queue ✅"| W["Worker: process_incident"] W -->|"Status ✅"| INV["investigating"] INV -->|"GitHub context ✅"| EV1["Evidence: commits, PRs"] EV1 -->|"Runbook match ✅"| EV2["Evidence: runbooks"] EV2 -->|"AI summary ✅"| AI["ai_summary + recommendations"] AI -->|"Slack ✅"| SL["Slack message or approval gate"] SL -->|"Postmortem ✅"| PM["Postmortem draft"] classDef done fill:#ecfdf5,stroke:#059669,stroke-width:2px classDef root fill:#eef2ff,stroke:#4f46e5,stroke-width:2px class WH root class INC,W,INV,EV1,EV2,AI,SL,PM done ``` | 步骤 | 服务 / 模块 | 写入 | 状态 | |------|------------------|--------|--------| | **接入告警** | `services/ingestion` | `Incident`, `Alert`, `alert_received` 事件 | ✅ 已实现 | | **队列 worker** | `workers/tasks` | Celery 任务 | ✅ 已实现 | | **GitHub 上下文** | `services/context` + `integrations/github` | `EvidenceItem` (commits, PRs) | ✅ 已实现 (需要 `GITHUB_TOKEN` + repo) | | **Runbook 匹配** | `services/context` | `EvidenceItem` (runbooks) | ✅ 关键字搜索 | | **AI 总结** | `services/ai` + `integrations/openai_client` | `ai_summary`, `ai_recommendations` | ✅ LLM 或 stub | | **Slack 通知** | `services/orchestration` + `integrations/slack` | `SlackMessage`，可选 `Approval` | ✅ Webhook, bot 或本地日志 | | **复盘草稿** | `services/ai` | `PostmortemDraft` | ✅ LLM 或 stub | **手动 / API 步骤** | 操作 | 方式 | |--------|-----| | 注册服务 | `POST /api/services` | | 添加 runbook | `POST /api/runbooks` | | 更新事件状态 | `PATCH /api/incidents/{id}` | | 重新运行 pipeline | `POST /api/incidents/{id}/run` | **规则 (pipeline)** 1. Webhook 同步创建事件 + 告警并立即返回。 2. Celery worker 异步运行 `run_incident_pipeline`。 3. 每一步都会记录一个事件并持久化 evidence，然后再继续下一步。 4. Slack 发布遵循 `REQUIRE_APPROVAL_FOR_SLACK`——如果为 true，则会创建一个 `Approval` 记录而不是直接发布。 ``` flowchart LR IG["Ingestion"] CX["Context"] AI["AI Reasoning"] CO["Collaboration"] PS["Persistence"] IG --> CX --> AI --> CO --> PS ``` 那一行是**逻辑层顺序**——接入、上下文获取、AI 推理、协作和持久化（事件 + evidence + 草稿）。 ### 应用 stack（软件） ``` ┌─────────────────────────────────────────────────────────────────────┐ │ AI Incident Response System (Docker Compose) │ │ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────┐ │ │ │ Next.js frontend │ │ FastAPI backend │ │ Celery worker │ │ │ │ · Incident list │◄─┤ · REST API │◄─┤ · process_ │ │ │ │ · Status badges │ │ · Webhook ingest │ │ incident │ │ │ │ · AI summary peek │ │ · Orchestration │ │ │ │ │ └────────────────────┘ └─────────┬──────────┘ └───────┬────────┘ │ │ │ │ │ │ ┌─────────▼──────────┐ ┌───────▼────────┐ │ │ │ PostgreSQL + │ │ Redis │ │ │ │ pgvector │ │ (Celery broker)│ │ │ └────────────────────┘ └────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ │ ▼ OpenAI · Slack · GitHub (optional integrations) ``` | 层级 | 角色 | |--------|------| | **前端** | Next.js dashboard；从 API 获取事件 | | **API** | 用于 webhook、事件、runbook、服务的 FastAPI 路由 | | **服务** | 接入、上下文、AI、编排业务逻辑 | | **Worker** | Celery 异步 pipeline 执行 | | **集成** | OpenAI、Slack webhook/bot、GitHub REST API | | **数据库** | 带有 pgvector 的 PostgreSQL，用于 runbook embeddings | | **队列** | 用作 Celery broker 和结果 backend 的 Redis | ### 数据模型 | 表 | 用途 | |--------|---------| | `service_catalog` | 包含负责团队、GitHub repo、Slack 频道的服务 | | `runbooks` | Runbook 内容、标签、可选的 vector embedding | | `incidents` | 包含状态、严重性、AI 字段的核心事件记录 | | `alerts` | 链接到事件的原始告警 payload | | `incident_events` | pipeline 和手动操作的时间线 | | `evidence_items` | GitHub、runbook、告警、手动或 AI evidence | | `slack_messages` | 出站的 Slack 消息（已发布或已暂存） | | `postmortem_drafts` | AI 生成的复盘，包含时间线和待办事项 | | `approvals` | 针对敏感操作（例如 Slack 发布）的审批关卡 | **事件状态：** `open` → `investigating` → `mitigated` → `resolved` ## 独特之处 - **是 Pipeline 而非聊天** — 事件是带有事件和 evidence 的结构化记录，而不是单一的 LLM 线程 - **总结前先获取上下文** — 在 AI 撰写任何内容之前，会先收集 GitHub 和 runbook evidence - **默认异步** — Webhook 快速返回；繁重的工作在 Celery 中运行 - **审批关卡** — Slack 发布在发送前可要求人工批准 - **Stub 安全的本地开发** — 无需 OpenAI、Slack 或 GitHub 密钥即可运行完整流程 - **可追溯的时间线** — 每一个自动化和手动操作都是一个 `incident_event` ## 后续计划 - **Alembic 迁移** — 版本化的 schema 以取代启动时的 `create_all` - **向量 runbook 搜索** — 使用存储的 pgvector embeddings 进行语义匹配 - **前端事件详情** — 时间线、evidence 面板、复盘查看器 - **Webhook 认证** — 针对每个告警源的 HMAC 签名验证 - **审批 UI** — 审查并批准/拒绝暂存的 Slack 消息 - **重新运行和分支** — 在不重复 evidence 的情况下部分重新运行 pipeline - **原生集成** — PagerDuty、Datadog、Grafana 告警格式化器 - **生产部署** — Kubernetes manifests、secrets 管理、observability ## 技术栈 - **Next.js 14** + **TypeScript** + **Tailwind CSS** — dashboard UI - **FastAPI** + **Python 3.12** — REST API 和编排 - **SQLAlchemy 2** — ORM 和模型 - **PostgreSQL 16** + **pgvector** — 持久化和 runbook embeddings - **Redis 7** — Celery broker 和结果 backend - **Celery 5** — 异步事件 pipeline worker - **OpenAI API** — 总结、复盘、embeddings（可选） - **Slack** — 用于事件通知的 webhook 或 bot token（可选） - **GitHub REST API** — 获取最近的 commits 和 PR 作为上下文（可选） - **Docker Compose** — 本地多服务开发 ## 快速开始 ### 前置条件 - **Docker** **Docker Compose** — 推荐用于运行完整 stack - **Git** — 用于克隆和版本控制 - **Node.js 20+** — 仅当在 Docker 外部运行前端时需要 - **Python 3.12+** — 仅当在 Docker 外部运行后端时需要 ### 安装 ``` git clone git@github.com:Yaph123/AI-Incident-Response-System..git cd AI-Incident-Response ``` 复制环境文件： ``` cp .env.example .env ``` ### 运行 stack ``` docker compose up --build ``` 打开： - **Dashboard:** `http://localhost:3000` - **API 文档:** `http://localhost:8000/docs` - **健康检查:** `http://localhost:8000/api/healthz` 常用命令： ``` docker compose up -d # run in background docker compose logs -f worker # watch Celery pipeline logs docker compose down # stop all services docker compose down -v # stop and remove database volume ``` ### API 密钥（可选） 集成是可选的。如果没有密钥，系统将使用安全的 stub 和本地日志记录，以便你探索完整流程。 编辑项目根目录下的 `.env`。**切勿提交 `.env`。** **OpenAI（总结、复盘、embeddings）：** ``` OPENAI_API_KEY=sk-proj-your-key-here OPENAI_MODEL=gpt-4o-mini ``` **Slack（事件通知）：** ``` # 选项 A: incoming webhook SLACK_WEBHOOK_URL=https://hooks.slack.com/services/... # 选项 B: bot token SLACK_BOT_TOKEN=xoxb-your-token SLACK_DEFAULT_CHANNEL=#incidents ``` **GitHub（作为 evidence 的最近 commits 和 PR）：** ``` GITHUB_TOKEN=ghp_your_token_here GITHUB_DEFAULT_OWNER=your-org GITHUB_DEFAULT_REPO=your-repo ``` **Slack 的审批关卡：** ``` REQUIRE_APPROVAL_FOR_SLACK=true ``` 启用后，Slack 消息将被暂存，并创建一个 `Approval` 记录，而不是立即发布。 | 变量 | 默认值 | 用途 | |----------|---------|---------| | `DATABASE_URL` | `postgresql+psycopg://incident:incident@localhost:5433/incident_response` | Postgres 连接 | | `REDIS_URL` | `redis://localhost:6379/0` | Celery broker | | `OPENAI_MODEL` | `gpt-4o-mini` | 用于总结和复盘的 Chat 模型 | | `SLACK_DEFAULT_CHANNEL` | `#incidents` | Fallback Slack 频道 | | `LOG_LEVEL` | `INFO` | Structlog 详细程度 | | `NEXT_PUBLIC_API_URL` | `http://localhost:8000` | 前端 → API 基础 URL | ### 首次运行 1. 启动 stack: `docker compose up --build` 2. 注册服务（可选但推荐）： curl -X POST http://localhost:8000/api/services \ -H "Content-Type: application/json" \ -d '{ "name": "payments", "owner_team": "sre", "github_repo": "YOUR_ORG/YOUR_REPO", "slack_channel": "#incidents" }' 3. 添加 runbook： curl -X POST http://localhost:8000/api/runbooks \ -H "Content-Type: application/json" \ -d '{ "title": "High 5xx Error Rate", "content": "Check latest deploy, rollback if needed, verify DB latency.", "service_name": "payments", "tags": ["http", "errors"] }' 4. 发送测试告警： curl -X POST http://localhost:8000/api/alerts/webhook \ -H "Content-Type: application/json" \ -d '{ "source": "datadog", "title": "Payments API 5xx spike", "severity": "high", "service_name": "payments", "description": "5xx above threshold for 10 minutes", "payload": {"monitor_id": "12345"} }' 5. 观看 worker 处理 pipeline： docker compose logs -f worker 6. 查看结果： - Dashboard: `http://localhost:3000` - 事件列表: `curl http://localhost:8000/api/incidents` - 事件详情（替换 `{id}`）: `curl http://localhost:8000/api/incidents/{id}` ### API 参考 (MVP) | 方法 | Endpoint | 描述 | |--------|----------|-------------| | `GET` | `/api/healthz` | 健康检查 | | `POST` | `/api/alerts/webhook` | 接入告警 → 创建事件 → 加入 pipeline 队列 | | `GET` | `/api/incidents` | 列出事件（最近 100 条） | | `GET` | `/api/incidents/{id}` | 包含事件、evidence、Slack、复盘的事件详情 | | `PATCH` | `/api/incidents/{id}` | 更新标题、描述、状态、严重程度、负责人 | | `POST` | `/api/incidents/{id}/run` | 同步重新运行完整 pipeline | | `GET` | `/api/runbooks` | 列出 runbook（可选 `?query=` 过滤器） | | `POST` | `/api/runbooks` | 创建 runbook 并索引 embedding | | `GET` | `/api/services` | 列出服务 | | `POST` | `/api/services` | 注册服务 | 包含请求/响应 schema 的交互式文档：`http://localhost:8000/docs` ## 项目结构 ``` AI-Incident-Response/ ├── backend/ │ ├── app/ │ │ ├── api/routes/ # FastAPI route handlers │ │ ├── core/ # config, database, logging │ │ ├── integrations/ # OpenAI, Slack, GitHub clients │ │ ├── models/ # SQLAlchemy models and enums │ │ ├── schemas/ # Pydantic request/response schemas │ │ ├── services/ # ingestion, context, AI, orchestration │ │ ├── workers/ # Celery app and tasks │ │ └── main.py # FastAPI entrypoint │ ├── Dockerfile │ └── requirements.txt ├── frontend/ │ ├── app/ # Next.js App Router pages │ ├── lib/ # API client helpers │ ├── Dockerfile │ └── package.json ├── infra/ │ └── docker-compose.yml # alternate compose path ├── .github/workflows/ │ └── ci.yml # backend + frontend CI ├── docker-compose.yml # primary local stack ├── .env.example └── README.md ``` ## 推送到 GitHub (SSH) 该仓库使用 SSH 进行 Git 操作。GitHub 上的仓库名称以句号结尾： ``` git remote -v # should show git@github.com:Yaph123/AI-Incident-Response-System..git git push ``` 如果需要设置 remote： ``` git remote set-url origin git@github.com:Yaph123/AI-Incident-Response-System..git ``` ## 备注 - 表在后端启动时自动创建（`Base.metadata.create_all`）。对于生产环境，请迁移到 Alembic。 - Runbook embeddings 存储在 pgvector 中，但搜索目前使用的是关键字 `ILIKE` 匹配。 - 这是一个独立于 [Research OS (Mimir)](https://github.com/Yaph123/Research-OS) 的**独立项目**——它们位于同级目录中，服务于不同的领域。
POST /api/alerts/webhook"] WH -->|"Ingest ✅"| INC["Incident + Alert
status: open"] INC -->|"Celery queue ✅"| W["Worker: process_incident"] W -->|"Status ✅"| INV["investigating"] INV -->|"GitHub context ✅"| EV1["Evidence: commits, PRs"] EV1 -->|"Runbook match ✅"| EV2["Evidence: runbooks"] EV2 -->|"AI summary ✅"| AI["ai_summary + recommendations"] AI -->|"Slack ✅"| SL["Slack message or approval gate"] SL -->|"Postmortem ✅"| PM["Postmortem draft"] classDef done fill:#ecfdf5,stroke:#059669,stroke-width:2px classDef root fill:#eef2ff,stroke:#4f46e5,stroke-width:2px class WH root class INC,W,INV,EV1,EV2,AI,SL,PM done ``` | 步骤 | 服务 / 模块 | 写入 | 状态 | |------|------------------|--------|--------| | **接入告警** | `services/ingestion` | `Incident`, `Alert`, `alert_received` 事件 | ✅ 已实现 | | **队列 worker** | `workers/tasks` | Celery 任务 | ✅ 已实现 | | **GitHub 上下文** | `services/context` + `integrations/github` | `EvidenceItem` (commits, PRs) | ✅ 已实现 (需要 `GITHUB_TOKEN` + repo) | | **Runbook 匹配** | `services/context` | `EvidenceItem` (runbooks) | ✅ 关键字搜索 | | **AI 总结** | `services/ai` + `integrations/openai_client` | `ai_summary`, `ai_recommendations` | ✅ LLM 或 stub | | **Slack 通知** | `services/orchestration` + `integrations/slack` | `SlackMessage`，可选 `Approval` | ✅ Webhook, bot 或本地日志 | | **复盘草稿** | `services/ai` | `PostmortemDraft` | ✅ LLM 或 stub | **手动 / API 步骤** | 操作 | 方式 | |--------|-----| | 注册服务 | `POST /api/services` | | 添加 runbook | `POST /api/runbooks` | | 更新事件状态 | `PATCH /api/incidents/{id}` | | 重新运行 pipeline | `POST /api/incidents/{id}/run` | **规则 (pipeline)** 1. Webhook 同步创建事件 + 告警并立即返回。 2. Celery worker 异步运行 `run_incident_pipeline`。 3. 每一步都会记录一个事件并持久化 evidence，然后再继续下一步。 4. Slack 发布遵循 `REQUIRE_APPROVAL_FOR_SLACK`——如果为 true，则会创建一个 `Approval` 记录而不是直接发布。 ``` flowchart LR IG["Ingestion"] CX["Context"] AI["AI Reasoning"] CO["Collaboration"] PS["Persistence"] IG --> CX --> AI --> CO --> PS ``` 那一行是**逻辑层顺序**——接入、上下文获取、AI 推理、协作和持久化（事件 + evidence + 草稿）。 ### 应用 stack（软件） ``` ┌─────────────────────────────────────────────────────────────────────┐ │ AI Incident Response System (Docker Compose) │ │ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────┐ │ │ │ Next.js frontend │ │ FastAPI backend │ │ Celery worker │ │ │ │ · Incident list │◄─┤ · REST API │◄─┤ · process_ │ │ │ │ · Status badges │ │ · Webhook ingest │ │ incident │ │ │ │ · AI summary peek │ │ · Orchestration │ │ │ │ │ └────────────────────┘ └─────────┬──────────┘ └───────┬────────┘ │ │ │ │ │ │ ┌─────────▼──────────┐ ┌───────▼────────┐ │ │ │ PostgreSQL + │ │ Redis │ │ │ │ pgvector │ │ (Celery broker)│ │ │ └────────────────────┘ └────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ │ ▼ OpenAI · Slack · GitHub (optional integrations) ``` | 层级 | 角色 | |--------|------| | **前端** | Next.js dashboard；从 API 获取事件 | | **API** | 用于 webhook、事件、runbook、服务的 FastAPI 路由 | | **服务** | 接入、上下文、AI、编排业务逻辑 | | **Worker** | Celery 异步 pipeline 执行 | | **集成** | OpenAI、Slack webhook/bot、GitHub REST API | | **数据库** | 带有 pgvector 的 PostgreSQL，用于 runbook embeddings | | **队列** | 用作 Celery broker 和结果 backend 的 Redis | ### 数据模型 | 表 | 用途 | |--------|---------| | `service_catalog` | 包含负责团队、GitHub repo、Slack 频道的服务 | | `runbooks` | Runbook 内容、标签、可选的 vector embedding | | `incidents` | 包含状态、严重性、AI 字段的核心事件记录 | | `alerts` | 链接到事件的原始告警 payload | | `incident_events` | pipeline 和手动操作的时间线 | | `evidence_items` | GitHub、runbook、告警、手动或 AI evidence | | `slack_messages` | 出站的 Slack 消息（已发布或已暂存） | | `postmortem_drafts` | AI 生成的复盘，包含时间线和待办事项 | | `approvals` | 针对敏感操作（例如 Slack 发布）的审批关卡 | **事件状态：** `open` → `investigating` → `mitigated` → `resolved` ## 独特之处 - **是 Pipeline 而非聊天** — 事件是带有事件和 evidence 的结构化记录，而不是单一的 LLM 线程 - **总结前先获取上下文** — 在 AI 撰写任何内容之前，会先收集 GitHub 和 runbook evidence - **默认异步** — Webhook 快速返回；繁重的工作在 Celery 中运行 - **审批关卡** — Slack 发布在发送前可要求人工批准 - **Stub 安全的本地开发** — 无需 OpenAI、Slack 或 GitHub 密钥即可运行完整流程 - **可追溯的时间线** — 每一个自动化和手动操作都是一个 `incident_event` ## 后续计划 - **Alembic 迁移** — 版本化的 schema 以取代启动时的 `create_all` - **向量 runbook 搜索** — 使用存储的 pgvector embeddings 进行语义匹配 - **前端事件详情** — 时间线、evidence 面板、复盘查看器 - **Webhook 认证** — 针对每个告警源的 HMAC 签名验证 - **审批 UI** — 审查并批准/拒绝暂存的 Slack 消息 - **重新运行和分支** — 在不重复 evidence 的情况下部分重新运行 pipeline - **原生集成** — PagerDuty、Datadog、Grafana 告警格式化器 - **生产部署** — Kubernetes manifests、secrets 管理、observability ## 技术栈 - **Next.js 14** + **TypeScript** + **Tailwind CSS** — dashboard UI - **FastAPI** + **Python 3.12** — REST API 和编排 - **SQLAlchemy 2** — ORM 和模型 - **PostgreSQL 16** + **pgvector** — 持久化和 runbook embeddings - **Redis 7** — Celery broker 和结果 backend - **Celery 5** — 异步事件 pipeline worker - **OpenAI API** — 总结、复盘、embeddings（可选） - **Slack** — 用于事件通知的 webhook 或 bot token（可选） - **GitHub REST API** — 获取最近的 commits 和 PR 作为上下文（可选） - **Docker Compose** — 本地多服务开发 ## 快速开始 ### 前置条件 - **Docker** **Docker Compose** — 推荐用于运行完整 stack - **Git** — 用于克隆和版本控制 - **Node.js 20+** — 仅当在 Docker 外部运行前端时需要 - **Python 3.12+** — 仅当在 Docker 外部运行后端时需要 ### 安装 ``` git clone git@github.com:Yaph123/AI-Incident-Response-System..git cd AI-Incident-Response ``` 复制环境文件： ``` cp .env.example .env ``` ### 运行 stack ``` docker compose up --build ``` 打开： - **Dashboard:** `http://localhost:3000` - **API 文档:** `http://localhost:8000/docs` - **健康检查:** `http://localhost:8000/api/healthz` 常用命令： ``` docker compose up -d # run in background docker compose logs -f worker # watch Celery pipeline logs docker compose down # stop all services docker compose down -v # stop and remove database volume ``` ### API 密钥（可选） 集成是可选的。如果没有密钥，系统将使用安全的 stub 和本地日志记录，以便你探索完整流程。 编辑项目根目录下的 `.env`。**切勿提交 `.env`。** **OpenAI（总结、复盘、embeddings）：** ``` OPENAI_API_KEY=sk-proj-your-key-here OPENAI_MODEL=gpt-4o-mini ``` **Slack（事件通知）：** ``` # 选项 A: incoming webhook SLACK_WEBHOOK_URL=https://hooks.slack.com/services/... # 选项 B: bot token SLACK_BOT_TOKEN=xoxb-your-token SLACK_DEFAULT_CHANNEL=#incidents ``` **GitHub（作为 evidence 的最近 commits 和 PR）：** ``` GITHUB_TOKEN=ghp_your_token_here GITHUB_DEFAULT_OWNER=your-org GITHUB_DEFAULT_REPO=your-repo ``` **Slack 的审批关卡：** ``` REQUIRE_APPROVAL_FOR_SLACK=true ``` 启用后，Slack 消息将被暂存，并创建一个 `Approval` 记录，而不是立即发布。 | 变量 | 默认值 | 用途 | |----------|---------|---------| | `DATABASE_URL` | `postgresql+psycopg://incident:incident@localhost:5433/incident_response` | Postgres 连接 | | `REDIS_URL` | `redis://localhost:6379/0` | Celery broker | | `OPENAI_MODEL` | `gpt-4o-mini` | 用于总结和复盘的 Chat 模型 | | `SLACK_DEFAULT_CHANNEL` | `#incidents` | Fallback Slack 频道 | | `LOG_LEVEL` | `INFO` | Structlog 详细程度 | | `NEXT_PUBLIC_API_URL` | `http://localhost:8000` | 前端 → API 基础 URL | ### 首次运行 1. 启动 stack: `docker compose up --build` 2. 注册服务（可选但推荐）： curl -X POST http://localhost:8000/api/services \ -H "Content-Type: application/json" \ -d '{ "name": "payments", "owner_team": "sre", "github_repo": "YOUR_ORG/YOUR_REPO", "slack_channel": "#incidents" }' 3. 添加 runbook： curl -X POST http://localhost:8000/api/runbooks \ -H "Content-Type: application/json" \ -d '{ "title": "High 5xx Error Rate", "content": "Check latest deploy, rollback if needed, verify DB latency.", "service_name": "payments", "tags": ["http", "errors"] }' 4. 发送测试告警： curl -X POST http://localhost:8000/api/alerts/webhook \ -H "Content-Type: application/json" \ -d '{ "source": "datadog", "title": "Payments API 5xx spike", "severity": "high", "service_name": "payments", "description": "5xx above threshold for 10 minutes", "payload": {"monitor_id": "12345"} }' 5. 观看 worker 处理 pipeline： docker compose logs -f worker 6. 查看结果： - Dashboard: `http://localhost:3000` - 事件列表: `curl http://localhost:8000/api/incidents` - 事件详情（替换 `{id}`）: `curl http://localhost:8000/api/incidents/{id}` ### API 参考 (MVP) | 方法 | Endpoint | 描述 | |--------|----------|-------------| | `GET` | `/api/healthz` | 健康检查 | | `POST` | `/api/alerts/webhook` | 接入告警 → 创建事件 → 加入 pipeline 队列 | | `GET` | `/api/incidents` | 列出事件（最近 100 条） | | `GET` | `/api/incidents/{id}` | 包含事件、evidence、Slack、复盘的事件详情 | | `PATCH` | `/api/incidents/{id}` | 更新标题、描述、状态、严重程度、负责人 | | `POST` | `/api/incidents/{id}/run` | 同步重新运行完整 pipeline | | `GET` | `/api/runbooks` | 列出 runbook（可选 `?query=` 过滤器） | | `POST` | `/api/runbooks` | 创建 runbook 并索引 embedding | | `GET` | `/api/services` | 列出服务 | | `POST` | `/api/services` | 注册服务 | 包含请求/响应 schema 的交互式文档：`http://localhost:8000/docs` ## 项目结构 ``` AI-Incident-Response/ ├── backend/ │ ├── app/ │ │ ├── api/routes/ # FastAPI route handlers │ │ ├── core/ # config, database, logging │ │ ├── integrations/ # OpenAI, Slack, GitHub clients │ │ ├── models/ # SQLAlchemy models and enums │ │ ├── schemas/ # Pydantic request/response schemas │ │ ├── services/ # ingestion, context, AI, orchestration │ │ ├── workers/ # Celery app and tasks │ │ └── main.py # FastAPI entrypoint │ ├── Dockerfile │ └── requirements.txt ├── frontend/ │ ├── app/ # Next.js App Router pages │ ├── lib/ # API client helpers │ ├── Dockerfile │ └── package.json ├── infra/ │ └── docker-compose.yml # alternate compose path ├── .github/workflows/ │ └── ci.yml # backend + frontend CI ├── docker-compose.yml # primary local stack ├── .env.example └── README.md ``` ## 推送到 GitHub (SSH) 该仓库使用 SSH 进行 Git 操作。GitHub 上的仓库名称以句号结尾： ``` git remote -v # should show git@github.com:Yaph123/AI-Incident-Response-System..git git push ``` 如果需要设置 remote： ``` git remote set-url origin git@github.com:Yaph123/AI-Incident-Response-System..git ``` ## 备注 - 表在后端启动时自动创建（`Base.metadata.create_all`）。对于生产环境，请迁移到 Alembic。 - Runbook embeddings 存储在 pgvector 中，但搜索目前使用的是关键字 `ILIKE` 匹配。 - 这是一个独立于 [Research OS (Mimir)](https://github.com/Yaph123/Research-OS) 的**独立项目**——它们位于同级目录中，服务于不同的领域。
标签：AI辅助, SRE, 事故响应, 偏差过滤, 搜索引擎查询, 测试用例, 版权保护, 自动化运维, 运维, 逆向工具