# LogPilot

**Repository Path**: wangqin.tracker/log-pilot

## Basic Information

- **Project Name**: LogPilot
- **Description**: AI 原生 Java 错误诊断引擎 — 一个 Maven 依赖实现智能错误监控与自动分析
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="docs/logo.png" alt="LogPilot" width="120" />
</p>

<h1 align="center">LogPilot</h1>

<p align="center">
  <b>AI 原生 Java 错误诊断引擎</b><br/>
  一个 Maven 依赖，让你的 Spring Boot 应用拥有智能错误监控与自动诊断能力
</p>

<p align="center">
  <a href="#快速开始"><img src="https://img.shields.io/badge/快速开始-5分钟接入-brightgreen" alt="Quick Start"/></a>
  <a href="#ai-模型支持"><img src="https://img.shields.io/badge/AI-通义千问%20|%20DeepSeek%20|%20Kimi-blue" alt="AI Models"/></a>
  <a href="#webhook-告警"><img src="https://img.shields.io/badge/告警-钉钉%20|%20企微%20|%20飞书-orange" alt="Webhooks"/></a>
  <img src="https://img.shields.io/badge/Java-17+-green" alt="Java"/>
  <img src="https://img.shields.io/badge/Spring%20Boot-3.x-green" alt="Spring Boot"/>
</p>

---

## 为什么需要 LogPilot？

线上报错了，你还在做这些事吗？

- 登录服务器 → `tail -f` 翻日志 → 复制堆栈 → 粘贴到搜索引擎或 ChatGPT → 逐条排查
- 同一个 `NullPointerException` 一天报了 500 次，被淹没有意义的重复噪音里
- 新来的同事看不懂堆栈，每次都要找老员工帮忙分析

**LogPilot 帮你把这些事自动化了。** 它拦截应用中所有 ERROR 级别日志，用指纹算法自动聚合相同根因的错误，内置 32 条常见 Java 错误的诊断规则实现秒级本地分析，未命中的错误自动调用 AI 给出根因分析和修复建议，然后通过钉钉/企微/飞书把结果推到你的群里。

不需要 ELK，不需要 APM，不需要额外部署任何服务。

## 核心能力

**智能指纹引擎** — 不是简单的异常类名去重。LogPilot 解析堆栈找到最深层根因，过滤掉 16 类框架帧（Spring、MyBatis、Hikari 等），只保留业务代码帧并计算稳定哈希。同一个数据库超时在不同线程发生会被归为一类，同一个 NPE 出现在不同业务路径会被识别为不同错误。

**本地规则引擎** — 内置 32 条覆盖主流框架的错误诊断规则。SQL 异常、连接池耗尽、网络超时、NPE、OOM、Redis 连接失败、Sa-Token 鉴权异常等常见错误，本地毫秒级匹配，不调 AI，零 token 消耗。规则库支持 YAML 自定义扩展。

**AI 深度分析** — 规则未命中时，自动调用 AI 大模型进行深度分析。AI 不仅看到堆栈，还能看到当时的内存使用、线程数、HTTP 请求信息和 TraceId，给出的分析远比"手动复制堆栈问 ChatGPT"更精准。

**智能采样保护** — 三重防护避免 AI 调用失控：指纹级去重（相同错误冷却期内不重复分析）、每日预算上限（默认 100 次/天）、错误风暴熔断（60 秒内错误激增自动切换到仅记录模式）。

**多模型适配** — 统一适配器架构，支持通义千问、DeepSeek、Kimi、OpenAI 及任何 OpenAI 兼容 API。根据 API URL 自动识别提供商，换模型只需改配置不改代码。

**Webhook 告警** — 支持钉钉、企业微信、飞书三个通道的机器人告警，异步推送 Markdown 格式的诊断报告，包含错误分类、指纹、上下文、规则诊断和 AI 分析结果。

**运行时上下文采集** — 错误发生时自动采集 JVM 内存使用、活跃线程数、当前 HTTP 请求信息、SkyWalking/Micrometer TraceId，为 AI 分析提供完整的运行时快照。

## 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>org.dromara</groupId>
    <artifactId>ruoyi-common-errorlog</artifactId>
    <version>${revision}</version>
</dependency>
```

### 2. 执行建表 SQL

```sql
-- script/sql/sys_error_log.sql
```

### 3. 配置 Logback

在 `logback-plus.xml` 的 `<root>` 中添加：

```xml
<appender name="error_monitor" class="org.dromara.common.errorlog.appender.ErrorLogAppender">
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
        <level>ERROR</level>
    </filter>
