Skip to content

2001-zewei/YunZhi-Q-and-A-Troubleshooting-System

BranchesTags

Repository files navigation

SuperBizAgent

基于 Spring Boot + AI Agent 的智能问答与运维系统

License: MIT Java Spring Boot

📖 项目简介

企业级智能业务代理系统，包含两大核心模块：

1. RAG 智能问答

集成 Milvus 向量数据库和阿里云 DashScope，提供基于检索增强生成的智能问答能力，支持多轮对话和流式输出。

2. AIOps 智能运维

基于 AI Agent 的自动化运维系统，采用 Planner-Executor-Replanner 架构，实现告警分析、日志查询、智能诊断和报告生成。

🚀 核心特性

  • ✅ RAG 问答: 向量检索 + 多轮对话 + 流式输出
  • ✅ AIOps 运维: 智能诊断 + 多 Agent 协作 + 自动报告
  • ✅ 工具集成: 文档检索、告警查询、日志分析、时间工具
  • ✅ 会话管理: 上下文维护、历史管理、自动清理
  • ✅ Web 界面: 提供测试界面和 RESTful API
  • ✅ Mock 模式: 无需外部服务即可开发和测试

🛠️ 技术栈

技术 版本 说明
Java 17+ 开发语言
Spring Boot 3.2.0 应用框架
Spring AI 1.1.0 AI Agent 框架
DashScope 2.17.0 阿里云 AI 服务
Milvus 2.5.10 向量数据库
Docker 24+ 容器化运行（Milvus）
Node.js 18+ MCP Server 运行环境（可选）

📦 项目结构

SuperBizAgent/
├── src/main/java/org/example/
│   ├── controller/
│   │   ├── ChatController.java        # 统一对话接口控制器
│   │   ├── FileUploadController.java  # 文件上传接口
│   │   └── MilvusCheckController.java # 健康检查接口
│   ├── service/
│   │   ├── ChatService.java           # 对话服务（核心）
│   │   ├── AiOpsService.java          # AIOps 智能运维服务
│   │   ├── RagService.java            # RAG 检索增强生成服务
│   │   ├── VectorEmbeddingService.java # 向量嵌入服务
│   │   ├── VectorIndexService.java    # 向量索引服务
│   │   └── VectorSearchService.java   # 向量搜索服务
│   ├── agent/tool/
│   │   ├── DateTimeTools.java         # 时间工具
│   │   ├── InternalDocsTools.java     # 内部文档检索工具
│   │   ├── QueryMetricsTools.java     # Prometheus 告警查询工具
│   │   └── QueryLogsTools.java        # 日志查询工具（Mock模式）
│   └── config/                        # Spring 配置类
├── src/main/resources/
│   ├── static/                        # Web 前端界面
│   └── application.yml                # 应用主配置
├── aiops-docs/                        # AIOps 运维文档库
├── vector-database.yml                # Milvus Docker Compose 配置
├── Makefile                           # 自动化运维脚本
├── setup.sh                           # 一键部署脚本
├── .env.example                       # 环境变量配置模板
├── SECURITY.md                        # 安全策略说明
└── pom.xml                            # Maven 项目配置

🚀 快速开始（5 分钟部署）

前置要求

在开始之前，请确保您的系统已安装以下软件：

软件 最低版本 安装指南
Java JDK 17+ Adoptium
Maven 3.8+ Maven 官网
Docker 24+ Docker Desktop
Node.js（可选） 18+ Node.js 官网
Git 2.x+ Git 官网

验证安装：

java -version    # 应显示 17 或更高
mvn -version     # 应显示 3.8 或更高
docker -v        # 应显示 24 或更高
npx -v           # 可选：腾讯云日志查询功能需要

方式一：一键部署（推荐）

# 1. 克隆项目
git clone https://github.com/2001-zewei/SuperBizAgent.git
cd SuperBizAgent

# 2. 配置 API 密钥
cp .env.example .env
# 编辑 .env 文件，填入您的真实密钥（详见下方配置说明）
# Windows 用户: notepad .env
# Mac/Linux 用户: nano .env

# 3. 运行一键部署脚本
chmod +x setup.sh    # Linux/Mac 需要执行此步骤
./setup.sh           # Windows Git Bash 用户: bash setup.sh

