# tianshu-ai

**Repository Path**: magic_yuan_admin/tianshu-ai

## Basic Information

- **Project Name**: tianshu-ai
- **Description**: 天枢AI知识库管理平台 - 基于Spring Boot和Vue3的企业级知识库系统
- **Primary Language**: Java
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2025-12-03
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 天枢AI应用平台

<p align="center">
  <img src="https://img.shields.io/badge/Spring%20Boot-3.2.0-brightgreen.svg" alt="Spring Boot">
  <img src="https://img.shields.io/badge/Vue-3.4-blue.svg" alt="Vue">
  <img src="https://img.shields.io/badge/JDK-17+-orange.svg" alt="JDK">
  <img src="https://img.shields.io/badge/License-Apache%202.0-green.svg" alt="License">
  <img src="https://img.shields.io/badge/LangChain4j-1.9.0-purple.svg" alt="LangChain4j">
  <img src="https://img.shields.io/badge/Milvus-2.6.5-red.svg" alt="Milvus">
</p>

天枢AI应用平台是一个**企业级智能知识库管理系统**，集成了先进的AI技术，提供文档智能解析、向量化存储、混合检索等核心能力。

### ✨ 主要亮点

- 🚀 **开箱即用**：Docker Compose 一键部署，包含所有依赖服务
- 🤖 **AI 驱动**：集成 LangChain4j，支持多种 AI 模型提供商
- 📚 **智能解析**：集成 MinerU Tianshu，高精度 PDF/Office 转 Markdown
- 🔍 **混合检索**：向量检索 + BM25 全文检索 + RRF 重排序
- 🎯 **灵活配置**：支持多种向量数据库和对象存储
- 🔐 **企业级**：完整的权限管理、审计日志、API Key 认证
- 🌐 **Dify 兼容**：提供 Dify 兼容的检索 API

## 目录

