通用运维根因分析 Agent 框架 · 零依赖起步 · 适配器抽象 · LLM DECIDE · 开源
OpenRCA 是一个开源的通用根因分析（Root Cause Analysis）Agent 框架。它不绑定任何特定运维场景——通过适配器模式解耦框架和系统，pip install 即可跑，逐步接入你的 Prometheus、ELK、Git、Kubernetes。
OpenRCA 不替代任何已有系统。它替代的是运维在多个系统之间来回切换、翻译指标含义、手动串联的 10 分钟。
graph TD
A["告警/日志/文本输入"] --> B["Agent (LLM DECIDE)"]
B --> C["Web UI 诊断对话"]
B --> D["交付 (飞书/工单)"]
B --> E["业务工具"]
E --> E1["监控 (WHAT/WHEN/WHERE)"]
E --> E2["日志 (WHO)"]
E --> E3["配置 (WHY)"]
B --> F["控制工具"]
F --> F1["navigate (push/pop 切换目标)"]
F --> F2["deliver (输出结论)"]
F --> F3["search_targets (搜索注册表)"]
F --> F4["get_neighbors (拓扑邻接)"]
F --> F5["search_cases (历史案例)"]
B --> G["基础设施"]
G --> G1["对象栈 Push/Pop/回退"]
G --> G2["目标解析引擎"]
G --> G3["拓扑图谱 + 调用索引"]
G --> G4["故障案例库 (向量匹配)"]
Agent 排障采用 LLM DECIDE 模型：调查方向的决策权完全交给 LLM。 LLM 自由选择业务工具（监控/日志/配置），自主通过控制工具（navigate/deliver）决定何时切换目标、何时结束。框架只做边界防护（防深度/防循环/防超时/防混用）。
# 1. 安装（Python 3.11+）
pip install openrca
# 带 ChromaDB 案例匹配和向量搜索（推荐）：
pip install "openrca[full]"
# 2. 启动（Web UI + API）
openrca serve
# 3. 打开浏览器 http://localhost:8080
# → 诊断对话：贴日志/描述异常，Agent 自动排查
# → 管理后台：手动录入 Target、管理拓扑、测试适配器
# 或 API 直接调用：
curl -X POST http://localhost:8080/api/v1/investigate \
-H "Content-Type: application/json" \
-d '{"source_type":"monitor","source":"prometheus_emr","instance":"core-07","anomaly":"cpu_high","value":95}'
# 4. Docker 全家桶（含 Ollama + ChromaDB + Web UI）
git clone https://github.com/openrca/openrca
docker compose up -d| 原则 | 说明 |
|---|---|
| 零依赖起步 | pip install openrca && openrca serve 就能跑。内置 SQLite + NetworkX + 内存 Dict 存储 |
| 适配器抽象 | 监控/日志/配置各层通过适配器接入——不绑定 Prometheus/ELK/Git，换了后端只改 config.yaml |
| 对象栈模型 | Agent 维护 LIFO 调查栈，发现新嫌疑人 Push，无收获 Pop 回退，栈底走到头才结案 |
| LLM DECIDE | |
| LLM 分工 | LLM 负责调查方向决策（用什么工具、查什么数据、何时切换目标）；适配器负责数据获取（确定性规则）；拓扑引擎负责关系发现（纯统计）。各司其职 |
| 开源友好 | MIT 协议 · Python 3.11+ · 基包零依赖 · 适配器贡献者只需实现 2-4 个方法 + 类型注解 |
| 场景 | 怎么用 |
|---|---|
| 大数据集群（Hadoop/Spark/Hive） | 接入 Prometheus + ELK + Airflow，自动排查任务失败/节点异常 |
| K8s + 微服务 | 接入 Prometheus + Loki + Istio，跨服务追踪调用链根因 |
| 传统 Linux + 数据库 | 接入 Zabbix + SSH 日志 + Git，排查硬件/配置变更导致的异常 |
| 混合云 | 同时接入 AWS CloudWatch + 阿里云 ARMS，跨云统一排障 |
| 文档 | 内容 |
|---|---|
| V1-product-scope.md | V1 产品范围 — 8 个 Web UI 核心功能、API vs Web UI 分工、Web UI 功能清单 |
| architecture.html | 架构总览图（SVG 深色主题） |
| agent-flow.html | Agent 核心流程（1→8 步骤 + CASE-MATCH/对象栈/DECIDE 分支） |
| target-topology.html | Target 模型（6 种类型）+ 三层存储设计（NetworkX 图 / call_index / Adapter 实时） |
完整设计文档维护在 Obsidian 知识库中，不在代码仓库内。
| 模块 | 默认选择 | 可选替代 |
|---|---|---|
| Agent 编排 | 自实现 ReAct + 对象栈 | — |
| Python | 3.11+ | — |
| LLM | OpenAI 兼容协议，默认指向 Ollama 本地 | DeepSeek / GPT / Claude |
| 向量存储 | 内存 Dict（零依赖） | ChromaDB（pip install openrca[full]）/ pgvector / Qdrant |
| 图存储 | NetworkX + SQLite | Neo4j |
| Web UI | 纯 HTML + Vanilla JS + D3.js | — |
| 部署 | pip install |
docker compose up -d |