Khaledayman9/ops-pilot

# ⚡ Ops-Pilot — 基于 AI 的 SRE 事件响应平台              Ops-Pilot 是一个生产级的多智能体 AI 系统，专为 SRE 事件响应设计。中央编排器协调十二个专业的 AI 智能体，用于对事件进行分类、遍历服务依赖知识图谱、扫描代码仓库和 Terraform 状态、分析遥测数据、确定根本原因，并生成可操作的修复方案——所有结果均通过 Server-Sent Events 实时流式传输给操作员。 ## 目录 - [布局](#layout) - [架构概述](#architecture-overview) - [技术栈](#tech-stack) - [智能体流水线](#agent-pipeline) - [快速开始](#quick-start) - [API 路由](#api-routes) - [身份验证](#authentication) - [安全护栏](#security-guardrails) - [流式传输 (SSE)](#streaming-sse) - [Neo4j 知识图谱](#neo4j-knowledge-graph) - [LLM 供应商切换](#llm-provider-switching) - [Alembic 数据迁移](#alembic-migrations) - [Celery 定期任务](#celery-periodic-tasks) - [MCP 集成](#mcp-integrations) - [Docker 目标](#docker-targets) - [环境变量](#environment-variables) - [测试](#testing) - [CI/CD](#cicd) ## 布局

主页

**深色模式（默认）：** **浅色模式：**

设置

聊天界面

**聊天窗口：** **查询：** **可解释性面板：** **取消操作：**

身份验证与个人资料

**登录：** **注册：** **个人资料：**

帮助与联系

**帮助：** **联系：**

