██╗ ██╗ ██╗███████╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗
██║ ██║ ██║╚══███╔╝██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝
██║ ███████║ ███╔╝ ███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║
██║ ██╔══██║ ███╔╝ ██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║
███████╗██║ ██║███████╗██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║
╚══════╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝
刘海柱Agent——Java大模型应用开发项目学习使用
代号"刘海柱"的 AI 智能助手全栈项目，融合大模型对话、联网搜索、知识库检索（RAG）、MCP 工具调用等核心 AI 能力，提供赛博朋克风格的现代交互体验。
🌐 在线体验：https://ailhz.top
| 子项目 | 技术栈 | 说明 |
|---|---|---|
| liuhaizhu-backend | Spring Boot 3 + Spring AI + MyBatis Plus | AI 对话后端服务 |
| liuhaizhu-frontend | Vue 3 + Vite + Element Plus | 前端交互界面 |
┌──────────────────────────────────────────────────────────────────┐
│ Nginx (HTTPS + 反向代理) │
│ :80 / :443 │
└────────────┬─────────────────────────────────┬───────────────────┘
│ │
▼ ▼
┌────────────────────────┐ ┌───────────────────────────────────┐
│ Vue 3 Frontend │ │ Spring Boot Backend (:8000) │
│ 赛博朋克 UI │────▶│ ┌──────────┐ ┌─────────────┐ │
│ SSE 流式对话 │ SSE │ │ Chat │ │ RAG │ │
│ GSAP 动效 │◀────│ │ Service │ │ Service │ │
│ Pinia 状态管理 │ │ └────┬─────┘ └──────┬──────┘ │
└────────────────────────┘ │ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────┐ │
│ │ Spring AI 1.0.3 │ │
│ │ (DashScope / Qwen3-Max) │ │
│ └──────────┬───────────────┘ │
│ │ │
│ ┌──────────┴───────────┐ │
│ │ MCP Tools │ │
│ │ Date/Email/Product │ │
│ └──────────────────────┘ │
└───────────┬───────────────────────┘
│
┌──────────────────────┼──────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────────┐ ┌──────────┐
│ MySQL │ │ Redis Stack │ │ SearXNG │
│ 9.5+ │ │ (缓存+向量) │ │ 搜索引擎 │
└──────────┘ └──────────────┘ └──────────┘
- AI 智能对话：基于 Qwen3-Max 模型 + Spring AI，SSE 流式响应，数据库持久化的 7 轮对话历史上下文记忆
- 联网搜索：集成 SearXNG 搜索引擎，Query 改写优化搜索关键词，搜索结果注入 LLM 对话上下文
- 知识库检索（RAG）：Tika 文档解析 → 递归文本分割 → qwen-flash Query 改写 → Redis 向量存储 → 语义检索 → qwen3-rerank Cross-Encoder 重排序
- MCP 工具调用：内置 DateTool / EmailTool / ProductTool，支持外部 MCP Server（如高德地图）
- 用户系统：邮箱验证注册、JWT 双 Token 认证（Access 24h + Refresh 7d）、BCrypt 密码加密
- 权限控制：Spring Security + 自定义注解（
@RequirePermission）+ AOP 切面 - 高级特性：请求限流（Redis Lua）| 分布式锁 | 慢请求告警 | 会话数量控制 | Actuator 健康监控
- 流式对话：SSE 字符级实时流式输出，支持文本和文件两种输入方式
- 三种对话模式：普通对话 / 联网搜索 / 知识库检索，互斥切换
- 会话管理：多会话 CRUD，消息持久化，标题自定义编辑
- 用户系统：用户名/邮箱注册、JWT 自动刷新、个人信息管理、数据加密存储
- 管理后台：用户管理、知识库管理、Token 用量统计，路由守卫 + 权限指令双重保护
- 赛博朋克 UI：科幻粒子背景、故障文字特效、HUD 装饰、暗黑/明亮双主题
- 交互动效：GSAP 卡片抽出页面转场、Lenis 阻尼滚动、打字机效果
| 层级 | 技术 |
|---|---|
| 前端框架 | Vue 3 (Composition API) |
| 构建工具 | Vite 7 |
| 状态管理 | Pinia 3 |
| UI 组件 | Element Plus 2 |
| 动画 | GSAP 3 + Lenis 1 |
| 后端框架 | Spring Boot 3.5.8 |
| AI 框架 | Spring AI 1.0.3 + DashScope (Qwen3-Max) |
| ORM | MyBatis Plus 3.5.12 |
| 数据库 | MySQL 9.5+ |
| 缓存/向量 | Redis Stack |
| 搜索引擎 | SearXNG |
| 安全 | Spring Security + JWT (auth0) |
| 文件存储 | x-file-storage (MinIO / Aliyun OSS) |
| MCP 协议 | Spring AI MCP 1.0.3 |
| 容器化 | Docker + Docker Compose |
| CI/CD | Jenkins |
| Web 服务器 | Nginx (HTTPS + 反向代理) |
| 测试框架 | JUnit 5 + Mockito（后端） / Vitest + @vue/test-utils（前端） |
liuhaizhu-agent/
├── liuhaizhu-backend/ # Spring Boot 后端
│ ├── src/main/java/.../ # Java 源码
│ ├── src/main/resources/ # 配置 / SQL / 提示词
│ ├── Dockerfile # 后端镜像构建
│ ├── docker-compose.yml # 后端容器编排
│ ├── Jenkinsfile # 后端 CI/CD
│ └── pom.xml # Maven 配置
├── liuhaizhu-frontend/ # Vue 3 前端
│ ├── src/ # Vue 源码
│ ├── public/ # 静态资源
│ ├── Dockerfile # 前端镜像构建
│ ├── docker-compose.yml # 前端容器编排
│ ├── nginx.conf # Nginx 配置
│ └── Jenkinsfile # 前端 CI/CD
├── LICENSE # MIT License
└── README.md # 本文件
- 后端：JDK 17+ / Maven 3.9+ / MySQL 9.5+ / Redis Stack / SearXNG
- 前端：Node.js ^22.14.0 / Yarn 1.22+
cd liuhaizhu-backend
# 1. 配置环境变量
cp src/main/resources/.env-template .env
# 编辑 .env 填入实际配置（数据库、Redis、DashScope API Key 等）
# 2. 初始化数据库（执行 SQL 脚本）
# src/main/resources/sql/liuhaizhu.sql
# 3. 启动
./mvnw spring-boot:run后端默认运行在 http://localhost:8000。
cd liuhaizhu-frontend
# 安装依赖
yarn install
# 启动开发服务器
yarn dev前端默认运行在 http://localhost:5173，已配置反向代理到后端 8000 端口。
前后端均有独立的 docker-compose.yml，可按需分别部署：
# 部署后端
cd liuhaizhu-backend
# 编辑 docker-compose.yml 中的环境变量
docker-compose up -d --build
# 部署前端（含 Nginx HTTPS）
cd liuhaizhu-frontend
# 准备 SSL 证书到 ssl/ 目录，编辑 docker-compose.yml
docker-compose up -d --build系统首次启动时会自动创建默认管理员账户（用户名 admin，角色 ADMIN），密码请查看 DataInitializer.java 中的初始化逻辑，生产环境务必修改默认密码。
项目已完成全面的单元测试覆盖，共 442 项测试（229 后端 + 213 前端），0 失败。
| 模块 | 测试文件数 | 测试数 | 覆盖范围 |
|---|---|---|---|
| 后端工具类 | 6 | 69 | JwtUtil, AceResult, RateLimiterUtil, DistributedLockUtil, SSEServerUtil, RecursiveTextSplitter |
| 后端枚举/MCP | 4 | 37 | UserRoleEnum, DateTool, EmailTool, DocumentFormatConversion |
| 后端 Service | 6 | 103 | AuthService, AdminUserService, ConversationService, UserProfileService, PermissionService, CustomUserDetailsService |
| 后端安全 | 2 | 16 | CustomUserDetails, JwtAuthenticationFilter |
| 后端 MCP 工具 | 1 | 12 | ProductTool（枚举转换 + CRUD） |
| 前端 Utils | 3 | 74 | helpers, imageUtils, permission |
| 前端 Stores | 4 | 79 | auth, chat, settings, transition |
| 前端 Composable | 1 | 12 | useToast |
| 前端 指令/API | 2 | 18 | v-permission, auth API |
# 后端
cd liuhaizhu-backend
./mvnw test
# 前端
cd liuhaizhu-frontend
yarn test:unitCopyright (c) 2025 aceFelix
本项目基于 MIT 协议开源，任何人可免费学习、使用、修改和分发。