Skip to content
SxzcodePublic

About

An ELK-alert-driven platform that automatically fixes production bugs: a Kibana alert comes in, an agent reproduces, fixes, and self-verifies the bug inside a Docker sandbox, then opens a GitLab merge request — through exactly the same review process as a human.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

OpsPilot

ELK 告警驱动的线上 Bug 自动修复平台:Kibana 告警进来,agent 在 Docker 沙箱里复现、修复、自验证,通过后自动向 GitLab 提 MR——走与人工完全相同的评审流程。

诊断报告实拍:告警 → 根因 → 修复方案 → 验证证据

English | 中文

CI License: MIT Python

项目状态:一期「线上 Bug 自动修复」已完成,demo 环境全链路验证通过;当前为 Alpha / 技术预览版,面向生产设计但尚未通过 Production Ready Gate。二期「MR 自动审查」在规划中(review 模块当前为占位骨架)。

是什么 / 为什么

线上 error 日志的典型命运:告警刷屏 → 值班人疲于奔命 → 真 bug 和噪音混在一起。OpsPilot 把这个循环自动化,同时把「agent 会不会乱来」这个信任问题当成核心设计问题来解:

  • 线上 Bug 自动修复(一期,已完成):ES 错误日志 → Kibana Alerting webhook → 触发网关去重分诊 → agent 在一次性 Docker 沙箱中先写能复现 bug 的失败测试,再修复到测试转绿 → 推送 opspilot/fix-<fingerprint> 分支并开 MR → 通知负责人评审。验证不通过则降级为带完整诊断报告的 Issue,绝不提烂 PR。
  • GitLab MR 自动审查(二期,WIP):确定性静态分析(SpotBugs/PMD)+ LLM 设计层审查的两层架构,输出带严重等级的 MR 评论。模块边界与插件接口已就位,实现排在一期之后。

agent 没有特权通道:GitLab 侧用 Developer 角色 token + 保护分支 + 强制人工 approve,结构上保证 agent 不可能自己合代码(见 docs/deployment.md §3)。

架构

控制面 / 数据面分离。控制面管配置与观测,数据面跑触发与修复:

flowchart LR
    subgraph CP["控制面"]
        Console["Console(React)"]
        API["console-api(FastAPI)"]
        DB[("PostgreSQL<br/>配置 · 指纹状态 · 报告 · 反馈")]
        Console --> API --> DB
    end

    subgraph DP["数据面"]
        Kibana["Kibana Alerting"] -->|"webhook"| GW["trigger-gateway<br/>指纹状态机 · Triage · 限流"]
        GW -->|"TRIGGER"| Pipeline["fix-pipeline<br/>复现 → 修复 → 自验证"]
        Pipeline --> Sandbox["sandbox-runner<br/>Docker 临时容器,用完即毁"]
        Pipeline -->|"opspilot/fix-* 分支 + MR"| GitLab["GitLab"]
        GitLab -->|"CI 结果回读"| Pipeline
        Pipeline --> Notify["notifier<br/>飞书 / 邮件"]
    end

    GW -.->|"读配置 / 写状态"| DB
    Pipeline -.->|"写 AgentRun / 诊断报告"| DB
Loading

模块职责详见 docs/architecture.md §3。