部署脚本将自动完成：

  • ✅ 环境检查
  • ✅ 环境变量配置
  • ✅ Milvus 向量数据库启动
  • ✅ Spring Boot 应用构建与启动
  • ✅ 服务健康检查

方式二：手动部署

# 1. 克隆项目
git clone https://github.com/2001-zewei/SuperBizAgent.git
cd SuperBizAgent

步骤 1：配置 API 密钥

# 复制环境变量模板
cp .env.example .env

# 编辑 .env，填入您的密钥
# 必填项：
DASHSCOPE_API_KEY=sk-your-real-dashscope-api-key

# 可选项（不需要腾讯云日志查询可不填）：
TENCENTCLOUD_SECRET_ID=AKIDxxxxx
TENCENTCLOUD_SECRET_KEY=xxxxx

步骤 2：启动 Milvus 向量数据库

# 启动向量数据库（首次启动需要拉取 Docker 镜像，约 2-3 分钟）
docker compose -f vector-database.yml up -d

# 等待容器就绪
echo "等待 Milvus 启动..."
until curl -s -f http://localhost:9091/healthz > /dev/null 2>&1; do
    echo -n "."
    sleep 2
done
echo ""
echo "✅ Milvus 已就绪！"

步骤 3：构建并启动应用

# Maven 编译打包
mvn clean package -DskipTests

# 启动应用（后台运行）
nohup mvn spring-boot:run > server.log 2>&1 &
echo $! > server.pid

步骤 4：验证服务

# 等待启动完成（约 30 秒）
echo "等待服务启动..."
until curl -s -f http://localhost:9900/milvus/health > /dev/null 2>&1; do
    echo -n "."
    sleep 3
done
echo ""
echo "✅ 服务已启动！"

# 访问 Web 界面
echo "打开浏览器访问: http://localhost:9900"

方式三：使用 Make

# 复制环境变量并编辑
cp .env.example .env
# 编辑 .env 填入真实密钥

# 一键初始化（Docker → 服务 → 文档上传）
make init

# 或分步操作
make up       # 启动 Docker（Milvus）
make start    # 启动 Spring Boot 服务
make upload   # 上传运维文档到向量库

⚙️ 配置说明

必需配置

阿里云 DashScope API 密钥（必填）

这是 AI 对话和文本向量化功能所需的核心密钥。

  1. 访问 阿里云 DashScope 控制台
  2. 注册/登录阿里云账号
  3. 在控制台中创建 API Key
  4. 将密钥填入 .env 文件： 
    DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

可选配置

腾讯云 CLS 日志查询（可选）

如果需要使用腾讯云日志查询功能，需要配置腾讯云 API 密钥。

  1. 访问 腾讯云 API 密钥管理
  2. 创建或查看您的 SecretId 和 SecretKey
  3. 填入 .env 文件： 
    TENCENTCLOUD_SECRET_ID=AKIDxxxxxxxxxxxxxxxx
TENCENTCLOUD_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxx

💡 不需要腾讯云日志查询？ 可以在 src/main/resources/application.yml 中设置 cls.mock-enabled: true 来使用模拟数据。

不使用 MCP 日志查询

如果完全不需要 MCP 日志查询功能，注释掉 application.yml 中的 MCP 配置：

spring:
  ai:
    mcp:
      client:
        enabled: false  # 关闭 MCP 客户端

Mock 模式说明

系统支持 Mock 模式，在以下场景特别有用：

  • 开发和测试阶段，没有真实的外部服务
  • 演示和评估项目功能
  • CI/CD 流程中的自动化测试

启用 Mock 模式：

# 在 application.yml 中修改：
prometheus:
  mock-enabled: true    # 使用模拟告警数据

cls:
  mock-enabled: true    # 使用模拟日志数据

📡 API 接口文档

基础信息

  • Base URL: http://localhost:9900
  • Content-Type: application/json
  • 字符编码: UTF-8

1. 智能问答接口

流式对话（推荐）

POST /api/chat_stream
Content-Type: application/json

{
  "Id": "session-123",
  "Question": "什么是向量数据库？"
}

支持 SSE (Server-Sent Events) 流式输出，实时显示 AI 回复内容。 AI Agent 会自动调用工具（文档检索、告警查询等）并整合结果。

