hertz_studio_springboot/项目说明文档.md

Hertz 权限管理系统项目说明文档

1. 项目简介

Hertz 权限管理系统是一个基于前后端分离架构的轻量级权限管理平台。系统集成了用户管理、角色管理、菜单管理等核心功能，采用 RBAC（Role-Based Access Control）模型实现细粒度的权限控制。

1.1 项目结构

项目采用典型的多模块（或目录分离）结构：

• src/: 后端工程源码，基于 Spring Boot 3 + MyBatis-Plus。
• ui/: 前端工程源码，基于 Vue 3 + Vite + Element Plus。

2. 技术栈

2.1 后端技术栈 (hertz_springboot)

• 核心框架: Spring Boot 3.4.1
• 持久层框架: MyBatis-Plus 3.5.8
• 安全框架: Spring Security + JJWT 0.12.6 (实现无状态 JWT 认证)
• 数据库连接池: HikariCP (Spring Boot 默认)
• 数据库驱动: MySQL Connector/J
• 工具库: Lombok
• 运行环境: Java 21

2.2 前端技术栈 (hertz_springboot_ui)

• 核心框架: Vue 3.5.24
• 构建工具: Vite 7.2.4
• UI 组件库: Element Plus 2.13.1
• 状态管理: Pinia 3.0.4
• 路由管理: Vue Router 4.6.4
• HTTP 客户端: Axios 1.13.2

3. 功能模块

1. 认证模块: 支持用户登录、注册（可选）、JWT Token 颁发与验证。
2. 系统管理:
   • 用户管理: 用户的增删改查、分配角色、状态控制。
   • 角色管理: 角色的增删改查、分配菜单权限。
   • 菜单管理: 动态菜单配置，支持目录、菜单、按钮三种类型，支持权限标识配置。
3. 个人中心: 用户资料修改、密码修改、头像上传。
4. 监控模块:
   • 系统监控: 实时展示 CPU、内存、JVM、服务器信息、磁盘状态。
   • 监控日志: 记录系统运行时的性能指标。
5. AI 助手模块:
   • 智能对话: 集成 Spring AI (Ollama)，支持与 AI 助手进行智能对话。
   • 会话管理: 支持历史会话的持久化存储与查询。
   • 知识库 (RAG): 支持创建知识库、上传/管理文档、向量化检索增强回答。

4. 快速开始

4.1 环境准备

• JDK 21+
• Node.js 18+
• MySQL 8.0+

4.2 后端启动

1. 配置数据库：
   • 创建数据库 hertz_springboot。
   • 导入 db/init.sql 初始化基础表结构和数据（RBAC、AI 对话等）。
   • 额外导入以下脚本以启用监控与知识库功能：
     • src/main/resources/schema/monitor_schema.sql
     • src/main/resources/schema/knowledge_schema.sql
   • 修改 src/main/resources/application.yml 中的数据库连接信息（url, username, password）。
2. 运行项目：

   mvn spring-boot:run
   

   或者在 IDE 中运行 HertzApplication.java。 后端服务将启动在 http://localhost:8088。

4.4 AI（Ollama）准备

AI 助手与知识库（RAG）依赖 Ollama。首次启动前请确保已安装并运行 Ollama，并拉取所需模型：

1. 向量化模型（Embedding，用于知识库）：

   ollama pull nomic-embed-text
   

2. 聊天模型（用于对话，按配置决定，例如）：

   ollama pull deepseek-llm:7b
   

对应配置项位于 src/main/resources/application.yml：

• spring.ai.ollama.chat.model
• spring.ai.ollama.embedding.model

4.3 前端启动

1. 进入前端目录：

   cd ui
   

2. 安装依赖：

   npm install
   

3. 启动开发服务器：

   npm run dev
   

   前端服务通常启动在 http://localhost:5173。

5. 默认账号

角色	用户名	密码	权限
管理员	hertz	hertz	拥有所有系统权限
普通用户	demo	123456	仅拥有基本查看权限

6. 配置说明

6.1 后端配置 (application.yml)

• Server Port: 8088
• File Upload:
  • 最大文件大小: 2MB
  • 最大请求大小: 10MB
  • 上传根路径: ./uploads（项目根目录下的 uploads 目录）
  • 头像文件目录: ./uploads/avatar/yyyy/MM/
  • 知识库文件目录: ./uploads/knowledge/kb-{kbId}/yyyy/MM/
• Vector Store:
  • 向量库目录: ./uploads/vector_store/
  • 按知识库分别存储: vector-store-kb-{kbId}.json
• JWT:
  • 密钥: app.jwt.secret (建议在生产环境中修改为强随机字符串)
  • 过期时间: 86400秒 (24小时)

7. 注意事项

• 文件上传: 默认配置了本地文件存储路径，请确保该路径存在或有写入权限，或者在 application.yml 中修改为合适的路径。
• 跨域: 前端开发环境通常通过 Vite 代理解决跨域问题，生产环境需配置 Nginx 或后端 CORS。