## 架构概述 ``` ┌──────────────────────────────────────────────────────────────────────┐ │ Next.js 15 │ TypeScript │ Tailwind CSS │ Framer Motion │ │ / /chat /login /register /help /settings /contact │ └──────────────────────────┬───────────────────────────────────────────┘ │ SSE + REST (JWT Bearer) ┌──────────────────────────▼───────────────────────────────────────────┐ │ FastAPI /api/v1/{auth, incident, chat, stream, health} │ │ JWT access + refresh tokens │ bcrypt │ Guardrails (Presidio) │ └────────────────┬─────────────────────────────────────────────────────┘ │ ┌────────────────▼─────────────────────────────────────────────────────┐ │ IncidentOrchestrator (LangGraph async generator) │ │ │ │ 1. Classifier — severity, service, urgency, type │ │ 2. Entity Extractor — services, deployments, owners, metrics │ │ 3. Document Processor — PDF, DOCX, PPTX, CSV, Markdown │ │ 4. Repo Scanner — GitHub commits, PRs, CI checks │ │ 5. Terraform Scanner — IaC drift, plans, workspace state │ │ 6. Graph Analyzer — Neo4j blast-radius + dependency map │ │ 7. Web Intelligence — DuckDuckGo: CVEs, advisories, outages │ │ 8. Ops Analyst — latency, error rate, saturation │ │ 9. Crew Intelligence — CrewAI Researcher→Analyst→Writer │ │ 10. Root Cause Finder — causal chain + deployment correlation │ │ 11. Remediator — rollback, runbooks, escalation paths │ │ 12. Conversationalist — operator-ready Markdown narrative │ └────────┬──────────────────────┬───────────────────────┬─────────────┘ │ │ │ ┌────────▼──────┐ ┌────────────▼──────┐ ┌────────────▼────────────┐ │ Neo4j 5 │ │ PostgreSQL 16 │ │ Redis 7 │ │ Service graph│ │ Users / Chats / │ │ Celery broker │ │ knowledge │ │ Messages / │ │ + result backend │ │ base │ │ Executions │ │ + periodic tasks │ └───────────────┘ └───────────────────┘ └─────────────────────────┘ ``` ## 技术栈 | 层级 | 技术 | | ----------- | ------------------------------------------------------------------------ | | 前端 | Next.js 15, TypeScript, Tailwind CSS, Framer Motion, anime.js, Jest | | 后端 | Python 3.11, FastAPI, LangGraph, CrewAI, LangChain | | LLM | OpenAI（默认） · Anthropic · Google — 运行时可切换，无需重构 | | 图数据库 | Neo4j 5 — 服务依赖知识图谱 + 爆炸半径遍历 | | 关系型数据库 | PostgreSQL 16 + SQLAlchemy 2 (async) + Alembic 迁移 | | 队列 | Redis 7 + Celery（定期图谱维护任务） | | 身份验证 | JWT（access token + refresh token），bcrypt 密码哈希，python-jose | | 安全护栏 | Prompt 注入检测，PII 清洗（Presidio + regex 回退） | | MCP | GitHub MCP server, Terraform MCP server, 自定义 Ops Inspector server | | IaC | Docker Compose — 开发与生产环境 overlay | | CI/CD | GitHub Actions — pytest，类型检查，lint，迁移检查，MLflow 评估 | | 流式传输 | 通过 sse-starlette 实现的 Server-Sent Events (SSE) | ## 智能体流水线 每个事件查询都会通过编排器的异步生成器进行处理，该生成器会生成 `StreamEvent` 对象，并通过 SSE 直接转发到前端。操作员可以在运行时独立启用/禁用每个智能体。 ### 1. 分类器 (Classifier) 使用结构化的 LLM 输出（Pydantic 模型）从原始查询中提取服务名称、严重程度（P0–P3）、事件类型、受影响的组件、触发事件以及置信度得分。 ### 2. 实体提取器 (Entity Extractor) 从查询中解析出结构化实体：服务名称、部署、指标、错误代码、时间范围，以及用于下游图数据库和 Web 查询的 Cypher 格式搜索关键字。 ### 3. 文档处理器 (Document Processor)（可选） 将上传的附件（PDF, DOCX, PPTX, XLS/XLSX, HTML, Markdown, CSV, TXT）转换为 Markdown 并将其注入到流水线上下文中。所有下游智能体都会接收到完整的文档上下文。 ### 4. 仓库扫描器 (Repo Scanner)（可选） 使用 GitHub MCP server 获取服务仓库最近的提交、打开的 pull request、失败的 CI 检查以及分支活动。需要配置 `GITHUB_TOKEN`。 ### 5. Terraform 扫描器 (Terraform Scanner)（可选） 使用 Terraform MCP server 检查工作区状态，检测基础设施漂移，并总结可能与事件相关的最近 plan/apply 运行记录。需要配置 Terraform MCP。 ### 6. 图谱分析器 (Graph Analyzer) 针对 Neo4j 知识图谱执行九个 Cypher 查询：直接依赖项、上游调用者、完整爆炸半径（3 跳传递闭包）、最近部署、历史事件、关联的 runbook、团队所有权、配置变更事件以及跨实体事件。 ### 7. 网络情报 (Web Intelligence)（可选） 运行 DuckDuckGo 搜索（Instant Answer API → HTML 抓取回退），以查找已知的供应商问题、CVE、事后分析报告和依赖项公告。搜索结果按 URL 进行去重。 ### 8. 运维分析师 (Ops Analyst)（可选） 使用自定义的 Ops Inspector MCP server 解析堆栈跟踪、计算错误率、格式化事件摘要，并根据可观测性工具的输出检查服务健康状况。 ### 9. 团队情报 (Crew Intelligence)（可选） 运行一个包含三个角色的 CrewAI 团队 —— Researcher → Analyst → Writer —— 负责收集、关联外部情报并将其综合成一份结构化的情报报告，然后注入到分析上下文中。 ### 10. 根本原因查找器 (Root Cause Finder) 使用 LLM 综合所有流水线上下文（图数据库、网络、遥测、代码仓库、IaC），以确定主要根本原因，建立带有置信度得分的因果链，检测部署相关性，并重建事件时间线。 ### 11. 修复器 (Remediator) 生成完整的修复方案：即时的 kubectl/CLI 操作、回滚步骤、缓解措施、带有 Slack 联系人的升级路径、runbook 引用以及事件后的后续行动事项。 ### 12. 对话助手 (Conversationalist) 将所有结构化的流水线输出综合成人类可读的 Markdown 叙述，其中包含用于压缩聊天记录的对话摘要。 ## 快速开始 ### 前置条件 - Docker 和 Docker Compose - Node.js 20+ - Python 3.11+ 并安装 `uv`（安装命令：`pip install uv`） ### 1. 克隆并配置 ``` git clone https://github.com/your-org/ops-pilot.git cd ops-pilot cp backend/.env.example backend/.env ``` 编辑 `backend/.env` 并至少设置以下内容： - `OPENAI_API_KEY` — 你的 OpenAI key - `SECRET_KEY` — 生成命令：`openssl rand -hex 32` ### 2. 启动基础设施 ``` cd backend docker compose up -d postgres neo4j redis # 运行 migrations 前请允许约 20 秒让 Neo4j 完全初始化 ``` ### 3. 运行迁移并初始化知识图谱 ``` uv sync uv run alembic upgrade head uv run python -m app.db.neo4j_seed ``` ### 4. 启动 API server ``` uv run uvicorn app.main:app --reload --port 8000 # 验证：curl http://localhost:8000/health ``` ### 5. 启动 Celery（在两个独立的终端中） ``` uv run celery -A app.tasks.celery_app worker --loglevel=info uv run celery -A app.tasks.celery_app beat --loglevel=info ``` ### 6. 启动前端 ``` cd ../frontend npm install cp .env.example .env.local # 设置：NEXT_PUBLIC_API_URL=http://localhost:8000 npm run dev # 打开 http://localhost:3000 ``` ## API 路由 ``` GET /health Liveness + dependency check POST /api/v1/auth/register Register new user POST /api/v1/auth/login Login, receive JWT tokens POST /api/v1/auth/refresh Refresh access token GET /api/v1/auth/me Get current user profile POST /api/v1/incident/analyze Full analysis (Bearer required) GET /api/v1/stream/incident SSE stream (optional Bearer) POST /api/v1/chat/ Create chat session (Bearer) GET /api/v1/chat/ List chat sessions (Bearer) GET /api/v1/chat/{id} Get chat by ID GET /api/v1/chat/{id}/messages Get messages for chat GET /api/v1/chat/{id}/executions Get agent execution log DELETE /api/v1/chat/{id} Delete chat session GET /api/v1/settings Get LLM settings (Bearer) PUT /api/v1/settings Update LLM settings (Bearer) ``` ## 身份验证 Ops-Pilot 采用双 token JWT 策略： - **Access token** — 生命周期短（默认 30 分钟），使用 HS256 和 `SECRET_KEY` 进行签名。作为 `Authorization: Bearer ` 发送。 - **Refresh token** — 生命周期长（默认 7 天）。用于通过 `POST /api/v1/auth/refresh` 获取新的 access token。 - 密码在存入 PostgreSQL 之前使用 **bcrypt** 进行哈希处理。 - `/api/v1/stream/incident` 端点接受可选的 Bearer token。未经身份验证的用户仍可以流式传输结果，但其会话不会持久化保存到用户账户中。 - 如果 token 缺失或无效，`get_current_user` 依赖项会引发 401 错误。`get_optional_user` 对于未经身份验证的请求将返回 `None`，而不会引发异常。 ## 安全护栏 每个用户查询（及文档上下文）在到达任何 LLM 或智能体之前，都会通过 `app/core/guardrails.py` 进行处理： 1. **控制字符清理** — 剔除空字节和不可打印字符。 2. **长度限制** — 输入上限为 4,000 个字符（`MAX_QUERY_LENGTH`）。 3. **Prompt 注入检测** — 使用正则表达式对已知的攻击短语进行模式匹配，如 "ignore all previous instructions", "forget everything", "you are now", "pretend to be" 和 "act as"。 4. **PII 清洗** — 使用 Microsoft Presidio（如果已安装）对电子邮件、电话号码、信用卡号、IP 地址和姓名进行脱敏。当 Presidio 不可用时，回退到 regex 模式进行匹配。 违反护栏会导致产生一个携带 `GUARDRAIL_VIOLATION` 代码的 SSE `error_event`，并立即终止流。违规内容永远不会被转发给任何 LLM。 ## 流式传输 (SSE) `/api/v1/stream/incident` 端点会打开一个 Server-Sent Events 连接，并在编排器处理流水线时实时发射 `StreamEvent` 对象。 ### 事件类型 | 事件类型 | 描述 | | ----------- | ----------------------------------------------------------------- | | `session` | 首先发射 — 包含本次分析轮次的 `session_id` | | `step` | 智能体生命周期更新（开始、完成、错误、跳过） | | `graph` | 图谱分析器结果 — 爆炸半径、依赖关系、runbook | | `reasoning` | 根本原因查找器结果 — 因果链、时间线、置信度 | | `result` | 最终合并 — 自然语言响应、结构化数据、引文 | | `error` | 流级别错误（违反护栏、意外异常） | | `done` | 流已关闭 — 回显 session_id 以供确认 | ### StreamEvent schema 每个事件的 `data` 字段都是一个 JSON 对象，该对象始终包含： - `description` — 关于该步骤执行操作的人类可读说明 - `input` — 此步骤接收的数据 - `output` — 生成的结果（在 complete 事件中） - `completed_steps` — 目前已完成的所有流水线步骤列表 - `error` — 错误信息（仅在 error 事件中） ### 前端调用 前端调用 `app/lib/apis.ts` 中的 `streamIncident()`，该函数会打开一个 `EventSource` 并将每个解析后的事件分发给 `recordExplainabilityEvent()`。聊天界面中的可解释性面板将每个事件呈现为可点击的卡片，显示步骤名称、状态以及输入/输出的悬停预览。点击会打开一个包含完整详细信息的模态框。 ## Neo4j 知识图谱 该图模拟了基础设施的实时服务依赖拓扑。`GraphAnalyzerAgent` 在每个事件轮次运行九个 Cypher 查询： 1. **直接依赖项** — 受影响服务直接调用的服务 2. **上游调用者** — 调用受影响服务的服务 3. **爆炸半径** — 所有可能受影响节点的 3 跳传递闭包 4. **部署** — 爆炸半径服务中最近的部署情况 5. **历史事件** — 相关服务上发生过的过去事件 6. **Runbook** — 关联的带有 URL 的 runbook 文档 7. **所有权** — 包含 Slack 频道的团队所有权记录 8. **配置变更** — 最近的配置变更事件 9. **跨实体事件** — 涉及任何提取出的实体的事件 ### 初始化知识图谱 ``` uv run python -m app.db.neo4j_seed ``` 这会创建 Service, Deployment, Incident, Runbook, Team 和 ConfigChange 节点，并为示例电商微服务拓扑（checkout, payment, inventory, api-gateway, redis, postgres 等）建立真实的关系。 ### Celery 图谱维护 `sync_web_intelligence_to_graph` Celery 任务（每小时运行一次）将网络搜索发现的结果作为 `WebKnowledge` 节点写回到 Neo4j 中，使得该图谱能够随着时间推移不断积累外部情报。 ## LLM 供应商切换 编辑 `backend/.env` — 无需重构： ``` # OpenAI（默认） LLM_PROVIDER=openai LLM_MODEL=gpt-4o OPENAI_API_KEY=sk-... # Anthropic Claude LLM_PROVIDER=anthropic LLM_MODEL=claude-3-5-sonnet-20241022 ANTHROPIC_API_KEY=sk-ant-... # Google Gemini LLM_PROVIDER=google LLM_MODEL=gemini-1.5-pro GOOGLE_API_KEY=AIza... ``` LLM 供应商在启动时通过 `app/core/llm.py` 解析。所有智能体均使用 `llm.with_structured_output(PydanticModel)` 来实现类型安全的结构化输出。 ## Alembic 数据迁移 ``` uv run alembic upgrade head apply all pending migrations uv run alembic revision --autogenerate -m "describe change" generate a new revision uv run alembic downgrade -1 roll back one step uv run alembic downgrade roll back to a specific hash uv run alembic current show current applied revision uv run alembic check assert no unapplied migrations uv run alembic history show full migration history ``` 迁移文件位于 `backend/alembic/versions/` 中。`alembic.ini` 指向了从 `backend/settings.py` 中提取的异步 PostgreSQL DSN。 ## Celery 定期任务 | 任务 | 计划 | 目的 | | -------------------------------- | ----------- | -------------------------------------------------- | | `refresh_service_health` | 每 15 分钟 | 从外部检查更新 Neo4j 服务状态 | | `sync_web_intelligence_to_graph` | 每小时 | 将 CVE / 公告发现写入 Neo4j 节点 | | `prune_stale_incidents` | 每天 02:00 | 删除超过 90 天的已解决事件 | 启动命令： ``` uv run celery -A app.tasks.celery_app worker --loglevel=info uv run celery -A app.tasks.celery_app beat --loglevel=info ``` ## MCP 集成 Ops-Pilot 通过 Model Context Protocol (MCP) 连接到外部工具。服务器配置位于 `backend/mcp_servers/servers.json`。 | 智能体 | MCP Server | 暴露的工具 | | ---------------- | ---------------------- | ------------------------------------------------------------------------------------ | | Repo Scanner | GitHub MCP (官方) | get_repository, list_commits, list_pull_requests, list_check_runs | | Terraform Scanner | Terraform MCP | workspace_list, plan_show, state_show, apply_status | | Ops Analyst | Ops Inspector (自定义) | parse_stack_trace, calculate_error_rate, format_incident_brief, check_service_health | 要启用 MCP 智能体，请在 `servers.json` 中设置所需的密钥，或通过由 `MCPClientManager` 替换的环境变量进行设置： ``` GITHUB_TOKEN=ghp_... enables Repo Scanner ``` ## Docker 目标 ``` Development (hot reload): cd backend && make dev Production: cd backend && make prod Run migrations via Docker: cd backend && make migrate cd backend && make migrate-version-up m= cd backend && make migrate-version-down m= Generate a new Alembic revision: cd backend && make revision m="add_users_table" Seed Neo4j: cd backend && make seed-neo4j Clean up Docker: cd backend && make prune ``` ## 环境变量 | 变量 | 必填 | 描述 | | ----------------------------- | -------- | --------------------------------------------------- | | `SECRET_KEY` | 是 | JWT 签名密钥 — `openssl rand -hex 32` | | `OPENAI_API_KEY` | 是\* | 当 `LLM_PROVIDER=openai` 时必填 | | `ANTHROPIC_API_KEY` | 是\* | 当 `LLM_PROVIDER=anthropic` 时必填 | | `GOOGLE_API_KEY` | 是\* | 当 `LLM_PROVIDER=google` 时必填 | | `LLM_PROVIDER` | 否 | `openai`（默认） / `anthropic` / `google` | | `LLM_MODEL` | 否 | 所选供应商的模型名称 | | `DATABASE_URL` | 否 | PostgreSQL 异步 DSN（默认指向 Docker 服务） | | `NEO4J_URI` | 否 | Neo4j bolt URI（默认为 `bolt://localhost:7687`） | | `NEO4J_USERNAME` | 否 | Neo4j 用户名（默认：`neo4j`） | | `NEO4J_PASSWORD` | 否 | Neo4j 密码（默认：`password`） | | `REDIS_URL` | 否 | Redis DSN（默认为 `redis://localhost:6379/0`） | | `GITHUB_TOKEN` | 否 | GitHub PAT — 启用 Repo Scanner 智能体 | | `ACCESS_TOKEN_EXPIRE_MINUTES` | 否 | JWT access token 生命周期（默认：30） | | `REFRESH_TOKEN_EXPIRE_DAYS` | 否 | JWT refresh token 生命周期（默认：7） | ## 测试 ``` Backend: cd backend uv run pytest tests/ -v uv run pytest tests/ -v --cov=app --cov-report=term-missing Frontend: cd frontend npm test npm run test:coverage ``` 测试覆盖率包括：API 端点、身份验证流程、所有十二个智能体（模拟 LLM 链）、安全护栏、编排器流事件以及实用工具函数。 ## CI/CD 位于 `.github/workflows/` 中的 GitHub Actions 工作流： | 工作流 | 触发器 | 步骤 | | ------------ | ------------- | ------------------------------------------------- | | `backend-ci` | Push / PR | 安装依赖，运行 pytest，检查 Alembic 挂起状态 | | `frontend-ci` | Push / PR | npm install, Jest, TypeScript 类型检查, ESLint | | `lint` | Push / PR | Ruff lint, black 格式检查 | | `infra` | 推送到 main | Docker 构建验证 | | `mlflow` | 推送到 main | 用于评估 LLM 输出质量的 MLflow 评估运行 | ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AIOps, AV绕过, FastAPI, LangGraph, SRE, 偏差过滤, 多智能体, 搜索引擎查询, 故障响应, 根因分析, 测试用例, 特征库, 请求拦截, 逆向工具