</appender>

<root level="info">
    <!-- 你已有的 appender -->
    <appender-ref ref="error_monitor" />
</root>
```

### 4. 配置 AI（可选）

在 `application.yml` 中添加：

```yaml
error-log:
  ai:
    api-url: https://dashscope.aliyuncs.com/compatible-mode/v1/
    api-key: '你的API Key'
    model: qwen-turbo
```

> 不配置 AI 也能正常使用。本地规则引擎会处理常见错误，只是未命中的错误不会调用 AI 分析。

### 5. 配置告警（可选）

```yaml
error-log:
  webhook:
    dingtalk-webhook: 'https://oapi.dingtalk.com/robot/send?access_token=xxx'
    dingtalk-secret: 'SECxxx'   # 可选
```

完成。应用启动后，所有 ERROR 日志将自动被拦截、分析和通知。

## AI 模型支持

| 提供商 | API 地址 | 推荐模型 | 单次成本 |
|--------|---------|---------|---------|
| 通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1/` | qwen-turbo | ~0.003 元 |
| DeepSeek | `https://api.deepseek.com/v1/` | deepseek-chat | ~0.003 元 |
| Kimi | `https://api.moonshot.cn/v1/` | moonshot-v1-8k | ~0.008 元 |
| OpenAI | `https://api.openai.com/v1/` | gpt-3.5-turbo | ~0.009 元 |

> 支持任何兼容 OpenAI Chat Completions API 的服务。provider 留空时根据 URL 自动识别。

## Webhook 告警

| 通道 | 配置项 | 签名验证 |
|------|--------|---------|
| 钉钉 | `dingtalk-webhook` + `dingtalk-secret` | HmacSHA256 |
| 企业微信 | `wecom-webhook` | 无需签名 |
| 飞书 | `feishu-webhook` + `feishu-secret` | HmacSHA256 |

## 完整配置参考

```yaml
error-log:
  # 总开关
  enabled: true
  # 去重冷却时间（秒）
  deduplicate-seconds: 60
  
  ai:
    # provider: qwen          # 留空自动检测
    api-url: https://dashscope.aliyuncs.com/compatible-mode/v1/
    api-key: 'sk-xxx'
    model: qwen-turbo
    timeout: 30000
  
  sampler:
    max-daily: 100             # 每日 AI 调用上限
    storm-window-seconds: 60   # 风暴检测窗口
    storm-threshold: 50        # 窗口内错误数阈值
  
  webhook:
    dingtalk-webhook: ''
    dingtalk-secret: ''
    wecom-webhook: ''
    feishu-webhook: ''
    feishu-secret: ''
```

## REST API

模块启动后自动注册以下接口：

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/monitor/errorlog/list` | 分页查询（支持 status、category 过滤） |
| GET | `/monitor/errorlog/{id}` | 查看详情 |
| GET | `/monitor/errorlog/stats` | 运行统计（当日 AI 调用数等） |
| POST | `/monitor/errorlog/analyze/{id}` | 手动触发 AI 分析 |
| POST | `/monitor/errorlog/ignore/{id}` | 标记为已忽略 |
| DELETE | `/monitor/errorlog/{ids}` | 批量删除 |

## 架构设计

```
ERROR日志 → Logback Appender → Spring Event (异步)
    → 指纹引擎（根因提取 + 业务帧哈希 + 分类）
    → 智能采样（去重 / 预算 / 风暴熔断）
    → 规则引擎（32条内置规则，本地毫秒级诊断）
    → 上下文采集（内存 / 线程 / HTTP / TraceId）
    → AI 分析（仅规则未命中时调用，省 token）
    → 数据库持久化
    → Webhook 告警（钉钉 / 企微 / 飞书）
```

## 技术栈

- Java 17 + Spring Boot 3.x
- MyBatis-Plus（数据持久化）
- Logback（日志拦截）
- Hutool + Fastjson2（工具库）
- 兼容 OpenAI API 的任意大模型服务

## 参与贡献

欢迎提交 Issue 和 Pull Request。特别是：

- **错误规则贡献**：在 `rules/common-errors.yml` 中补充你遇到的错误模式和诊断经验
- **模型适配**：为非 OpenAI 兼容的模型 API 编写适配器
- **框架集成**：为更多 Java 框架提供开箱即用的 Starter

## License

[Apache License 2.0](LICENSE)