- [快速开始](#快速开始)
- [系统架构](#系统架构)
- [核心特性](#核心特性)
- [技术栈](#技术栈)
- [功能模块](#功能模块)
- [项目结构](#项目结构)
- [数据库设计](#数据库设计)
- [使用指南](#使用指南)
- [常见问题](#常见问题)
- [致谢](#致谢)
- [联系方式](#联系方式)

## 快速开始

### 前置要求

- Docker 20.10+
- Docker Compose 2.0+
- 至少 8GB 可用内存
- 至少 20GB 可用磁盘空间

### 一键部署

#### 方式一：使用启动脚本（推荐）

**开发环境快速启动：**

Windows 用户：
```bash
scripts\start.bat
```

Linux/Mac 用户：
```bash
chmod +x scripts/start.sh
./scripts/start.sh
```

**生产环境部署：**

Windows 用户：
```bash
# 1. 配置环境变量
copy .env.production.example .env
# 编辑 .env 文件，修改所有密码和密钥

# 2. 运行生产部署脚本
scripts\deploy-production.bat
```

Linux/Mac 用户：
```bash
# 1. 配置环境变量
cp .env.production.example .env
vim .env  # 修改所有密码和密钥

# 2. 运行生产部署脚本
chmod +x scripts/deploy-production.sh
./scripts/deploy-production.sh
```

生产部署脚本特性：
- ✅ 强制安全检查（禁止默认密码）
- ✅ 自动备份现有数据
- ✅ 拉取最新镜像
- ✅ 重新构建应用
- ✅ 健康检查和验证
- ✅ 详细的部署报告

#### 方式二：手动部署

1. **克隆项目**

```bash
git clone https://github.com/magicyuan876/tianshu-ai.git
cd tianshu-ai
```

2. **配置环境变量**

```bash
# 开发环境（使用默认配置）
cp .env.example .env

# 生产环境（需要修改密码和密钥）
cp .env.production.example .env
# 然后编辑 .env 文件，修改所有密码和密钥
```

**重要配置项说明：**

```bash
# 数据库配置
POSTGRES_DB=tianshu_ai              # 数据库名称
POSTGRES_USER=postgres              # 数据库用户名
POSTGRES_PASSWORD=postgres123       # 数据库密码（生产环境必须修改）

# Redis 配置
REDIS_PASSWORD=redis123             # Redis 密码（生产环境必须修改）

# MinIO 配置
MINIO_ROOT_USER=minioadmin          # MinIO 用户名
MINIO_ROOT_PASSWORD=minioadmin123   # MinIO 密码（生产环境必须修改）

# 安全配置（生产环境必须修改）
JWT_SECRET_KEY=your_jwt_secret_key
ENCRYPTION_KEY=your_encryption_key

# 端口配置（如有冲突可修改）
POSTGRES_PORT=5432
REDIS_PORT=6379
MINIO_API_PORT=9000
MINIO_CONSOLE_PORT=9001
BACKEND_PORT=8080
FRONTEND_PORT=80
```

> ⚠️ **生产环境安全提示**：
> - 必须修改所有默认密码
> - 使用强随机密钥（至少 32 位）
> - 生成密钥命令：`openssl rand -base64 64`

3. **启动所有服务**

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

首次启动需要下载镜像，约 5-10 分钟。等待服务启动完成（约 1-2 分钟）后访问：

- **前端应用**: http://localhost:80
- **后端 API 文档**: http://localhost:8080/doc.html
- **MinIO 控制台**: http://localhost:9001

4. **默认管理员账号**

- 用户名: `admin`
- 密码: `admin123`

> ⚠️ 请在首次登录后立即修改默认密码！

### 详细部署文档

完整的部署指南请参考：[DEPLOYMENT.md](DEPLOYMENT.md)

包含：
- 详细配置说明
- 生产环境部署指南
- 常见问题解决方案
- 备份和恢复方案
- 性能优化建议

### 快速使用流程

1. **登录系统**：使用默认账号登录
2. **配置 AI 模型**：系统设置 > AI 模型配置（配置嵌入模型）
3. **配置向量数据库**：系统设置 > 向量数据库配置（默认使用 Milvus）
4. **创建知识库**：知识库管理 > 新建知识库
5. **上传文档**：进入知识库 > 上传文档（支持 PDF、Word、Markdown 等）
6. **检索测试**：进入知识库 > 检索测试（测试检索效果）

## 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         前端应用 (Vue 3)                          │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────────┐   │
│  │知识库管理│文档管理  │检索测试  │系统配置  │用户权限管理  │   │
│  └──────────┴──────────┴──────────┴──────────┴──────────────┘   │
└────────────────────────────┬────────────────────────────────────┘
                             │ HTTP/REST API
┌────────────────────────────┴────────────────────────────────────┐
│                    后端应用 (Spring Boot)                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              业务层 (Service Layer)                       │   │
│  │  ┌─────────┬─────────┬─────────┬─────────┬──────────┐   │   │
│  │  │知识库服务│文档服务 │检索服务 │AI配置   │权限服务  │   │   │
│  │  └─────────┴─────────┴─────────┴─────────┴──────────┘   │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              数据访问层 (MyBatis Plus)                    │   │
│  └──────────────────────────────────────────────────────────┘   │
└────────┬──────────┬──────────┬──────────┬──────────┬───────────┘
         │          │          │          │          │
    ┌────▼───┐ ┌───▼────┐ ┌───▼────┐ ┌──▼─────┐ ┌─▼────────┐
    │PostgreSQL Redis  │ │ MinIO  │ │ Milvus │ │AI 模型   │
    │  数据库  │ 缓存   │ │对象存储│ │向量数据库│ │(OpenAI等)│
    └─────────┘ └────────┘ └────────┘ └────────┘ └──────────┘
                                         │
                                    ┌────▼────┐
                                    │  Etcd   │
                                    │服务发现 │
                                    └─────────┘
```

### 核心流程

#### 文档处理流程
```
1. 用户上传文档
   ↓
2. 上传到对象存储 (MinIO/OSS/S3)
   ↓
3. 创建异步处理任务
   ↓
4. 文档解析 (MinerU Tianshu / LangChain4j)
   ↓
5. 文本分块 (根据配置的策略)
   ↓
6. 向量化 (调用嵌入模型)
   ↓
7. 存储到向量数据库 (Milvus/Qdrant/PGVector)
   ↓
8. 更新文档状态和统计信息
```

#### 检索流程
```
1. 用户输入查询文本
   ↓
2. 文本向量化 (调用嵌入模型)
   ↓
3. 向量检索 / 混合检索
   ├─ 向量检索：在向量数据库中查找相似向量
   └─ 混合检索：向量检索 + BM25 全文检索 + RRF 重排序
   ↓
4. 返回相关文档片段
```

## 核心特性

### 🎯 知识库管理
- **多租户支持**：支持组织、角色、权限的细粒度管理
- **知识库分类**：支持分类管理，便于组织和检索
- **可见性控制**：支持私有、组织内、公开三种可见性级别
- **成员协作**：支持知识库成员管理，包含所有者、管理员、编辑者、查看者角色

### 📄 文档处理
- **智能解析**：集成 [MinerU Tianshu](https://github.com/magicyuan876/mineru-tianshu) 文档解析服务，支持高精度 PDF/Office 转 Markdown
- **多格式支持**：支持 PDF、Word、Excel、PowerPoint、Markdown、纯文本等格式
- **自动分块**：支持多种分割策略（段落、句子、字符、递归），可配置分块大小和重叠
- **异步处理**：大文件异步处理，支持任务状态跟踪和错误恢复
- **向量化存储**：自动将文档内容向量化并存储到向量数据库

### 🔍 智能检索
- **混合检索**：支持向量检索、全文检索、混合检索（BM25 + 向量）
- **多种重排序算法**：支持 RRF（倒数排名融合）、加权融合等重排序策略
- **灵活配置**：可配置 Top K、相似度阈值、重排序权重等参数
- **Dify 集成**：提供 Dify 兼容的检索 API，支持 API Key 认证

### 🤖 AI 模型集成
- **多提供商支持**：
  - OpenAI（及兼容 API）
  - Ollama（本地部署）
  - Xinference（企业级推理平台）
  - Azure OpenAI
- **灵活配置**：支持嵌入模型和对话模型独立配置
- **模型测试**：内置模型连接测试功能

### 💾 向量数据库
- **多数据库支持**：
  - Milvus（推荐，支持混合检索）
  - Qdrant
  - PGVector
  - Elasticsearch
  - Redis
- **自动集合管理**：自动创建和管理向量集合
- **连接测试**：支持数据库连接测试

### 🔐 安全与审计
- **认证授权**：基于 Sa-Token 的权限认证框架
- **API Key 管理**：支持用户级 API Key，用于外部系统集成
- **审计日志**：完整的操作审计日志记录
- **数据加密**：敏感配置信息加密存储

### 🎨 现代化前端
- **响应式设计**：基于 Element Plus 的现代化 UI
- **实时反馈**：文档处理进度实时更新
- **便捷操作**：拖拽上传、批量操作、快速检索
- **可视化配置**：所有系统配置均可通过 Web 界面管理

## 技术栈

### 后端技术
- **核心框架**: Spring Boot 3.2.0 + JDK 17
- **数据库**: PostgreSQL 15（主数据库）
- **缓存**: Redis 7（会话缓存、分布式锁）
- **ORM**: MyBatis Plus 3.5.7
- **认证授权**: Sa-Token 1.37.0
- **对象存储**: MinIO / 阿里云 OSS / AWS S3（多存储支持）
- **向量数据库**: Milvus 2.6.5 / Qdrant / PGVector / Elasticsearch / Redis
- **AI 框架**: LangChain4j 1.9.0（嵌入、分块、检索）
- **文档解析**: MinerU Tianshu / Apache PDFBox
- **API 文档**: Knife4j 4.4.0（OpenAPI 3.0）
- **工具库**: Hutool 5.8.24

### 前端技术
- **核心框架**: Vue 3.4 + TypeScript 5.3
- **构建工具**: Vite 5.0
- **UI 组件**: Element Plus 2.5
- **状态管理**: Pinia 2.1
- **路由**: Vue Router 4.2
- **HTTP 客户端**: Axios 1.6
- **样式**: Sass

### 基础设施
- **容器化**: Docker + Docker Compose
- **Web 服务器**: Nginx（前端）
- **服务发现**: Etcd（Milvus 依赖）
- **健康检查**: Spring Boot Actuator

## 功能模块

### ✅ 用户与权限管理
- **用户管理**：用户增删改查、状态管理、密码重置
- **组织管理**：树形组织结构、成员管理
- **角色管理**：角色定义、权限分配
- **菜单管理**：动态菜单配置、权限控制
- **审计日志**：完整的操作日志记录和查询

### ✅ 知识库管理
- **知识库 CRUD**：创建、编辑、删除、查询知识库
- **分类管理**：知识库分类体系
- **成员管理**：知识库成员和权限管理
- **文档管理**：文档上传、解析、向量化、删除
- **检索测试**：支持多种检索方式的在线测试

### ✅ 系统配置
- **对象存储配置**：MinIO / 阿里云 OSS / AWS S3
- **向量数据库配置**：Milvus / Qdrant / PGVector 等
- **AI 模型配置**：嵌入模型和对话模型配置
- **文档解析配置**：MinerU Tianshu 服务配置
- **系统参数配置**：文件大小限制、分块参数等

### ✅ 外部集成
- **Dify 集成**：提供 Dify 兼容的检索 API
- **API Key 管理**：用户级 API Key 生成和管理

## 项目结构

```
tianshu-ai/
├── backend/                           # 后端应用
│   ├── src/main/
│   │   ├── java/ai/tianshu/platform/
│   │   │   ├── common/                # 通用基础类
│   │   │   ├── config/                # 配置类
│   │   │   ├── exception/             # 异常处理
│   │   │   ├── langchain4j/           # LangChain4j 集成
│   │   │   ├── module/                # 业务模块
│   │   │   │   ├── aiconfig/          # AI 模型配置模块
│   │   │   │   ├── kb/                # 知识库模块
│   │   │   │   └── system/            # 系统管理模块
│   │   │   ├── parse/                 # 文档解析
│   │   │   ├── storage/               # 对象存储
│   │   │   ├── task/                  # 异步任务
│   │   │   └── TianshuAiApplication.java    # 启动类
│   │   └── resources/
│   │       ├── application.yml        # 应用配置
│   │       ├── db/                    # 数据库脚本
│   │       └── mapper/                # MyBatis XML 映射文件
│   ├── Dockerfile                     # Docker 镜像构建文件
│   └── pom.xml                        # Maven 配置
├── frontend/                          # 前端应用
│   ├── src/
│   │   ├── api/                       # API 接口
│   │   ├── components/                # 公共组件
│   │   ├── router/                    # 路由配置
│   │   ├── stores/                    # 状态管理
│   │   ├── utils/                     # 工具函数
│   │   ├── views/                     # 页面组件
│   │   ├── App.vue                    # 根组件
│   │   └── main.ts                    # 入口文件
│   ├── Dockerfile                     # Docker 镜像构建文件
│   ├── nginx.conf                     # Nginx 配置
│   ├── package.json                   # NPM 配置
│   └── vite.config.ts                 # Vite 配置
├── docker-compose.yml                 # Docker Compose 编排文件
├── .env.example                       # 环境变量示例
└── README.md                          # 项目说明
```

## 数据库设计

详见 [数据库初始化说明](backend/src/main/resources/db/README_INIT.md)

### 核心数据表

#### 系统管理
- `sys_user` - 用户表
- `sys_user_api_key` - 用户 API Key 表
- `sys_organization` - 组织表
- `sys_role` - 角色表
- `sys_menu` - 菜单表
- `sys_permission` - 权限表
- `sys_audit_log` - 审计日志表
- `sys_config` - 系统配置表

#### 知识库管理
- `kb_category` - 知识库分类表
- `kb_knowledge_base` - 知识库表
- `kb_member` - 知识库成员表
- `kb_document` - 文档表
- `kb_async_task` - 异步任务表

## 使用指南

### 1. 配置 AI 模型

登录系统后，进入 **系统设置 > AI 模型配置**：

1. **配置嵌入模型**（用于文档向量化）
   - 选择提供商：OpenAI / Ollama / Xinference
   - 填写 API 地址和密钥
   - 选择模型（如 text-embedding-3-small）
   - 设置向量维度（如 1536）

2. **配置对话模型**（用于智能问答，可选）
   - 选择提供商和模型
   - 设置温度、最大令牌数等参数

3. **测试连接**
   - 点击"测试连接"按钮验证配置

### 2. 配置向量数据库

进入 **系统设置 > 向量数据库配置**：

1. 选择数据库类型（推荐 Milvus）
2. 填写连接信息（地址、端口、凭证）
3. 测试连接

### 3. 配置文档解析服务（可选）

进入 **系统设置 > 文档解析配置**：

1. 部署 [MinerU Tianshu](https://github.com/magicyuan876/mineru-tianshu) 服务
2. 填写服务地址
3. 启用服务

> 如不配置，系统将使用内置的 LangChain4j 解析器（仅支持 PDF 和纯文本）

### 4. 创建知识库

1. 进入 **知识库管理**
2. 点击"新建知识库"
3. 填写知识库信息：
   - 名称、描述、图标
   - 选择分类
   - 设置可见性
   - 配置分块参数（可选）
4. 保存后系统自动创建向量集合

### 5. 上传文档

1. 进入知识库详情
2. 点击"上传文档"
3. 选择文件（支持拖拽）
4. 系统自动：
   - 上传到对象存储
   - 解析文档内容
   - 分块处理
   - 向量化
   - 存储到向量数据库

### 6. 检索测试

1. 进入知识库详情 > 检索测试
2. 输入查询文本
3. 选择检索方式：
   - 向量检索
   - 混合检索（推荐）
4. 设置参数（Top K、相似度阈值等）
5. 查看检索结果

### 7. 外部集成（Dify）

1. 进入 **个人中心 > API Key 管理**
2. 创建 API Key
3. 在 Dify 中配置知识库：
   - API 地址：`http://your-domain/api/dify/retrieval`
   - API Key：刚创建的 Key
   - 知识库 ID：从知识库列表获取

## 常见问题

### 1. Docker 启动失败？

**检查端口占用：**
```bash
# Windows
netstat -ano | findstr "80\|8080\|5432\|6379\|9000\|19530"

# Linux/Mac
lsof -i :80,8080,5432,6379,9000,19530
```

**查看容器日志：**
```bash
docker-compose logs -f tianshu-ai-backend
docker-compose logs -f tianshu-ai-milvus
```

### 2. Milvus 启动失败？

**常见原因：**
- Etcd 未正常启动（检查 `docker-compose logs tianshu-ai-etcd`）
- MinIO 连接失败（检查 MinIO 凭证是否一致）
- 内存不足（Milvus 建议至少 4GB 内存）

**解决方案：**
```bash
# 重启相关服务
docker-compose restart tianshu-ai-etcd
docker-compose restart tianshu-ai-minio
docker-compose restart tianshu-ai-milvus
```

### 3. 文档上传后处理失败？

**检查清单：**
1. AI 模型配置是否正确（系统设置 > AI 模型配置 > 测试连接）
2. 向量数据库配置是否正确（系统设置 > 向量数据库配置 > 测试连接）
3. 对象存储配置是否正确（系统设置 > 对象存储配置）
4. 查看异步任务表（`kb_async_task`）的错误信息
5. 查看后端日志：`docker-compose logs -f tianshu-ai-backend`

### 4. 如何重置数据库？

```bash
# 停止所有服务并删除数据卷
docker-compose down -v

# 重新启动（会自动初始化数据库）
docker-compose up -d
```

### 5. 如何修改管理员密码？

**方法一：通过 Web 界面**
1. 使用 admin/admin123 登录
2. 进入个人中心 > 修改密码

**方法二：通过数据库**
```sql
-- 密码使用 MD5 加密
-- 新密码：newpassword123
UPDATE sys_user 
SET password = MD5('newpassword123') 
WHERE username = 'admin';
```

### 6. 如何备份数据？

**备份数据库：**
```bash
docker exec tianshu-ai-postgres pg_dump -U postgres tianshu_ai > backup.sql
```

**备份对象存储：**
```bash
docker cp tianshu-ai-minio:/data ./minio-backup
```

**备份向量数据库：**
```bash
docker cp tianshu-ai-milvus:/var/lib/milvus ./milvus-backup
```

### 7. 向量检索结果不理想？

**优化建议：**
1. 调整分块参数（chunk_size、chunk_overlap）
2. 使用混合检索而非纯向量检索
3. 调整 Top K 和相似度阈值
4. 使用更好的嵌入模型（如 text-embedding-3-large）
5. 确保文档内容质量

## 许可证

Apache License 2.0

## 致谢

- [LangChain4j](https://github.com/langchain4j/langchain4j) - Java AI 应用框架
- [Milvus](https://milvus.io/) - 开源向量数据库
- [MinerU](https://github.com/opendatalab/MinerU) - 文档解析引擎
- [Element Plus](https://element-plus.org/) - Vue 3 UI 组件库

## 联系方式

- 作者：Magic_yuan
- 项目地址：https://github.com/magicyuan876/tianshu-ai
- 问题反馈：https://github.com/magicyuan876/tianshu-ai/issues
- MinerU Tianshu：https://github.com/magicyuan876/mineru-tianshu