Alex-Massaci/autonomous-incident-response-agent

# 自治 DevOps 事件响应 Agent [](https://github.com/OluwaTossin/autonomous-incident-response-agent/actions/workflows/ci.yml) 面向生产系统运维人员的 **AI 辅助事件分类**：基于 runbook、事件和日志的 **RAG**；带有防护机制的 **LangGraph** pipeline；来自 **FastAPI** 的 **结构化 JSON**；**Next.js** 分流控制台；可选的 **Gradio** 和 **n8n**；当你需要部署到笔记本以外的环境时，提供基于 **AWS** (ECS, ALB, ECR) 的 **Terraform** 支持。 **维护者：** Oluwatosin Jegede ## 目录 - [本产品的功能](#what-this-product-does) - [目标用户](#who-it-is-for) - [快速开始](#quick-start) - [自带数据](#bring-your-own-data) - [系统架构](#architecture) - [功能特性](#features) - [前置条件](#prerequisites) - [文档](#documentation) - [项目状态与分支](#project-status--branches) - [已交付里程碑（摘要）](#shipped-milestones-summary) - [仓库结构](#repository-layout) - [开发](#development) - [测试](#testing) - [Docker Compose (产品栈)](#docker-compose-product-stack) - [贡献指南](#contributing) - [免责声明](#disclaimer) ## 本产品的功能 你发送 **告警格式的 JSON**。该服务会**检索**相关的运维文档（runbook、历史事件、日志），利用 LLM 进行**推理**，并返回**结构化分流结果**：摘要、严重程度、假设、建议操作、升级信号以及可供审计的**证据**。可选的 hook 可以通过 **n8n** 将结果推送到 **Slack** 风格的工作流或工单系统中。 **目前已交付：** 从本地开发到 **AWS ECS**、**CloudWatch** 和 **GitHub Actions** 的端到端路径（里程碑 **1–14**）。各阶段的证据和检查清单：**[`docs/build-journey/execution-v1.md`](docs/build-journey/execution-v1.md)**。 更深层的产品规划：[`docs/decisions/capabilities-and-roadmap.md`](docs/decisions/capabilities-and-roadmap.md)。 ## 目标用户 - **SRE / DevOps / 平台工程师** —— 需要脚踏实地的初步分流，而不是通用的聊天机器人 - **团队** —— 已经将 runbook 和事件复盘作为文件（Markdown、日志）存储的团队 - **构建者** —— 需要一个将 RAG + Agent + IaC + CI/CD 整合在一个仓库中的参考架构的人 ## 快速开始 **分步安装（Compose、`.env`、首次索引）：** [`docs/installation.md`](docs/installation.md) · **产品文档索引：** [`docs/README.md`](docs/README.md) ``` uv sync --extra dev # add --extra ui for Gradio at /ui cp .env.example .env # set OPENAI_API_KEY uv run product-build-index --workspace default # or `uv run rag-build` — index under workspaces//index/ unless RAG_INDEX_DIR is set uv run serve-api # http://127.0.0.1:8000/docs ``` | 命令 | 用途 | |---------|---------| | `uv run rag-build` / `rag-query` | 索引构建 + 临时检索 | | `uv run product-validate-workspace` / `uv run product-build-index` | 工作区布局检查 + 作用域内的索引构建（参见 [`docs/bring-your-own-data.md`](docs/bring-your-own-data.md)） | | `uv run triage -f …` | 一次性分流 CLI | | `uv run serve-api` | FastAPI + OpenAPI | | `uv run triage-eval` | 黄金标准 JSONL → 测试报告（约 27 个测试用例；真实 LLM） | **完整技术栈（API + Next.js）：** 在运行 `./scripts/product/rebuild-index.sh` 后，执行 `./scripts/product/start.sh` —— API 端口 **:18080**，UI 端口 **:3000**。可选的 n8n：添加 `--profile automation`。参见 [Docker Compose (产品栈)](#docker-compose-product-stack)。 **Next.js 控制台：** [`frontend/README.md`](frontend/README.md) —— 本地开发默认通过 `http://localhost:3000` 连接你的 API（按照文档设置 `NEXT_PUBLIC_API_BASE_URL`）。 ## 自带数据 目前的运维知识存放在 **`data/`** 目录下： | 路径 | 作用 | |------|------| | [`sample_data/default_demo/`](sample_data/default_demo/) | 内置的合成语料库（runbook、事件、日志、知识库），在 **`AIRA_DATA_MODE=demo`** 且工作区 `data/` 为空时使用 | | [`workspaces//data/`](workspaces/README.md) | 你的运维文件（保持相同的子文件夹结构）；当该目录有内容或处于 **`AIRA_DATA_MODE=user`** 模式时作为主要数据源 | | [`data/eval/`](data/eval/) | 黄金标准 JSONL 和评估报告（`uv run triage-eval`） | 在 **`workspaces/.../data/`** 下添加或更改语料库文件后（或在 demo 模式下依赖 **`sample_data/default_demo/`**），请运行 **`uv run rag-build`** 或 **`./scripts/product/rebuild-index.sh`**，以便刷新 **`workspaces//index/`** 下被 gitignore 的 FAISS 包（除非 **`RAG_INDEX_DIR`** 指向了其他位置）。参见 **[`docs/bring-your-own-data.md`](docs/bring-your-own-data.md)** · [`workspaces/README.md`](workspaces/README.md) · [`data/README.md`](data/README.md) · [`sample_data/README.md`](sample_data/README.md)。 ## 系统架构  分层架构图、序列图和 CI/CD 详情（Mermaid）：**[`docs/architecture/system-architecture.md`](docs/architecture/system-architecture.md)** · 索引 [`docs/architecture/README.md`](docs/architecture/README.md) ## 功能特性 - **RAG** — 基于工作区或内置 `sample_data/default_demo/` 语料库构建的 FAISS 索引（`uv run rag-build`；`AIRA_DATA_MODE`） - **Agent** — LangGraph pipeline：标准化 → 检索 → 分析 → 丰富 → 决策 → 格式化 - **API** — FastAPI：`POST /triage`、`POST /ingest-incident`，OpenAPI 文档位于 `/docs`，可选的 `API_KEY` + 速率限制 - **审计与反馈** — JSONL 审计日志；用于关联的 `triage_id`；n8n + Gradio 反馈路径 - **用户界面** — Gradio 位于 `/ui`；[`frontend/`](frontend/) 中的 Next.js 分流控制台（部署时为静态导出 → S3） - **自动化** — n8n 工作流（Slack，模拟 Jira） — [`workflows/n8n/`](workflows/n8n/) - **评估** — 黄金标准数据集 + `uv run triage-eval` — [`data/eval/`](data/eval/) - **AWS** — Terraform **开发/生产**环境，ECS Fargate，ALB，ECR，SSM secrets，可选的静态 UI CDN - **可观测性** — CloudWatch 仪表盘，分流日志指标，告警 — [`docs/deploy/observability.md`](docs/deploy/observability.md) - **CI/CD** — GitHub Actions（lint，测试，Terraform 校验，前端 + Docker 构建） — [`docs/deploy/ci.md`](docs/deploy/ci.md) ## 前置条件 | 需求 | 说明 | |-------------|--------| | **Python** | 3.11+（参见 [`pyproject.toml`](pyproject.toml)） | | **uv** | [安装 uv](https://docs.astral.sh/uv/) — 包管理器和虚拟环境 | | **OpenAI (或兼容的模型)** | `.env` 中的 `OPENAI_API_KEY`，用于 embeddings + 聊天 | | **Docker** | 可选；用于 Compose (API + n8n) 和本地 n8n | | **AWS CLI / Terraform** | 用于部署路径 — 参见部署文档 | 复制 [`.env.example`](.env.example) → **`.env`**。应用只会加载 **`.env`** 文件（切勿提交密钥信息）。 ## 文档 | 主题 | 链接 | |-------|------| | **产品文档索引**（安装、配置、数据、重建索引、故障排除） | [`docs/README.md`](docs/README.md) | | **安装说明**（前置条件、`.env`、Compose） | [`docs/installation.md`](docs/installation.md) | | **配置**（优先级、密钥、工作区） | [`docs/configuration.md`](docs/configuration.md) | | **自带数据**（工作区布局、管理 API） | [`docs/bring-your-own-data.md`](docs/bring-your-own-data.md) | | **重建索引**（CLI + `/admin/reindex`） | [`docs/reindexing.md`](docs/reindexing.md) | | **安全性**（密钥、TLS、Compose 与 ECS 对比、非目标） | [`docs/security.md`](docs/security.md) | | **故障排除** | [`docs/troubleshooting.md`](docs/troubleshooting.md) | | 架构（Mermaid 图表、PNG 导出） | [`docs/architecture/system-architecture.md`](docs/architecture/system-architecture.md) | | **第一版构建日志**（阶段 1–14、里程碑、收尾） | [`docs/build-journey/execution-v1.md`](docs/build-journey/execution-v1.md) | | 构建历程索引 | [`docs/build-journey/README.md`](docs/build-journey/README.md) | | 分支（`dev` / `main`）、GitHub Secrets | [`docs/contributing.md`](docs/contributing.md) | | 将 API 部署到 ECS / ECR / SSM | [`docs/deploy/aws-ecs.md`](docs/deploy/aws-ecs.md) | | CloudWatch 仪表盘和分流指标 | [`docs/deploy/observability.md`](docs/deploy/observability.md) | | GitHub Actions CI 和可选部署 | [`docs/deploy/ci.md`](docs/deploy/ci.md) | | Terraform 结构与远程状态 | [`infra/terraform/README.md`](infra/terraform/README.md) | | n8n 工作流与 webhooks | [`workflows/n8n/README.md`](workflows/n8n/README.md) | | Next.js 分流 UI | [`frontend/README.md`](frontend/README.md) | | 云部署前验证 | [`docs/validation/pre-cloud-validation.md`](docs/validation/pre-cloud-validation.md) | | 问题定义 / ADRs | [`docs/decisions/`](docs/decisions/) | | 数据语料库结构 | [`data/README.md`](data/README.md) | ## 项目状态与分支 - **已交付：** 里程碑 **1–14**（参见 [已交付里程碑（摘要）](#shipped-milestones-summary) 和 [`docs/build-journey/execution-v1.md`](docs/build-journey/execution-v1.md)）。 - **第二版（在 `dev` 分支上）：** **V2.10** 产品文档 — [`docs/README.md`](docs/README.md)（安装、配置、自带数据、重建索引、安全性、故障排除）。**下一步：** V2.11 外部验证（测试 A–C）。 - **工作流：** 在 **`dev`** 上开发，通过 **PR → `main`** 进行提交 — [`docs/contributing.md`](docs/contributing.md)。 - **待办事项：** TLS、第 15 阶段想法、更深入的 n8n 指标 — 记录在 [`docs/build-journey/execution-v1.md`](docs/build-journey/execution-v1.md) 中，不属于当前的收尾范围。 ## 已交付里程碑（摘要） | 阶段 | 状态 | 主要产物 | |-------|--------|-------------------| | **1** — 问题定义 | 已完成 | [`docs/decisions/problem-definition.md`](docs/decisions/problem-definition.md) | | **2** — 知识与样本数据 | 已完成 | [`sample_data/default_demo/`](sample_data/default_demo/)（内置语料库）；[`data/eval/`](data/eval/) | | **3** — 本地 RAG | 已完成 | [`app/rag/`](app/rag/) · `.rag_index/`（已被 gitignore） | | **4** — LangGraph Agent | 已完成 | [`app/agent/`](app/agent/), [`app/models/`](app/models/)| **5** — HTTP API | 已完成 | [`app/api/`](app/api/) | | **6** — n8n | 已完成 | [`workflows/n8n/`](workflows/n8n/), [`docker-compose.n8n.yml`](docker-compose.n8n.yml) | | **7** — Gradio UI | 已完成 | [`app/ui/`](app/ui/) · `/ui` | | **8** — 评估 | 已完成 | [`app/eval/`](app/eval/), [`data/eval/gold.jsonl`](data/eval/gold.jsonl) | | **9** — Docker Compose | 已完成 | [`Dockerfile`](Dockerfile), [`docker-compose.yml`](docker-compose.yml) | | **10** — Terraform | 已完成 | [`infra/terraform/`](infra/terraform/) | | **11** — ECS / ECR | 已完成 | [`docs/deploy/aws-ecs.md`](docs/deploy/aws-ecs.md), [`scripts/aws/push_api_to_ecr.sh`](scripts/aws/push_api_to_ecr.sh) | | **12** — Next.js UI | 已完成 | [`frontend/`](frontend/), [`scripts/aws/deploy_frontend_cdn.sh`](scripts/aws/deploy_frontend_cdn.sh) | | **13** — 可观测性 | 已完成 | [`docs/deploy/observability.md`](docs/deploy/observability.md), [`infra/terraform/modules/monitoring/`](infra/terraform/modules/monitoring/) | | **14** — CI/CD | 已完成 | [`.github/workflows/ci.yml`](.github/workflows/ci.yml), [`docs/deploy/ci.md`](docs/deploy/ci.md) | **第二版（产品化，`dev` 分支）：** **V2.10** 文档 —— **已完成**（精心整理了 [`docs/README.md`](docs/README.md)、安装、配置、重建索引、故障排除；BYO + `config.example.yaml` 已对齐）。**V2.9** 安全基线已于早些时候交付。**正朝着 V2 收尾迈进：** **V2.11** 验证测试 A–C。 **各阶段详情**（端点、环境变量、n8n 行为、AWS 步骤）：**[`docs/build-journey/execution-v1.md`](docs/build-journey/execution-v1.md)** — 完整的规范存放在该文件中，以保持本文件的简洁易读。 ## 仓库结构 | 路径 | 用途 | |------|---------| | [`docs/build-journey/execution-v1.md`](docs/build-journey/execution-v1.md) | 版本 1 的分阶段构建日志、里程碑、证据 | | [`docs/README.md`](docs/README.md) | 产品文档索引（V2.10） | | [`docs/security.md`](docs/security.md) | API 密钥、`/admin/*`、上传限制、威胁说明 | | [`sample_data/README.md`](sample_data/README.md) | 内置演示语料库（`AIRA_DATA_MODE`） | | [`docs/contributing.md`](docs/contributing.md) | 分支策略与 GitHub Actions secrets | | [`docs/decisions/`](docs/decisions/) | ADRs、问题定义、路线图 | | [`docs/architecture/`](docs/architecture/) | [`system-architecture.md`](docs/architecture/system-architecture.md)、图表；仓库根目录的概览 PNG [`architectural-diagram.png`](architectural-diagram.png) | | [`app/`](app/) | `rag`、`agent`、`api`、`models`、`ui`、`eval` | | [`data/`](data/) | 评估黄金数据集、运行时 JSONL 日志；内置语料库 → [`sample_data/default_demo/`](sample_data/default_demo/) | | [`frontend/`](frontend/) | Next.js 分流控制台 | | [`workflows/n8n/`](workflows/n8n/) | 可导入的 n8n JSON + README | | [`infra/terraform/`](infra/terraform/) | 模块、`envs/dev`、`envs/prod`、引导脚本 | | [`scripts/`](scripts/) | E2E 检查、基准测试、AWS 辅助脚本、[`scripts/product/`](scripts/product/)（Compose + 索引） | | [`examples/sample_incident_payload.json`](examples/sample_incident_payload.json) | 用于 CLI / API 的样本 payload | ## 开发 使用基于 [`pyproject.toml`](pyproject.toml) 和 [`uv.lock`](uv.lock) 的 **[uv](https://docs.astral.sh/uv/)**。 ``` curl -LsSf https://astral.sh/uv/install.sh | sh # or: brew install uv cd autonomous-incident-response-agent uv sync --extra dev ``` **分流 CLI**（需要 `.env`、索引、聊天模型）： ``` uv run triage -f examples/sample_incident_payload.json ``` **API**（相同的环境）： ``` uv run serve-api curl -s http://127.0.0.1:8000/health curl -s -X POST http://127.0.0.1:8000/triage -H "Content-Type: application/json" \ -d @examples/sample_incident_payload.json ``` 如果在服务器上设置了 **`API_KEY`**，请添加请求头 `x-api-key: `。OpenAPI 文档：`/docs`。 **Gradio：** `uv sync --extra ui`，然后运行 `uv run serve-api` → `http://127.0.0.1:8000/ui`（Compose 的默认 API 端口是 **18080**）。 **评估：** `uv run triage-eval` — 可选参数 `--limit N`、`--out path/to/report.md`。 **锁文件：** 在编辑依赖项后，运行 `uv lock`。[`requirements.txt`](requirements.txt) 是可选的；推荐使用 **`uv sync`**。 如果 `POST /triage` 返回 404，请确认没有其他程序占用了该端口：`curl -s http://127.0.0.1:8000/` 应该会显示该服务的发现 JSON。 ## 测试 ``` uv sync --extra dev uv run pytest ``` 测试结构：`tests/unit/`、`tests/integration/`（集成测试在适当的地方模拟了 LLM）。**安全基线 (V2.9)：** `tests/integration/test_security_baseline_v29.py`、`tests/unit/test_rate_limit_providers.py`，以及已有的 `test_admin_routes.py`。 ## Docker Compose (产品栈) **默认技术栈**（API + Next.js 静态运维 UI）：除非你使用 Compose 的 **`automation`** 配置文件选择启用，否则 **n8n 不会启动**。 ``` uv run product-build-index --workspace default # or: ./scripts/product/rebuild-index.sh ./scripts/product/start.sh # same as: docker compose up -d --build ``` - **API (OpenAPI / Gradio)：** `http://127.0.0.1:18080/docs` 和 `http://127.0.0.1:18080/ui`（使用 `COMPOSE_API_PORT` 可覆盖主机端口）。 - **Next.js（通过 nginx 实现静态导出）：** `http://127.0.0.1:3000/`（使用 `COMPOSE_UI_PORT` 进行更改）。UI 在构建时通过 `NEXT_PUBLIC_API_BASE_URL` 指向该 API 端口，以便**浏览器**能从你的机器上访问 API。 - **n8n（可选）：** `docker compose --profile automation up -d --build` — 然后访问 `http://127.0.0.1:5678/`。与传递 `--profile automation` 时的 [`./scripts/product/start.sh`](scripts/product/start.sh) 使用的配置文件相同。 **数据卷：** `./workspaces`（根据 `WORKSPACE_ID` 存放语料库和索引）和 `./data`（旧版语料库和日志）被绑定挂载到 API 容器中。**安全性：** API 在容器**内部**监听 `0.0.0.0` 以便端口发布生效；请仅在你信任的网络接口上发布 `COMPOSE_API_PORT` / `COMPOSE_UI_PORT`。在没有 TLS 和反向代理的情况下，请勿将受 **`ADMIN_API_KEY`** 保护的（已实现的）路由暴露在公共互联网上 — 参见 [`docs/bring-your-own-data.md`](docs/bring-your-own-data.md) 中的产品说明。 **辅助脚本：** [`scripts/product/start.sh`](scripts/product/start.sh)、[`rebuild-index.sh`](scripts/product/rebuild-index.sh)、[`reset.sh`](scripts/product/reset.sh)（仅清除索引；需要输入 `DELETE`）、[`verify-frontend-bundle.sh`](scripts/product/verify-frontend-bundle.sh)（静态 `out/` 目录不能包含被禁止的密钥标记）。 **E2E 冒烟测试：** [`scripts/e2e_stack_check.sh`](scripts/e2e_stack_check.sh) — 如果不使用 n8n，请设置 `SKIP_N8N=1`（除非使用 `--profile automation`，否则 n8n 是关闭的）。 **仅 n8n**（API 运行在宿主机上）：`docker compose -f docker-compose.n8n.yml up -d` — 完整指南：[`workflows/n8n/README.md`](workflows/n8n/README.md)。 **AWS 镜像：** 根目录的 `Dockerfile` 总是会生成一个 stub `.rag_index/`，以便在没有本地索引的情况下 `docker build` 也能正常工作；**`scripts/aws/push_api_to_ecr.sh`** 在为 ECS 构建之前，会通过 **`docker/bake_index_context/`** 覆盖宿主机构建的索引。当未设置 `RAG_INDEX_DIR` 时，本地 Compose 优先使用 **`workspaces//index/`** — 如果该目录为空，请在运行 `docker compose` 前执行 [`scripts/product/rebuild-index.sh`](scripts/product/rebuild-index.sh)。部署流程：[`scripts/aws/push_api_to_ecr.sh`](scripts/aws/push_api_to_ecr.sh) 和 [`docs/deploy/aws-ecs.md`](docs/deploy/aws-ecs.md)。 ## 贡献指南 请基于 **`dev`** 分支开发，向 **`main`** 分支发起 Pull Requests。CI 要求和可选的 Secrets：[`docs/contributing.md`](docs/contributing.md)。 ## 免责声明 本仓库中的 runbook、事件和日志均为**合成的**训练和评估材料。它们不是真实的生产数据。

标签：AIOps, AI助手, ALB, AV绕过, AWS, CISA项目, CloudWatch, DLL 劫持, Docker, Docker Compose, DPI, ECR, ECS, ECS, FastAPI, GitHub Actions, Gradio, IT运维, JSON, LangGraph, LLM, n8n, RAG, Slack, Socks5代理, Terraform, Terraform, Unmanaged PE, 事件管理, 事故响应, 告警分类, 大语言模型, 安全生产, 安全防御评估, 故障诊断, 智能代理, 智能运维, 检索增强生成, 网络调试, 自动化, 自动笔记, 自动驾驶, 请求拦截, 运维平台, 运行手册, 逆向工具