核心设计亮点

  • 错误指纹状态机去重:指纹 = hash(异常类型 + 本服务顶层栈帧 + 服务名),刻意不含行号——否则修复合入后行号漂移会把「复发」误判成新 bug,回归检测失效。每个指纹一条状态记录(NEW → TRIAGING → PR_OPEN → RESOLVED / REGRESSED …),同一个 bug 只修一次,后续告警只计数。
  • Triage 四分类前置闸门:修复最难的不是「怎么修」,而是「这是什么东西」。每个指纹先落进 ACTIONABLE / BENIGN / PRODUCT_GAP / PROPAGATED 四个桶之一再决定动不动手。传导型错误(死在 RPC 边界的超时/熔断)永不触发 pipeline——下游服务是受害者,去「修复」它们只会产出基于错误诊断的烂 PR。修复空间语义发散即 PRODUCT_GAP,产出需求澄清单路由给 PM,agent 绝不偷偷做产品决策。
  • 沙箱红→绿自验证:agent 必须先写出能复现该 bug 的失败测试,修复后该测试转绿且编译 + 相关模块测试通过,三条缺一即降级。这证明「这个修复对上了这个 bug」,而不只是「代码能跑」。
  • 两级验证,不重造 CI:沙箱内只做定向验证(分钟级、资源小);全量回归交给 GitLab CI,结果回读——CI 红则自动在 MR 评论说明、标记修复存疑并通知负责人,不二次提 PR。企业 CI 已有的缓存、runner、权限体系不重复造。
  • 峰值资源为常数的降级哲学:沙箱是「每次修复一个临时容器」,不是每服务常驻实例。指纹状态机 → Triage → 服务级限流 → 全局并发池四道闸门之后,告警洪峰再大,峰值资源 = 并发数 × 单次成本;超额只排队,报告变慢而系统不倒。修复信心不足时降级为诊断报告 Issue——诊断能力在修复失败时依然有产出,系统就不产生纯噪音。
  • 结构化数据飞轮(明确不做向量 RAG):飞轮载体是 PostgreSQL 里的结构化反馈表(审查裁决、PR merge/关闭、人工修改 diff),SQL 查询做 few-shot 注入,可解释、可调试、可人工编辑。案例积累到几千条再加 embedding 层是顺水推舟——先有数据,后有检索,顺序反了就是空转。

控制台实拍

指纹工作台(状态机去重) 运行记录时间线(每步留痕)
指纹工作台 运行记录时间线
Incident 级联故障时间线 统计面板
Incident 时间线 统计面板

自动开出的 GitLab MR(复现测试随 MR 一并提交,CI 结果回读):

OpsPilot 自动开出的 MR

v0.1 基准结果

基准集采取 mutation 注入冷启动(roadmap v3):向 demo-service(级联演示道具,源码见 examples/demo-service)的 GitLab 仓库注入 6 类已知缺陷(off-by-one / 比较符错误 / 资源未关闭 / 错误状态判断 / 异常被吞 / 判空缺失),逐案例跑真实 pipeline(真实模型 + 真实沙箱 + 真实 MR)。正式轮结果:

指标 值
gate-pass(两级验证全过并开出 MR) 6/6(MR !4–!9,修复语义逐案抽查与期望一致)
单案模型调用 7–10 次(DeepSeek);单案端到端耗时 79–178s
模型调用总消耗 正式轮 50 次(入 17,984 / 出 16,360 tokens)
对照实验 同案例同模型压到 max-turns=6 → gate-pass 0/6(2 案已修复转绿但无轮次提交报告)——轮次预算是一阶变量,完整分析见结果全文

案例定义、重放方式与逐案数据:benchmarks/ · results-v0.1.md。失败对照轮也完整保留——带失败记录的基准才可信。

另有真实开源 bug 子集(Defects4J 风格,取自 apache/commons-lang 真实 fix commit):同预算(max-turns=10)下 gate-pass 0/3,如实呈现。逐案失败断点分析(复现测试方向 / 大库探索不收敛 / 真实构建约束)见 results-real-bugs.md;这些分析已逐一转化为 v0.2 的 agent 探索策略改进项——真实 bug 暴露的是 agent 在大型陌生代码库中探索与定向复现的能力短板,也正是下一阶段要补的课。

三引擎对打(M11:builtin vs codex vs bare-codex,同一考题集与验证底座,含"缰绳值多少钱"的对照证据)见 results-engine-ab.md。

快速开始

环境:Python 3.11+、Docker、Node.js 18+(仅前端需要)。Windows / Linux / macOS 通用。

# 1. 起依赖:PostgreSQL(可选 demo / elk profile 起演示道具服务 + ELK + GitLab CE)
docker compose up -d postgres
# 完整 demo 环境:docker compose --profile demo --profile elk up -d

# 2. Python 虚拟环境
python -m venv .venv
# Windows PowerShell:  .venv\Scripts\Activate.ps1
# Windows Git Bash:    source .venv/Scripts/activate
# Linux / macOS:       source .venv/bin/activate
pip install -e ".[dev]"   # pip 慢可加 -i https://pypi.tuna.tsinghua.edu.cn/simple
cp .env.example .env      # 按需修改;默认指向 compose 里的 PG

# 3. 测试(测试数量以当前收集结果为准;集成测试需要本机 Docker)
pytest -q -m "not integration" --timeout=10
pytest -q -m integration  # Docker/Maven 测试可能较长;由 CI job 总时限约束

