Mobicos/smartsre-copilot-py

# SmartSRE Copilot [](https://www.python.org/) [](https://fastapi.tiangolo.com/) [](https://www.langchain.com/langgraph) [](https://github.com/Mobicos/smartsre-copilot-py/actions/workflows/ci.yml) SmartSRE Copilot 是一个基于 FastAPI 的 SRE 助手，它结合了： - 基于运维文档的 RAG 知识检索 - 结合本地和基于 MCP 工具的 LLM 聊天 - 计划-执行-重规划（Plan-Execute-Replan）风格的 AIOps 诊断 - 用于聊天、流式回答、文件上传和诊断的轻量级 Web UI ## 中文速览 SmartSRE Copilot 是一个面向 SRE / On-call / AIOps 场景的智能助手，当前主要提供三类能力： - 知识库问答：基于本地运维文档做 RAG 检索增强 - 智能诊断：基于 Planner、Executor、Replanner 做多步排障 - 工具接入：通过 MCP 接入日志和监控查询能力 适合的使用场景： - 内部运维知识助手 - 故障演练或诊断流程演示 - AIOps Copilot 原型验证 ## 功能介绍 ### 1. 基于知识的聊天 - 使用自然语言提出运维问题 - 从 Markdown 或文本文档中检索相关内容 - 支持普通响应模式和流式响应模式 ### 2. AIOps 诊断 - 自动构建诊断计划 - 使用可用工具执行排查步骤 - 重新评估进度并生成最终的 Markdown 报告 ### 3. 工具集成 - 用于时间查找和知识检索的内置工具 - 用于日志和监控查询的 MCP 集成 ### 4. Web 体验 - 简单的静态前端 - 浏览器中的本地聊天记录 - 用于知识库索引的文件上传 ## 系统架构 ``` Browser UI | v FastAPI | +-- Chat API --------------------> RAG Agent Service | | | +-- ChatQwen | +-- Knowledge Tool | +-- Time Tool | +-- MCP Tools | +-- Upload API ------------------> Document Splitter | | | +-- Embedding Service | +-- Milvus Vector Store | +-- AIOps API -------------------> Planner -> Executor -> Replanner | +-- MCP Log Tools +-- MCP Monitor Tools ``` ## 技术栈 - 后端：FastAPI、SSE、Pydantic Settings - Agent 框架：LangChain、LangGraph - LLM：DashScope / Qwen - 向量数据库：Milvus - 主要持久层：PostgreSQL - 队列 / 缓存：Redis - 工具协议：MCP - 前端：静态 HTML、CSS、JavaScript ## 仓库结构 ``` app/ api/ HTTP routes services/ RAG, indexing, search, AIOps services agent/ MCP client and AIOps graph nodes core/ Milvus and LLM integration tools/ Built-in agent tools models/ Request and response models utils/ Logging and helpers static/ Web UI mcp_servers/ Mock MCP services for logs and monitoring aiops-docs/ Sample knowledge base documents ``` ## 当前范围 本项目最好被视为一个内部 SRE copilot，它可以在轻量级的本地模式下运行，也可以在 Dockerized 的服务栈中运行。 - MCP 服务器当前默认返回 mock（模拟）数据 - 默认的本地回退存储是 SQLite - Dockerized 运行时支持 PostgreSQL + Redis - 提供 API key 和基于能力的访问控制 - 生产模式现在需要明确的身份验证配置和非通配符 CORS - PostgreSQL schema 通过 Alembic 迁移进行管理 ## 前置条件 - Python `3.11` 到 `3.13` - Docker Desktop 或其他 Docker 运行时 - 有效的 DashScope API key ## 快速开始 ### 1. 克隆并进入项目 ``` git clone cd "SmartSRE Copilot Py" ``` ### 2. 创建虚拟环境并安装依赖 使用 `uv`： ``` uv venv source .venv/bin/activate uv pip install -e . ``` 使用 `pip`： ``` python -m venv .venv source .venv/bin/activate pip install -e . ``` ### 3. 创建 `.env` 使用附带的模板： ``` cp .env.example .env ``` 然后更新关键字段，特别是 `DASHSCOPE_API_KEY` 和安全设置： ``` DASHSCOPE_API_KEY=your_api_key ENVIRONMENT=dev CORS_ALLOWED_ORIGINS=http://localhost:9900,http://127.0.0.1:9900 APP_API_KEY=replace_with_a_secure_key DASHSCOPE_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1 DATABASE_BACKEND=postgres POSTGRES_DSN=postgresql://smartsre:smartsre@postgres:5432/smartsre REDIS_URL=redis://redis:6379/0 TASK_QUEUE_BACKEND=redis TASK_DISPATCHER_MODE=detached INDEXING_TASK_MAX_RETRIES=3 MILVUS_HOST=standalone MILVUS_PORT=19530 RAG_TOP_K=3 CHUNK_MAX_SIZE=800 CHUNK_OVERLAP=100 ``` 对于生产环境： - 设置 `ENVIRONMENT=prod` - 配置 `APP_API_KEY` 或 `API_KEYS_JSON` - 将 `CORS_ALLOWED_ORIGINS` 配置为明确的源，而不是 `*` ### 4. 启动完整技术栈 Linux 或 macOS： ``` make up ``` 此操作会启动： - Milvus - PostgreSQL - Redis - 一次性迁移任务 - FastAPI 应用容器 - 后台工作容器 如果您更喜欢以前的本地 Python 模式，您仍然可以使用： ``` make init ``` 如果您针对 Docker 外部的本地 PostgreSQL 实例运行应用程序，请首先运行迁移： ``` make db-upgrade ``` ### 5. 打开应用 - Web UI：[http://localhost:9900](http://localhost:9900) - API 文档：[http://localhost:9900/docs](http://localhost:9900/docs) - 健康检查：[http://localhost:9900/health](http://localhost:9900/health) ## Windows 启动 使用提供的脚本： ``` .\start-windows.bat .\stop-windows.bat ``` 如果您喜欢手动启动： 1. 启动 Docker 2. 运行 `docker compose up -d --build` 3. 启动 `mcp_servers/cls_server.py` 4. 启动 `mcp_servers/monitor_server.py` 5. 启动 `uvicorn app.main:app --host 0.0.0.0 --port 9900` 6. 上传示例文档到 `/api/upload` ## Docker 运行时 ### 完整技术栈 ``` docker compose up -d --build ``` Docker 服务包括： - `postgres` - `redis` - `migrate` - `app` - `worker` `migrate` 服务会在 `app` 和 `worker` 启动之前应用 `alembic upgrade head`。 ## 配置 主要的运行时设置位于 `app/config.py` 中。 关键设置： - `DASHSCOPE_API_KEY`：必填 - `ENVIRONMENT`：`dev` 或 `prod` - `CORS_ALLOWED_ORIGINS`：以逗号分隔或 JSON 数组形式的 CORS 白名单 - `APP_API_KEY` / `API_KEYS_JSON`：基于 API key 的身份验证配置 - `DASHSCOPE_API_BASE`：推荐用于兼容模式端点 - `DATABASE_BACKEND`：`sqlite` 或 `postgres` - `POSTGRES_DSN`：PostgreSQL 连接字符串 - `REDIS_URL`：Redis 连接字符串 - `TASK_QUEUE_BACKEND`：`database` 或 `redis` - `TASK_DISPATCHER_MODE`：`embedded` 或 `detached` - `INDEXING_TASK_MAX_RETRIES`：后台索引任务的最大重试次数 - `DASHSCOPE_MODEL`：聊天模型 - `MILVUS_HOST`、`MILVUS_PORT`：向量数据库连接 - `RAG_TOP_K`：检索数量 - `CHUNK_MAX_SIZE`、`CHUNK_OVERLAP`：文档分块 - `MCP_CLS_URL`、`MCP_MONITOR_URL`：MCP 服务端点 您可以从 [.env.example](/Users/mobicos/dev-sourcecode/Project-master/SmartSRE%20Copilot%20Py/.env.example) 开始。 ### 数据库迁移 对于 PostgreSQL，schema 变更通过 Alembic 管理，而不是在启动时创建表。 常用命令： ``` make db-upgrade make db-revision MESSAGE="describe change" ``` ## API ### 聊天 `POST /api/chat` ``` { "Id": "session-123", "Question": "What does high CPU usually indicate?" } ``` ### 流式聊天 `POST /api/chat_stream` 带有增量内容消息的 SSE 响应。 ### AIOps 诊断 `POST /api/aiops` ``` { "session_id": "session-123" } ``` 返回包含以下内容的 SSE 流： - 计划事件 - 步骤执行事件 - 最终诊断报告 ### 上传知识文档 `POST /api/upload` - 后端支持：`.txt`、`.md` - 上传的文件将被索引到 Milvus 中 ### 健康检查 `GET /health` 检查服务和 Milvus 的连通性。 ## 开发命令 ### 服务管理 ``` make init make start make stop make restart make check ``` ### Docker 和 MCP ``` make up make down make status make status-mcp ``` ### 代码质量 ``` make format make lint make type-check make security ``` ### 本地开发 ``` make dev make run make logs ``` ## AIOps 工作原理 诊断流程由三个核心节点构建： 1. `Planner` 将任务分解为可执行的排查步骤，并在可能时参考知识库经验。 2. `Executor` 通过选择工具和收集证据来执行当前步骤。 3. `Replanner` 决定是继续、调整剩余计划，还是生成最终响应。 最终输出预期为一份包含证据和建议的 Markdown 诊断报告。 ## 局限性 - 除非您将 MCP 服务器连接到真实系统，否则它们都是 mock（模拟）实现 - API key / 能力身份验证有意设计为轻量级，目前还不是完整的企业 IAM 解决方案 - 会话、任务和审计持久层可用，但迁移仍是 SQL 优先而非 ORM 管理的 - 尚未包含自动化测试套件 - 后台索引是异步的；在调试上传结果时请检查任务状态 ## 故障排除 ### FastAPI 无法启动 - 检查端口 `9900` 是否已被占用 - 检查 `logs/` 或 `server.log` 中的日志 - 验证您的 DashScope key 是否有效 ### Milvus 连接失败 ``` docker compose ps docker compose restart ``` ### MCP 工具不可用 - 确认两个 MCP 服务器都在运行 - 检查 `mcp_cls.log` 和 `mcp_monitor.log` - 验证您的环境设置中的 MCP URL ### 无检索结果 - 先上传文档 - 确认索引已成功完成 - 确认 Milvus 运行正常 ## 建议的下一步操作 如果您想将此项目发展至超越演示用途，最高价值的下一步操作是： 1. 添加持久会话存储 2. 添加身份验证和环境隔离 3. 将 MCP 工具连接到真实的可观测性系统 4. 为 API 和服务层添加测试 5. 规范化前端和后端的验证行为 ## 贡献 有关本地设置、提交风格和 pull request 预期，请参见 [CONTRIBUTING.md](/Users/mobicos/dev-sourcecode/Project-master/SmartSRE%20Copilot%20Py/CONTRIBUTING.md)。 ## 许可证 MIT

标签：AIOps, AI助手, AI应用, AV绕过, Black Hat, Copilot, DLL 劫持, DNS解析, FastAPI, ITSM, IT服务管理, IT运维, LangGraph, LLM, MCP, Multi-Agent, On-call, Plan-Execute-Replan, Python, RAG, Socks5代理, SRE, TCP SYN 扫描, Unmanaged PE, Web UI, 企业级, 偏差过滤, 后端开发, 大语言模型, 对话式AI, 开源项目, 技术栈, 搜索引擎查询, 故障响应, 故障诊断, 文件上传, 无后门, 日志查询, 智能分析, 智能客服, 智能运维, 检索增强生成, 流式输出, 测试用例, 生产级, 监控告警, 知识库问答, 知识检索, 自动化诊断, 自动化运维, 请求拦截, 运维工具, 运维排障, 运维知识库, 逆向工具