普通对话

POST /api/chat
Content-Type: application/json

{
  "Id": "session-123",
  "Question": "最近有哪些告警？"
}

一次性返回完整结果，包含工具调用过程。

2. AIOps 智能运维接口

POST /api/ai_ops

自动执行告警分析流程：

  1. 查询 Prometheus 告警
  2. 分析告警关联日志
  3. 智能诊断问题
  4. 生成运维报告（SSE 流式输出）

3. 会话管理

# 清空指定会话的历史记录
POST /api/chat/clear
Content-Type: application/json

{
  "sessionId": "session-123"
}

# 获取会话信息
GET /api/chat/session/{sessionId}

4. 文件管理

# 上传文件并自动向量化存储
POST /api/upload
Content-Type: multipart/form-data

file=@document.txt

支持的文件格式：.txt, .md

5. 健康检查

GET /milvus/health

返回 Milvus 向量数据库连接状态。

🐳 Docker 服务管理

# 启动向量数据库集群
docker compose -f vector-database.yml up -d

# 查看运行状态
docker compose -f vector-database.yml ps

# 查看日志
docker compose -f vector-database.yml logs -f

# 停止服务
docker compose -f vector-database.yml down

# 停止并清理数据
docker compose -f vector-database.yml down -v

Docker 服务说明：

服务 端口 说明
Milvus Standalone 19530 向量数据库主服务
Attu 8000 Milvus Web 管理界面
MinIO 9000, 9001 对象存储（Milvus 数据持久化）
etcd 2379 分布式配置存储

🔧 常用命令速查

# 查看应用日志
tail -f server.log

# 停止应用
kill $(cat server.pid)

# 重启应用
kill $(cat server.pid) && nohup mvn spring-boot:run > server.log 2>&1 & echo $! > server.pid

# 清理构建产物
mvn clean

# 上传文档到向量库
make upload

# 测试上传单个文件
make test-upload

# 查看 Docker 容器状态
make status

# 完整清理
make clean && make down

🖥️ Web 界面

启动应用后，打开浏览器访问：

http://localhost:9900

Web 界面提供以下功能：

  • 💬 智能问答对话
  • 📊 AIOps 运维诊断
  • 📁 文件上传与管理
  • 📈 服务状态监控

❓ 常见问题

Q: 启动时提示 "API Key 未设置"？

# 检查 .env 文件是否存在且配置正确
cat .env

# 如果不存在，从模板创建
cp .env.example .env
# 然后编辑 .env 填入真实密钥

Q: Milvus 无法连接？

# 检查 Docker 容器是否运行
docker compose -f vector-database.yml ps

# 如果未运行，启动服务
docker compose -f vector-database.yml up -d

# 等待约 30 秒后检查健康状态
curl http://localhost:9091/healthz

Q: Docker 启动失败？

# 检查 Docker 是否在运行
docker info

# Windows 用户请确保 Docker Desktop 已启动
# Linux 用户请确保当前用户在 docker 组中
sudo usermod -aG docker $USER
# 重新登录后生效

Q: 端口被占用？

# 查看占用端口的进程（Windows）
netstat -ano | findstr :9900
netstat -ano | findstr :19530

# Linux/Mac
lsof -i :9900
lsof -i :19530

Q: Maven 编译失败？

# 检查 Java 版本
java -version  # 需要 Java 17+

# 清理本地 Maven 缓存后重试
mvn clean install -U

Q: 如何在没有 API 密钥的情况下测试？

启用 Mock 模式（见上方配置说明），系统将使用模拟数据运行，无需任何外部 API 密钥。

🔒 安全提醒

  • 绝对不要将 .env 文件或包含真实密钥的配置文件提交到版本控制
  • 如果密钥意外泄露，请立即在对应云平台吊销并重新生成
  • 详细安全策略请参阅 SECURITY.md
  • 本项目 .gitignore 已配置忽略 .env 文件和敏感目录

📄 许可证

本项目基于 MIT 许可证开源。详见 LICENSE 文件。

版本: v1.0.0
作者: @2001-zewei
许可证: MIT

About

No description or website provided.

Topics

react mcp rag milvus muilt-agents springai-alibaba plan-execute

Resources

Readme

License

Apache-2.0 license

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages