# AIBugAnalyzer

**Repository Path**: test-dev-qa/aibug-analyzer

## Basic Information

- **Project Name**: AIBugAnalyzer
- **Description**: AI Bug Analyzer — 本地部署的 AI 测试分析与 Bug 管理工具

测试提单，AI 自动定位根因，研发修复回写，测试回归关闭——一个由 Claude Code CLI 驱动的 Bug 全生命周期闭环系统。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Bug Analyzer — AI 测试分析与 Bug 管理工具

Node 全栈项目，本地部署，接入 Claude Code CLI 实现 AI 驱动的 Bug 分析。

## 技术栈

| 层 | 技术 |
|---|---|
| 后端 | NestJS + Prisma + SQLite |
| 前端 | React + Vite + Tailwind CSS + Zustand |
| AI 引擎 | Claude Code CLI（通过后端队列调度） |
| 日志存储 | Elasticsearch + Kibana + ELK MCP Server |
| 包管理 | pnpm (monorepo) |
| 容器化 | Docker Compose（ES + Kibana + ELK MCP） |

## 前置条件

在新机器上部署前，确保已安装：

- **Node.js** >= 20
- **pnpm** >= 11.3.0（`corepack enable && corepack prepare pnpm@11.3.0 --activate`）
- **Docker** + Docker Compose（用于 Elasticsearch / Kibana / ELK MCP）
- **Claude Code CLI**（`npm install -g @anthropic-ai/claude-code`，需有 Anthropic API Key）
- **Git**

## 快速部署（新机器）

### 1. 克隆仓库

```bash
git clone https://gitee.com/yjj_1012/aibug.git
cd aibug
```

### 2. 配置环境变量

项目需要配置以下 `.env` 文件：

**根目录 `.env`**（从 `.env.example` 复制）：

```bash
cp .env.example .env
```

编辑 `.env`，**必须修改**以下配置：

```env
# JWT —— 务必改为自己的随机密钥
JWT_SECRET=改成你自己的长随机字符串
JWT_EXPIRES_IN=12h

# Claude Code CLI
CLAUDE_CLI_PATH=claude          # claude 可执行文件路径
CLAUDE_MODEL=                   # 模型（留空用 CLI 默认）
CLAUDE_TIMEOUT_SEC=600          # 单任务超时
CLAUDE_MAX_CONCURRENCY=1        # 最大并发
CLAUDE_MAX_RETRY=1              # 失败重试次数
```

**`apps/elk-mcp/.env`**（从 `.env.example` 复制）：

```bash
cp apps/elk-mcp/.env.example apps/elk-mcp/.env
```

**`apps/web/.env`** — 默认指向 `http://localhost:5601`（Kibana），一般无需修改。

> ⚠️ `.env` 文件已在 `.gitignore` 中排除，不会提交到仓库。

### 3. 启动依赖服务（Docker）

```bash
docker compose up -d
```

这会启动三个容器：

| 容器 | 端口 | 说明 |
|---|---|---|
| `aba-es` | 9200 | Elasticsearch — 日志存储 |
| `aba-kibana` | 5601 | Kibana — 日志可视化 |
| `aba-elk-mcp` | 9201 | ELK MCP Server — Claude Code ↔ ES 桥梁 |

验证服务状态：

```bash
docker compose ps           # 确认三个容器都是 Up
curl http://localhost:9200  # ES 应返回 "You Know, for Search"
curl http://localhost:9201/health  # MCP Server 健康检查
```

### 4. 安装项目依赖

```bash
pnpm install
```

### 5. 初始化数据库

```bash
# 生成 Prisma Client
pnpm -C apps/server db:generate

# 执行数据库迁移（创建表结构）
pnpm -C apps/server db:migrate

# 或直接用 db push（跳过迁移文件）
pnpm -C apps/server db:push

# 创建初始管理员账号
pnpm -C apps/server db:seed
```

默认管理员：`admin` / `admin123`（可在 `.env` 中通过 `SEED_ADMIN_USERNAME` / `SEED_ADMIN_PASSWORD` 修改）。

### 6. 启动应用

```bash
# 开发模式（前后端同时启动）
pnpm dev

# 或分别启动
pnpm -C apps/server dev    # 后端 → http://localhost:3000/api
pnpm -C apps/web dev       # 前端 → http://localhost:5173
```

访问 `http://localhost:5173`，用管理员账号登录即可使用。

### 7. 配置 Claude Code 的 MCP 服务器（可选，用于日志查询）

如果需要在 Claude Code 中直接查询 Elasticsearch 日志，在项目根目录创建 `.claude/settings.local.json`：

```json
{
  "mcpServers": {
    "elk-mcp": {
      "type": "http",
      "url": "http://localhost:9201/mcp"
    }
  }
}
```

创建命令：

```bash
mkdir -p .claude
cat > .claude/settings.local.json << 'EOF'
{
  "mcpServers": {
    "elk-mcp": {
      "type": "http",
      "url": "http://localhost:9201/mcp"
    }
  }
}
EOF
```

## 项目结构

```
aibug/
├── apps/
│   ├── server/          # NestJS 后端（API / 认证 / Bug 管理 / AI 任务队列）
│   │   ├── prisma/      # 数据模型 + SQLite 数据库
│   │   └── src/
│   │       └── common/trace/  # Trace ID 链路追踪（W3C 标准）
│   ├── web/             # React 前端
│   └── elk-mcp/         # ELK MCP Server（Elasticsearch ↔ Claude Code 桥梁）
├── data/                # 运行期数据（SQLite、附件、分析报告、日志等，不入库）
├── docs/                # 设计文档 + Trace ID 规范
├── docker-compose.yml   # ES + Kibana + ELK MCP 容器编排
├── .env.example         # 环境变量模板
└── CLAUDE.md            # 项目规范（Claude Code 自动加载）
```

## 常用命令

```bash
pnpm dev                  # 启动开发模式（前后端）
pnpm build                # 构建前后端
pnpm -C apps/server db:push        # 数据库 schema 同步
pnpm -C apps/server db:seed        # 重置管理员
pnpm -C apps/server backup         # 备份数据
docker compose up -d      # 启动依赖服务
docker compose down       # 停止依赖服务
docker compose logs -f    # 查看服务日志
```

## Trace ID 规范

本项目遵循 W3C Trace Context 标准，所有 HTTP 接口返回 `X-Trace-Id` 响应头。详见 [`docs/trace-id-spec.md`](docs/trace-id-spec.md) 和 [`CLAUDE.md`](CLAUDE.md)。