shakshamsharma/AI-Powered-DevOps-Incident-Response-Analysis-Platform

# IncidentPilot AI IncidentPilot AI 是一个由 AI 驱动的 DevOps 事件助手。它通过 SNS 接收 AWS CloudWatch 警报，创建持久化的事件记录，并使用 runbook 上下文对其进行丰富，运行兼容 OpenAI 的根因分析，生成 Markdown/HTML 报告，并发送 Slack/SES 通知。 ## 架构 ``` flowchart LR CW["CloudWatch Alarm"] --> SNS["SNS Topic"] SNS --> API["FastAPI /webhooks/sns"] API --> SVC["Incident Service"] SVC --> DB[("PostgreSQL")] SVC --> RAG["LangChain + FAISS Runbooks"] SVC --> AI["OpenAI-Compatible Analysis"] AI --> SVC SVC --> REP["Markdown/HTML Reports"] SVC --> SLACK["Slack Webhook"] SVC --> SES["AWS SES"] ``` ## 快速开始 1. 将 `.env.example` 复制到 `.env`，并至少设置 `AI_ENGINE_MOCK_MODE=true` 以便进行本地开发。 2. 运行 `docker compose up --build`。 3. 打开 `http://localhost:8000/health`。 4. 使用下方的模拟命令发送一个本地警报。 5. 从 `http://localhost:8000/incidents/` 获取事件。 ## 前置条件 - 用于本地开发的 Python 3.12 - Docker 和 Docker Compose - 用于非 Docker 本地运行的 PostgreSQL 16 - 用于实际分析和 embeddings 的 OpenAI API key - 用于通知的 Slack Incoming Webhook 和 AWS SES 配置 ## 本地开发 ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -e ".[test]" copy .env.example .env alembic upgrade head uvicorn app.main:app --reload ``` 要在不进行外部 AI 调用的情况下进行本地工作，请设置： ``` AI_ENGINE_MOCK_MODE=true SIMULATION_MODE=true ``` ## 环境变量 | 变量 | 必需 | 默认值 | 描述 | |---|---:|---|---| | `DATABASE_URL` | 是 | `postgresql+asyncpg://postgres:postgres@localhost:5432/incidentpilot` | 异步 SQLAlchemy 数据库 URL。 | | `OPENAI_API_KEY` | 在 mock 模式下为否 | 空 | 用于分析和 embeddings 的 OpenAI key。 | | `SLACK_WEBHOOK_URL` | 否 | 空 | Slack Incoming Webhook URL。 | | `SES_SENDER_EMAIL` | 否 | 空 | 已验证的 SES 发件人地址。 | | `SES_RECIPIENT_EMAILS` | 否 | 空 | 以逗号分隔的收件人列表。 | | `SES_REGION` | 否 | `us-east-1` | AWS SES 区域。 | | `FAISS_INDEX_PATH` | 否 | `./faiss_index` | 持久化的 FAISS 索引目录。 | | `RUNBOOK_DIR` | 否 | `./runbooks` | 包含 `.md` 和 `.txt` runbook 的目录。 | | `AI_ENGINE_MOCK_MODE` | 否 | `false` | 返回确定性的模拟分析。 | | `SIMULATION_MODE` | 否 | `false` | 启用 `POST /simulate/alarm`。 | | `DEBUG` | 否 | `false` | 在 HTTP 500 响应中包含 tracebacks。 | | `APP_VERSION` | 否 | `1.0.0` | 由 `/health` 报告的版本。 | | `APP_BASE_URL` | 否 | `http://localhost:8000` | 通知链接中使用的基 URL。 | ## API 参考 | 方法 | 路径 | 用途 | |---|---|---| | `GET` | `/health` | 服务和数据库健康状态。 | | `POST` | `/incidents/` | 创建事件。 | | `GET` | `/incidents/` | 列出事件，支持分页和可选过滤。 | | `GET` | `/incidents/{id}` | 检索单个事件。 | | `PATCH` | `/incidents/{id}` | 更新事件状态/分析/报告字段。 | | `DELETE` | `/incidents/{id}` | 删除事件。 | | `GET` | `/incidents/{id}/report` | 返回已存储的 Markdown 报告。 | | `GET` | `/incidents/{id}/report/html` | 将已存储的报告渲染为 HTML。 | | `POST` | `/webhooks/sns` | AWS SNS webhook endpoint。 | | `POST` | `/simulate/alarm` | 启用时的本地警报模拟。 | | `POST` | `/admin/reindex` | 重建 FAISS runbook 索引。 | ## SNS 模拟 启用 `SIMULATION_MODE=true`，然后运行： ``` curl -X POST http://localhost:8000/simulate/alarm \ -H "Content-Type: application/json" \ -d '{ "AlarmName": "CriticalHighCPU", "AlarmDescription": "critical api alarm", "NewStateValue": "ALARM", "NewStateReason": "CPUUtilization crossed 80%", "StateChangeTime": "2026-01-01T00:00:00Z", "Trigger": { "Namespace": "AWS/ECS", "Dimensions": [{"Name": "ServiceName", "Value": "api"}] } }' ``` ## 测试 ``` pytest --cov=app --cov-report=term-missing --cov-fail-under=80 ruff check . black --check . ``` 测试套件使用 SQLite fixtures 进行单元/属性测试，并 mock 外部服务。CI 配置为在 Python 3.12 上运行。 ## 部署 使用 Docker Compose 在本地构建并运行： ``` docker compose up --build ``` 对于 AWS 部署，请使用 `terraform/` 下的 Terraform 配置： ``` cd terraform cp terraform.tfvars.example terraform.tfvars terraform init terraform plan terraform apply ``` Terraform 模块定义了 EC2、IAM、安全组、SNS 订阅以及一个示例 CloudWatch CPU 警报。请通过环境变量或您的部署密钥管理器提供生产环境密钥，而不要将其提交到 Terraform 文件中。

标签：AI辅助, AV绕过, FastAPI, RAG, 告警管理, 根因分析, 测试用例, 版权保护, 请求拦截, 运维