Zayedkz/ai-incident-response-assistant

# AI 故障响应助手 这是一个生产级别的故障工作流服务，用于接收运维事件、构建有序的时间线，并通过确定性的方式返回包含建议响应动作的故障摘要。 本项目作为 AI 运维、可靠性工具和企业故障工作流的工程项目作品而构建。它展示了 AI 故障助手的后端基础，后续计划加入持久化存储、日志关联 worker、实时更新、LLM 摘要和复盘文档起草功能。 ## 为什么会有这个项目 故障响应通常从零散的告警、部署记录、指标、日志和聊天动态开始。团队往往会在还原事件经过、识别当前风险以及决定优先尝试哪种缓解方案上浪费大量时间。一个为 AI 准备的故障助手，在能够生成更丰富的故障指导之前，需要具备可靠的事件接收、严格的事件模型、可复现的时间线以及基于证据的摘要。 本仓库专注于上述基础能力： - 围绕具体的运维问题创建故障 - 针对告警、日志、指标、部署和人工更新的强类型事件接收 - 按事件时间戳排序的确定性时间线构建 - 基于事件严重程度的风险分类 - 受影响服务的提取 - 基于严重程度和事件来源信号推导的推荐操作 - 为持久化、关联 worker 和 LLM 摘要预留的清晰扩展点 ## 架构 ``` flowchart LR Operator[Operator or Alert Source] --> API[FastAPI API] API --> Incidents[Incident Creation] API --> Events[Typed Event Intake] Events --> Store[(In-Memory Store)] Store --> Timeline[Timeline Builder] Timeline --> Summary[Deterministic Summarizer] Summary --> Risk[Risk Classification] Summary --> Actions[Recommended Actions] FutureQueue[Future Redis Workers] --> Logs[Log Search Provider] FutureQueue --> Metrics[Metric Correlation] FutureQueue --> LLM[Evidence-Constrained LLM Summary] API --> Obs[Structured Logs + Metrics] ``` 当前的实现将存储保留在内存中，且摘要生成过程是确定性的，这使得本地开发和 CI 保持无依赖状态。PostgreSQL 和 Redis 已纳入项目规划，用于实现持久化存储、数据补充任务以及生产级别的工作流。 ## 评审人员需关注的亮点 - FastAPI 服务，具备明确的故障和事件请求模型。 - 针对告警、日志、指标、部署和人工更新的强类型事件源。 - 针对 info、warning 和 critical 信号的强类型严重程度。 - 按事件时间戳进行时间线排序，并通过稳定的事件 ID 处理同频并发情况。 - 基于观察到的最高严重程度进行风险分类。 - 根据严重程度和事件源组合动态变化的推荐操作。 - 确定性行为，无需付费 API 即可轻松测试。 - 详尽的测试，涵盖 API 流程、缺失的故障、时间线排序、风险分类以及空故障情况。 - 系统设计文档涵盖了可扩展性、可用性、故障处理、可观测性和安全性。 ## 功能 - `GET /health` 返回服务状态和环境信息。 - `POST /incidents` 创建一个故障。 - `POST /incidents/{incident_id}/events` 追加一个运维事件并返回更新后的风险级别。 - `GET /incidents/{incident_id}/summary` 返回时间线、风险、受影响的服务、摘要文本和推荐操作。 - Docker Compose 包含 PostgreSQL 和 Redis，用于规划中的持久化和队列架构。 - GitHub Actions 运行 Ruff 和 pytest。 ## 技术栈 - Python 3.12 - FastAPI - Pydantic Settings - pytest - Ruff - PostgreSQL（已规划） - Redis（已规划） - 可选的日志搜索和 LLM 提供商（已规划） - GitHub Actions ## 仓库导览 ``` app/api/ FastAPI routers for health and incident workflows app/core/ Environment-driven configuration app/incidents/ Domain models, in-memory store, and deterministic summarizer docs/ System design and production tradeoffs tests/ Unit and API tests docker-compose.yml Local PostgreSQL and Redis services for future persistence work ``` ## 本地设置 创建环境文件： ``` cp .env.example .env ``` 安装依赖项： ``` python3 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` 启动 API： ``` uvicorn app.main:app --reload ``` API 默认运行在 `http://localhost:8000`。 健康检查： ``` curl http://localhost:8000/health ``` 启动本地基础设施，为未来的持久化和 worker 工作做准备： ``` docker compose up -d ``` ## 演示流程 创建一个故障： ``` curl -X POST http://localhost:8000/incidents \ -H "Content-Type: application/json" \ -d '{"title":"Payments latency"}' ``` 添加一个部署事件： ``` curl -X POST http://localhost:8000/incidents/{incident_id}/events \ -H "Content-Type: application/json" \ -d '{ "source": "deploy", "severity": "info", "message": "Payments deploy finished.", "service": "payments", "occurred_at": "2026-07-01T12:00:00Z", "metadata": {"sha": "abc123"} }' ``` 添加一个 critical 级别的指标事件： ``` curl -X POST http://localhost:8000/incidents/{incident_id}/events \ -H "Content-Type: application/json" \ -d '{ "source": "metric", "severity": "critical", "message": "p95 latency exceeded 3 seconds.", "service": "payments", "occurred_at": "2026-07-01T12:03:00Z", "metadata": {"region": "us-east-1"} }' ``` 生成摘要： ``` curl http://localhost:8000/incidents/{incident_id}/summary ``` 摘要响应包含排序后的时间线条目、受影响的服务、风险级别、critical 事件计数、确定性摘要文本以及推荐操作。 ## 环境变量 | 变量 | 用途 | 示例 | | --- | --- | --- | | `APP_ENV` | 运行时环境标签 | `local` | | `LOG_LEVEL` | 日志详细程度 | `INFO` | | `INCIDENT_STORE` | 预留的故障存储选择器 | `memory` | | `LLM_PROVIDER` | 预留的摘要提供商选择器 | `mock` | | `DATABASE_URL` | 预留的 PostgreSQL 连接字符串 | `postgresql+psycopg://...` | | `REDIS_URL` | 预留的 Redis 连接字符串 | `redis://localhost:6381/0` | ## 测试 ``` pytest ruff check . ``` 测试套件无需 Docker、外部告警提供商、日志系统或付费模型 API 即可验证故障工作流。 ## 设计说明 更多详细信息请参阅 [docs/system-design.md](docs/system-design.md)。 关键权衡： - 确定性摘要不如 LLM 生成的摘要表现力强，但它们是可复现且易于测试的。 - 内存存储使第一阶段的切片保持轻量且易于检查；而真实的故障历史记录则需要使用 PostgreSQL。 - 内联摘要使得 API 行为对于本地演示而言非常简单；生产环境的数据补充任务应移至基于 Redis 的 worker 中处理。 - 当前服务对故障证据进行了建模，但尚未对外部告警投递的 ID 强制执行幂等性。 - 未来的 LLM 输出应限制在仅使用时间线证据，并在调用提供商前对敏感日志或客户数据进行脱敏处理。 ## 未来改进 - 添加 PostgreSQL 持久化支持和 Alembic 数据库迁移。 - 添加事件幂等键和特定于数据源的去重机制。 - 添加基于 Redis 的数据补充和关联 worker。 - 添加日志搜索和指标提供商的抽象层。 - 添加受证据约束的 LLM 摘要和复盘文档提供商。 - 添加基于 SSE 或 WebSocket 的实时故障时间线更新。 - 添加带审计历史的故障状态流转机制。

标签：AI运维, AV绕过, FastAPI, 可靠性工程, 安全规则引擎, 搜索引擎查询, 时间线构建, 测试用例, 版权保护, 运维监控, 逆向工具