# 4. 数据库迁移和后端服务(应用启动不自动迁移,避免多副本竞争)
alembic upgrade head
python -m opspilot.gateway      # trigger-gateway → http://127.0.0.1:8000
python -m opspilot.console_api  # console-api     → http://127.0.0.1:8001

# 5. 起前端控制台
cd console && npm install && npm run dev   # → http://localhost:5173

# 6. 健康检查
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8001/health

已有旧库的注意:数据库 schema 由 Alembic 管理(migrations/)。旧库若来自 Alembic 引入前的 create_all,先执行 alembic stamp head,再按发布说明完成升级。单实例本地开发如需启动时迁移,可设置 OPSPILOT_AUTO_MIGRATE=true。

配置通过 OPSPILOT_ 前缀环境变量注入(.env),完整清单见 docs/deployment.md §2。模型接入(base_url + api_key + model)走控制台 ModelProvider 配置,api_key Fernet 加密落库,兼容任何 Anthropic 协议端点。

活体 demo:Spring 官方 PetClinic

活体 demo 的主角是社区公认的 spring-projects/spring-petclinic。fork 托管在本机 GitLab(compose gitlab 服务)的 root/spring-petclinic,代码不纳入本仓库——OpsPilot 仓只在 compose 与文档中引用它。

  • bug 分支 opspilot/demo-bug:在 OwnerController 的 owners 分页搜索里埋了一个真实感缺陷——page size 开放为查询参数但漏了下限校验,GET /owners?size=0 触发 IllegalArgumentException(HTTP 500,ERROR 日志带 org.springframework.samples.petclinic 栈帧)。
  • 日志:bug 分支配置了 logstash-logback-encoder,JSON 日志落 /var/log/petclinic/*.json.log,filebeat 采集进 demo-logs-*(service.name=petclinic),与 demo-service 同格式。
  • 构建:compose demo profile 的 petclinic 服务(:8082),构建上下文是 GitLab 仓的本地 clone(默认 ../.demo-src/spring-petclinic,可用 PETCLINIC_SRC 覆盖)。
docker compose --profile demo --profile elk up -d
curl 'http://localhost:8082/owners?size=0'   # 预期 500

随后 filebeat → ES → Kibana rule → trigger-gateway 自动归因到 petclinic 并生成指纹(Kibana 告警规则配置见 examples/demo-service/kibana-alert-setup.md)。

另有两个自研 Spring Boot 服务 demo-service / demo-gateway(compose demo profile,:8080/:8081)已挪至 examples/,定位为级联故障演示道具:demo-gateway 的 checkout 入口调用 demo-service,后者内置一个故意植入的 NPE,用于演示跨服务级联故障的 Incident 聚合与源头归因。

项目结构

├── src/opspilot/
│   ├── core/            # 共享层:config(pydantic-settings)、db、ORM models(9 张表)、structlog、Bearer auth
│   ├── gateway/         # trigger-gateway:Kibana webhook、指纹状态机、Triage、限流、归因、ES 回查
│   ├── pipeline/        # fix-pipeline:七步编排、agent tool-use loop、诊断报告生成、GitLab 自动 MR
│   ├── sandbox/         # sandbox-runner:SandboxBackend、LocalDocker 实现、全局并发池
│   ├── plugins/         # 扩展槽口:StackPlugin / Notifier / FixEngine 协议 + Java 栈实现、surefire 解析、entry-points 注册
│   ├── notify/          # 通知调度:渠道路由、冷却窗口合并摘要
│   ├── review/          # review-service(二期,占位骨架)
│   ├── console_api/     # 控制台 REST API:服务/路由/策略/ModelProvider CRUD、指纹工作台、运行记录
│   └── gitlab_client.py # GitLab REST API v4 封装(分支 + MR + CI 回读)
├── console/             # React 18 + Vite + antd 控制台(服务/指纹/报告/运行/统计 五个页面)
├── examples/            # 级联演示道具(demo-service / demo-gateway 两个 Spring Boot 服务)+ 示例插件(钉钉 notifier)
├── benchmarks/          # v0.1 基准集:mutation 注入脚本 + 案例定义(cases.json)+ 实测结果
├── deploy/filebeat/     # Filebeat 采集配置(demo-service / demo-gateway / petclinic 日志 → ES demo-logs-*)
├── migrations/          # Alembic 迁移
├── scripts/             # 运维脚本:故障注入、gateway 压测、ModelProvider 播种、端到端演练
├── tests/               # 单测与 Docker 集成测试(数量由 CI 收集结果决定)
├── tools/screenshots/   # 发布物料工具(Playwright 截图脚本,独立 npm 工程)
└── docs/                # 架构 / 部署 / 插件开发(含 images/ 实拍图)

插件体系

五个扩展槽口,只抽象「真正会变的东西」(详见 docs/architecture.md §8),基于标准 entry-points 发现——内置与第三方插件同一机制,开发指南见 docs/plugins.md:

  • StackPlugin:技术栈的确定性部分(镜像、跑测试、静态分析、stack trace 解析)。当前实现 Java(Spring Boot + Maven),LLM 推理部分语言无关、不插件化。
  • Notifier:通知渠道。已实现飞书(自定义机器人 webhook)与邮件(SMTP)。
  • ModelProvider:模型接入做成控制台配置实体,任何 Anthropic 兼容端点(官方 / 国内网关 / 自建中转)填 base_url + key 即用;审查与修复可绑定不同档位模型做成本分层。
  • SandboxBackend:沙箱执行后端。已实现 LocalDockerBackend(docker-py 临时容器 + 共享 .m2 缓存卷),KubernetesBackend(K8s Job + ResourceQuota 治理)预留接口。
  • FixEngine:修复引擎抽象(entry-points 可插拔)。已实现 builtin(自研 agent loop)与 codex(CLI 子进程封装 + MCP 主动取证),引擎选型由基准集 A/B 数据裁决。

文档

  • docs/architecture.md — 架构全貌:技术选型决策、两层审查、修复链路、指纹状态机、Triage、Incident、数据飞轮、扩展槽口
  • docs/deployment.md — 生产部署 checklist:组件清单、环境变量、GitLab 权限模型、备份、资源估算
  • docs/roadmap.md — 路线图 v3:定位、v0.1–v0.3 发布节奏、验收标准、九条安全红线
  • docs/adr/ — 架构决策记录:Triage 前置闸、红→绿门禁、no-self-merge、不做向量 RAG、引擎基准集裁决、量化行为而非方向
  • examples/demo-service/kibana-alert-setup.md — Kibana Alerting webhook 配置手册

路线图

已完成:一期自动修复全链路

  • 触发 / 去重 / 分诊:Kibana Alerting 接入 → 指纹状态机去重 → Triage 四分类前置闸(传导型错误永不进 pipeline)
  • 修复 / 验证 / 提审:Docker 沙箱红→绿自验证(复现测试 + 相关模块测试)→ GitLab MR + CI 回读;验证不过降级为带完整诊断报告的 Issue
  • 通知与控制台:飞书 + 邮件通知(冷却合并);React 控制台(指纹工作台 / 运行记录 / Incident 时间线 / 统计面板)
  • Incident 级联处置:跨服务告警聚合、源头候选、合并通知
  • 插件体系(五槽口):Stack / Notifier / SandboxBackend / ModelProvider / FixEngine,entry-points 可插拔
  • 双修复引擎 + 基准集:builtin + codex(MCP 主动取证);mutation 6 例 + 真实开源 bug 3 例 + 三引擎对打表(benchmarks/)

v0.2:进行中

  • 持久化任务队列:租约 + SELECT ... FOR UPDATE SKIP LOCKED + 死信人工重放——任务不丢、不双跑
  • 可观测性:/metrics Prometheus 出口,系统状态从黑盒变成面板
  • 指标埋点:修复率 / 噪音率自动计算(含 target_invalidated 标签)
  • 大库修复能力提升:基于对打失败分析的轮次预算与收尾机制

远期(v0.3+)

  • 更多引擎 adapter:Claude Code / Aider / OpenHands spike,A/B 对打数据裁决主力引擎
  • K8s SandboxBackend 生产形态:KubernetesBackend(Job + ResourceQuota),沙箱隔离扩项(pids / cap_drop / 非 root)
  • MR 自动审查(二期):review-service、SpotBugs/PMD 确定性分析层 + LLM 审查,输出带严重等级的 MR 评论
  • 反馈中心:审查裁决与 MR 结果回读 Feedback,结构化 few-shot 注入,数据飞轮滚动

License

MIT

About

An ELK-alert-driven platform that automatically fixes production bugs: a Kibana alert comes in, an agent reproduces, fixes, and self-verifies the bug inside a Docker sandbox, then opens a GitLab merge request — through exactly the same review process as a human.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages