FaultMaven/faultmaven

# FaultMaven [](LICENSE) [](https://www.python.org/downloads/) [](https://fastapi.tiangolo.com/) **面向现代工程的开源 AI 故障排查 Copilot** FaultMaven 将您的实时遥测数据与操作手册、文档以及过往的修复记录相关联。它提供的答案基于您的实际系统，而非泛泛的猜测。借助这款既了解您的技术栈又了解您的组织架构的 AI Copilot，更快地解决故障。 传统的可观测性工具只能告诉您坏了**什么**。通用的 LLM 会猜测**为什么**，但无法洞察您的基础设施。FaultMaven 弥补了这一空白。 ## 系统组件 FaultMaven 由协同工作的三个组件组成： | 组件 | 代码库 | 用途 | |-----------|------------|---------| | **FaultMaven API** | 本代码库 | 后端服务器：调查引擎、知识库、AI 编排 | | **FaultMaven Dashboard** | [faultmaven-dashboard](https://github.com/FaultMaven/faultmaven-dashboard) | Web UI：知识库管理、案例历史记录、设置 | | **FaultMaven Copilot** | [faultmaven-copilot](https://github.com/FaultMaven/faultmaven-copilot) | 浏览器扩展：上下文故障排查覆盖层 | **典型用法：** Copilot 扩展是您在处理突发事件时的主要接口。Dashboard 用于管理您的知识库和审查过往案例。两者均连接到 API 后端。 ## 快速入门 在 5 分钟内让完整的 FaultMaven 技术栈运行起来。 ### 前置条件 - **Docker** 和 **Docker Compose** - **LLM 提供商**（以下任选其一）： - 云端：OpenAI, Anthropic, Fireworks AI, Google Gemini, Groq, Cohere, HuggingFace, OpenRouter - 本地：Ollama（无需 API 密钥） ### 步骤 1：启动技术栈 ``` # Clone the repository git clone https://github.com/FaultMaven/faultmaven.git cd faultmaven # 配置你的 LLM 提供商 cp .env.example .env # 编辑 .env：设置 OPENAI_API_KEY、ANTHROPIC_API_KEY 或配置 Ollama # 启动 API + Dashboard（从 Docker Hub 拉取预构建的镜像） # 这会自动创建数据库和默认管理员用户。 ./faultmaven.sh start # 或者：docker compose up -d ``` **执行过程：** 1. Docker 拉取镜像并启动服务。 2. API 会自动初始化数据库并运行迁移。 3. 创建一个默认的管理员用户：`admin` / `admin@local.faultmaven` ### 步骤 2：登录 1. 打开 **http://localhost:3333** 2. 选择 **Dev Login** 3. 输入用户名：`admin` 大功告成！您已准备就绪。 ### 可选：创建额外用户 如果您需要更多账户，可以通过 CLI 创建： ``` ./faultmaven.sh create-user ``` ### 步骤 3：安装 Copilot 扩展 1. 从 [Releases](https://github.com/FaultMaven/faultmaven-copilot/releases) 下载 `faultmaven-copilot.zip` 2. 解压文件 3. **Chrome/Edge：** 打开 `chrome://extensions` → 启用“开发者模式” → “加载已解压的扩展程序” → 选择 `.output/chrome-mv3/` 4. **Firefox：** 打开 `about:debugging#/runtime/this-firefox` → “临时载入附加组件” → 选择 `.output/firefox-mv3/` 中的任意文件 5. 点击扩展图标 → 设置 → 将 API URL 设置为 `http://localhost:8090` ### 步骤 4：配置 LLM 提供商 登录后，进入 Dashboard 侧边栏的 **LLM Settings**，验证您的提供商是否已连接： 1. 检查您配置的提供商是否显示 **Connected** 状态 2. 点击 **Test Connection** 以验证 API 密钥是否有效 3. 您可以直接在 Dashboard 中更改主要提供商或更新 API 密钥——更改会立即生效，无需重启 ### 步骤 5：开始故障排查 1. 打开 **Dashboard**（http://localhost:3333），将操作手册上传到您的 Knowledge Base 2. 导航到任何可观测性工具（AWS Console、Datadog、Grafana） 3. 点击 **Copilot** 扩展图标并开始故障排查 ### Docker 管理命令 用于管理基于 Docker 技术栈的便捷脚本： ``` # 用于基于 Docker 部署的主 CLI ./faultmaven.sh start # Start services ./faultmaven.sh start --demo # Start with demo data ./faultmaven.sh health # Check service health ./faultmaven.sh logs # View all logs ./faultmaven.sh logs api # View specific service logs ./faultmaven.sh restart # Restart all services ./faultmaven.sh stop # Stop all services ./faultmaven.sh clean # Remove containers (PROTECTS ./data) ./faultmaven.sh clean --wipe-data # Remove containers AND delete all data ``` ### 访问入口 | 组件 | URL | 描述 | |-----------|-----|-------------| | Dashboard | http://localhost:3333 | 用于知识库管理、案例历史记录、LLM 设置的 Web UI | | API | http://localhost:8090 | REST API | | API Docs | http://localhost:8090/docs | 交互式 OpenAPI 文档 | ### 替代方案：本地开发设置 面向贡献者或调试场景，您可以将组件作为本地进程而非 Docker 运行。 **1. 启动 API 后端：** ``` # 将 API 作为本地进程启动 ./scripts/faultmaven-dev.sh start # 验证其是否正在运行 ./scripts/faultmaven-dev.sh health ``` API 将在 `http://localhost:8090` 处可用 **2. 启动 Dashboard（在另一个进程中）：** Dashboard 位于单独的代码库中。要在本地运行： ``` # Clone the dashboard repository（如果尚未 clone） git clone https://github.com/FaultMaven/faultmaven-dashboard.git cd faultmaven-dashboard # 安装依赖 npm install # 或者：pnpm install # 配置 API 端点（可选 - 默认为 http://localhost:8090） cp .env.example .env # 如需修改请编辑 .env：VITE_API_URL=http://localhost:8090 # 启动开发服务器 npm run dev # 或者：pnpm dev ``` Dashboard 将在 `http://localhost:5173`（Vite 开发服务器）处可用，并连接到位于 `http://localhost:8090` 的 API。 ### 本地开发管理命令 用于管理本地开发环境的便捷脚本： ``` # 面向 FaultMaven 的贡献开发者 ./scripts/faultmaven-dev.sh start # Start API as local process ./scripts/faultmaven-dev.sh stop # Stop the API ./scripts/faultmaven-dev.sh restart # Restart the API ./scripts/faultmaven-dev.sh health # Run comprehensive health checks ./scripts/faultmaven-dev.sh logs # Stream application logs ./scripts/faultmaven-dev.sh test # Run tests (delegates to scripts/tests.py) ``` 有关更详细的设置说明，请参阅 [开发设置](docs/development/local-setup.md)。 ## 为什么选择 FaultMaven？ FaultMaven 不仅仅是一个聊天机器人包装器；它是一个具备上下文感知能力的调查引擎，旨在随着每次突发事件变得越来越智能。 ### 1. 深度上下文感知 通用聊天机器人无法访问您的日志、配置或部署。FaultMaven 关联您的**全栈上下文**——将错误与最近的更改、配置漂移和系统状态连接起来，以更快地找到根本原因。 **示例：** 一个 Kubernetes pod 处于 crashlooping 状态。ChatGPT 给出的是通用建议。而 FaultMaven 会将您的 pod 日志与部署 YAML 及最近的更改一起分析——然后识别出 2 小时前的 ConfigMap 更新引入了一个无效的环境变量。 ### 2. 零上下文切换 停止在浏览器标签页之间复制错误信息。**[FaultMaven Copilot](https://github.com/FaultMaven/faultmaven-copilot)** 浏览器扩展将 AI 故障排查直接叠加在您现有的工具之上——AWS Console、Datadog、Grafana 或 localhost。无需后端代理、webhook 或复杂的集成。 **工作原理：** FaultMaven 运行在您的浏览器中，而不是您的集群中。当您在 CloudWatch 中查看日志、在 Datadog 中查看链路追踪，或在 Kubernetes Dashboard 中查看 pod 时，Copilot 扩展会捕获相关的上下文，并实时将其与您的 Knowledge Base 相关联。 ### 3. 知识飞轮 大多数故障排查知识在故障处理结束后就丢失了。FaultMaven 通过“播种与成长”（Seed & Grow）生命周期，将这些丢失的数据转化为不断增长的资产： - **通过操作手册播种：** 您不是从零开始的。将现有的操作手册和文档预加载到 Knowledge Base 中，以便 AI 从第一天起就了解您的标准操作程序。 - **在故障中成长：** 随着您的排查，AI 也在学习。当一个案例被解决时，FaultMaven 会提取成功的步骤和根本原因，以自动更新知识库。 - **结果：** 您的静态文档变成了一个动态的、自我改进的引擎。今天突发事件的解决方案将成为明天的自动化修复方案。 ### 4. 机会性调查框架 FaultMaven 采用**机会性调查**方法，其中 agent 根据数据可用性完成任务，而不是遵循僵化的顺序阶段。 **核心原则：** - **基于里程碑的进度** - 追踪已完成的内容，而不是您所处的阶段。在数据允许的情况下，在一轮交互中完成多个里程碑。 - **线性阶段流转** - 两条调查路径（MITIGATION_FIRST、ROOT_CAUSE）均遵循 1→2→3→4 的进展过程。 - **缓解作为一种工具** - 在早期阶段提供快速修复，而不会中断调查流程。 **案例生命周期：** `INQUIRY` → `INVESTIGATING` → `RESOLVED` / `CLOSED` **关键组件：** - **MilestoneEngine** - 机会性地追踪验证、调查和解决里程碑。 - **WorkingConclusionGenerator** - 持续的进度跟踪，以防止循环推理。 - **MemoryManager** - 热/温/冷内存分层，用于在长时间调查中维护上下文。 ### 5. 灵活的多 LLM 支持 FaultMaven 采用模型无关的架构设计，让您可以自由地为特定需求和预算选择最佳的智能方案。 它支持多种后端，包括： - **前沿模型：** 连接到主要的云提供商（OpenAI, Anthropic, Google）以进行复杂推理和多模态分析。 - **推理提供商：** 利用高速推理引擎（Groq, Fireworks AI）实现低延迟响应。 - **本地与开源：** 使用本地运行器（Ollama, vLLM）完全在您自己的硬件上运行，以实现最大的数据隐私和零 API 成本。 - **模型路由：** 内置回退逻辑通过在主 API 不可用时自动切换提供商来确保高可用性。 ## 版本说明 FaultMaven 运行在单一的、与部署无关的**核心**之上。该引擎可针对不同的环境进行配置，为您提供两种使用平台的不同方式。 ### 1. FaultMaven 开源版（本地部署） **最适合：** 个人、贡献者和隔离网络环境。 在此配置中，您在自己的硬件上运行核心——既可以直接作为服务器进程，也可以在 Docker 容器内运行。您拥有对基础设施的完全控制权。 - **自托管：** 您拥有整个技术栈。您管理容器、数据库以及配置。 - **构建您自己的知识：** 本地环境从零开始。它包含了摄取您自己的操作手册并从头开始构建**个人知识库**的所有能力，完全根据您的特定需求量身定制。 - **离线能力：** 可完全离线运行（使用本地 LLM 如 Ollama），非常适合高限制环境。 按照上方的 [快速入门](#quick-start) 指南开始运行。 ### 2. FaultMaven 云端版 (SaaS) **最适合：** 需要协作和组织级规模的工程团队和企业。 SaaS 版本在分布式、生产级配置中运行核心。它通过托管的基础设施和数据提供立竿见影的价值。 - **托管的 Kubernetes 基础设施：** 我们在高可用性的 Kubernetes 控制平面上运行核心，为您处理自动扩容、加密和零停机更新。 - **预置智能：** 与空的本地状态不同，SaaS 版本附带一个预先填充了行业标准的故障排查指南和最佳实践的**全局知识库**。 - **协作式 3 层知识：** 云平台激活了完整的 3 层架构： 1. **全局：** 预置的全系统知识。 2. **团队：** 共享的操作手册和事件日志（机构记忆）。 3. **个人：** 私人笔记和草稿。 ### 比较 | 特性 | 开源版 (本地) | 云端版 (SaaS) | | ------- | ------------------- | ------------ | | **配置** | 单用户 / Docker | 多用户 / 托管 K8s | | **知识库初始状态** | **为空** (由用户构建) | **预加载** (包含全局知识库) | | **知识层级** | 仅个人 | **全局 + 团队 + 个人** | | **LLM 配置** | Dashboard 管理 (热重载) | Dashboard 管理 (热重载) | | **案例管理** | 完整 (带归档) | 完整 (带归档 + 组织级视图) | | **用户管理** | 不适用 (单用户) | 完整 CRUD、邀请、角色 | | **基础设施** | 用户管理 | 完全托管 | | **安全性** | 本地认证 | SSO (SAML/OIDC)，SOC 2 就绪 | | **会话持久性** | **临时** (FakeRedis，重启时重置) | **持久化** (Redis，跨会话保存) | | **访问地址** | `http://localhost:3333` (仅限 localhost) | `https://app.faultmaven.ai` | **订阅：** [https://cloud.faultmaven.ai](https://cloud.faultmaven.ai) ## 架构 FaultMaven 是一个具有整洁**垂直切片架构**的单体应用。我们没有按技术层来分离，而是按功能模块进行组织。 ``` Browser Extension / Dashboard | HTTPS v +------------------------------------------------------------------+ | FaultMaven API (8090) | | | | +------------------------------------------------------------+ | | | API Layer | | | | /api/v1/agent /api/v1/cases /api/v1/knowledge ... | | | +------------------------------------------------------------+ | | | Service Layer | | | | AgentService CaseService KnowledgeService AuthService | | | +------------------------------------------------------------+ | | | Infrastructure Layer | | | | LLM Router Persistence Security Observability | | | +------------------------------------------------------------+ | +------------------------------------------------------------------+ | | | v v v +--------+ +---------+ +----------+ | Redis | |ChromaDB | | SQLite/ | | (opt) | |(Vectors)| | Postgres | +--------+ +---------+ +----------+ ``` ### 模块 | 模块 | 描述 | |--------|-------------| | `agent` | 调查编排、AI 工具、OODA 框架 | | `auth` | 用户、会话、组织、团队、RBAC | | `case` | 调查案例和生命周期管理 | | `evidence` | 文件上传、元数据、存储适配器 | | `knowledge` | Embeddings、向量搜索、RAG、知识条目 | | `report` | 报告生成和建议 | ## 项目结构 ``` faultmaven/ ├── faultmaven/ # Main application │ ├── main.py # FastAPI entry point │ ├── api/ # Shared API middleware, dependencies │ ├── modules/ # Vertical slice feature modules │ │ ├── agent/ # Investigation + AI tools │ │ ├── auth/ # Authentication + authorization │ │ ├── case/ # Case management │ │ ├── evidence/ # Evidence/file handling │ │ ├── knowledge/ # Knowledge base + RAG │ │ └── report/ # Reporting │ ├── config/ # Settings (single env-read point) │ ├── container/ # Dependency injection │ ├── infrastructure/ # Shared adapters (LLM, DB, storage) │ ├── core/ # Core domain logic │ └── services/ # Service layer ├── tests/ # Test suite │ ├── unit/ │ ├── integration/ │ ├── health/ │ └── performance/ ├── docs/ # Documentation ├── alembic/ # Database migrations ├── faultmaven.sh # CLI wrapper (start/stop/test) ├── docker-compose.yml # Local services ├── Dockerfile # Container image ├── pyproject.toml # Dependencies and tools └── .env.example # Configuration template ``` ## 配置 ### 环境变量 从模板创建一个 `.env` 文件： ``` cp .env.example .env ``` FaultMaven 有两个配置层： | 级 | 配置内容 | 如何更改 | | ----- | ------------------- | ------------- | | **环境 (`.env`)** | 基础设施：数据库、认证模式、Redis、CORS、端口 | 编辑 `.env` 文件，重启服务器 | | **Dashboard (数据库支持)** | LLM 设置：提供商、API 密钥、回退链 | 通过 Dashboard UI 更改，立即生效 | 在首次启动时，LLM 设置从 `.env` 加载。一旦您通过 Dashboard 修改了它们，数据库就成为 LLM 配置的真实来源。基础设施设置始终来自 `.env`。 ### 基础设施设置 (`.env`) | 类别 | 变量 | 描述 | |----------|-----------|-------------| | 数据库 | `DATABASE_URL` | SQLite (默认) 或 PostgreSQL | | 会话 | `REDIS_HOST`, `REDIS_URL` | FakeRedis (默认) 或真正的 Redis | | 向量 | `VECTOR_STORAGE_TYPE` | `inmemory` (默认) 或 `chromadb` | | 安全 | `JWT_SECRET_KEY`, `CORS_ALLOW_ORIGINS` | 认证和 CORS 设置 | 有关所有选项和详细注释，请参见 [.env.example](.env.example)。 ### LLM 提供商设置 在 `.env` 中设置您初始的 LLM 提供商： ``` # 选择主要 provider CHAT_PROVIDER=openai # openai, anthropic, fireworks, gemini, groq, cohere, huggingface, openrouter, local # 为你的 provider 添加 API 密钥 OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... FIREWORKS_API_KEY=fw-... GROQ_API_KEY=gsk-... COHERE_API_KEY=xxx HUGGINGFACE_API_KEY=hf_... OPENROUTER_API_KEY=sk-or-... # 可选：为特定任务配置单独的 provider MULTIMODAL_PROVIDER=gemini # Visual evidence processing SYNTHESIS_PROVIDER=openai # RAG document queries ``` 首次启动后，您可以通过 **Dashboard > LLM Settings** 页面管理所有 LLM 设置（提供商、API 密钥、回退链）。更改会热重载——无需重启服务器。 **回退链：** 主提供商 -> Fireworks -> OpenAI -> 本地 ## 开发 ### 测试 ``` # 运行所有测试 ./faultmaven.sh test # 运行并生成覆盖率报告 ./faultmaven.sh test --coverage # 或者直接使用 pytest pytest tests/unit/ pytest --cov=faultmaven ``` ### 代码质量 ``` # Linting ruff check . # Formatting black . isort . # Type checking mypy faultmaven/ ``` ### 数据库迁移 ``` # 创建迁移 alembic revision --autogenerate -m "description" # 应用迁移 alembic upgrade head ``` ## 技术栈 | 层级 | 技术 | |-------|--------------| | **框架** | Python 3.11+, FastAPI, Uvicorn, AsyncIO | | **LLM/AI** | LangGraph, LangChain, OpenAI, Anthropic, Fireworks, Gemini, Groq, Cohere, HuggingFace, OpenRouter | | **数据库** | SQLAlchemy 2.0, SQLite (本地), PostgreSQL (生产环境), Alembic | | **向量数据库** | ChromaDB, sentence-transformers | | **缓存** | Redis (云端), FakeRedis (本地 — 完整的 API 兼容性) | | **认证** | JWT (PyJWT), bcrypt, RBAC | | **可观测性** | Opik tracing, Prometheus 指标, structlog | | **测试** | pytest, pytest-asyncio, pytest-cov | ## 用户界面 FaultMaven 提供两个前端界面。有关设置说明，请参见 [快速入门](#quick-start) 或 [本地开发设置](docs/development/local-setup.md)。 ### Dashboard **[FaultMaven Dashboard](https://github.com/FaultMaven/faultmaven-dashboard)** - 用于主动知识管理的 Web 应用： - **知识库管理**：上传操作手册，搜索索引文档，归档和恢复项目 - **案例管理**：查看、搜索、过滤和注释过去的调查。归档已解决的案例以供长期参考 - **LLM 设置**：查看提供商状态，测试连接，更改主要提供商和更新 API 密钥——所有更改立即生效，无需重启 ### 浏览器扩展 **[FaultMaven Copilot](https://github.com/FaultMaven/faultmaven-copilot)** - 用于被动故障排查的浏览器扩展： - **上下文捕获**：直接从您的屏幕读取日志、堆栈跟踪和仪表板 - **流程内诊断**：在 AWS Console、Datadog、Grafana 和其他工具中进行故障排查 - **知识库集成**：实时引用您的文档 - **会话连续性**：跨浏览器会话维护聊天历史记录 ### 从源码构建 用于开发或自定义，请参见相应的代码库： - [Dashboard 开发](https://github.com/FaultMaven/faultmaven-dashboard#development) - [Copilot 开发](https://github.com/FaultMaven/faultmaven-copilot#development) ## 文档 | 文档 | 描述 | |----------|-------------| | [docs/README.md](docs/README.md) | 文档索引 | | [docs/architecture/](docs/architecture/) | 系统设计和 ADR | | [docs/guides/](docs/guides/) | 操作指南 | | [docs/development/](docs/development/) | 开发标准 | | [docs/operations/](docs/operations/) | 操作手册和监控 | ## 贡献 请参见 [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) 了解： - 开发设置 - 编码标准 - 测试要求 - PR 指南 ## 许可证 Apache 2.0 - 详见 [LICENSE](LICENSE)。 ## 支持 - **问题反馈：** [GitHub Issues](https://github.com/FaultMaven/faultmaven/issues) - **讨论交流：** [GitHub Discussions](https://github.com/FaultMaven/faultmaven/discussions) - **邮箱：** support@faultmaven.ai

标签：AIOps, AI故障排查, Anthropic, API网关, API集成, AV绕过, CIS基准, DLL 劫持, Docker, Docker Compose, FastAPI, IT运维, LLM, LLM评估, Ollama, OpenAI, Python, Ruby, Socks5代理, SRE, Unmanaged PE, 仪表盘, 偏差过滤, 内存规避, 可观测性, 大语言模型, 安全防御评估, 开源, 搜索引擎查询, 故障修复, 无后门, 智能副驾驶, 测试用例, 浏览器扩展, 现代化工程, 知识库, 编排引擎, 请求拦截, 逆向工具, 遥测数据