# knowledge-rag

**Repository Path**: strivingboy/knowledge-rag

## Basic Information

- **Project Name**: knowledge-rag
- **Description**: 基于论文系统的知识库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 论文知识库 Knowledge Base

> 基于 **Spring Boot 3 + Vue 3 (JS)** 的论文知识库系统。  
> AI 提供方：**MiniMax**（`https://api.minimaxi.com/anthropic`），使用 **Anthropic 协议** 接入。

## ✨ 功能特性

| 模块 | 能力 |
|------|------|
| 用户 | 注册 / 登录 / JWT 鉴权 |
| 仪表盘 | 首页聚合展示论文 / 笔记 / 对话 / 消息统计、近 30 天趋势、文件类型分布、高频引用论文 |
| 论文 | 上传 PDF → 自动解析、异步构建 RAG 索引、CRUD、关键字搜索、标签 |
| AI 总结 | MySQL 全文召回 + Embedding 重排后生成结构化摘要 |
| AI 对话 | 绑定论文后执行混合检索；普通 + **SSE 流式** 两种模式 |
| 知识卡片 | Markdown 卡片 CRUD，与论文可关联 |
| 文档 | Swagger UI 自动生成的 API 文档 |

## 🧱 技术栈

- **后端**：Spring Boot 3.5 / Java 17 / Spring Security 6 / JPA / Flyway / MySQL 8.4 / ONNX Runtime / DJL Tokenizers / WebClient / PDFBox 3
- **测试数据库**：H2，仅用于自动化测试，不进入运行时制品
- **前端**：Vue 3.5 / Vite 5 / Vue Router 4 / Pinia / Element Plus / Axios / marked + highlight.js
- **AI**：MiniMax（Anthropic 协议兼容）

## 📁 目录结构

```
knowledge-base/
├── backend/                  Spring Boot 后端
├── frontend/                 Vue 3 前端
├── docs/
│   └── ARCHITECTURE.md       架构设计
└── README.md
```

## 🚀 快速开始

### 方式 A：本地开发模式

#### 1. 准备本地 Embedding 模型

```powershell
cd backend
.\scripts\下载嵌入模型.ps1
```

脚本下载量化 `bge-small-zh-v1.5` ONNX 模型和 tokenizer 到 `backend/models/embedding/`。

#### 2. 启动后端

环境要求：JDK 17+。项目已包含 Maven Wrapper，不依赖全局 Maven 版本。

```powershell
cd backend
$env:SPRING_DATASOURCE_URL = "jdbc:mysql://localhost:3306/knowledge_base?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai"
$env:SPRING_DATASOURCE_USERNAME = "knowledge_base"
$env:SPRING_DATASOURCE_PASSWORD = "本地数据库密码"
$env:APP_JWT_SECRET = "至少32个字符的随机密钥"
$env:APP_AI_BASE_URL = "https://api.minimaxi.com/anthropic"
$env:APP_AI_API_KEY = "聊天模型API密钥"
.\mvnw.cmd spring-boot:run
```

服务启动后：

- REST API：`http://localhost:8080/api`
- Swagger UI：`http://localhost:8080/swagger-ui.html`

> 实际运行默认且仅使用 MySQL，Flyway 会自动迁移结构。H2 只保留在测试 classpath，并由 `test` profile 隔离使用。
> 如果本地调试时显式设置 `SPRING_PROFILES_ACTIVE=test`，后端会使用 H2；未设置时默认 profile 为 `mysql`。

#### 3. 启动前端

环境要求：Node 18+

```bash
cd frontend
npm install
npm run dev
```

打开 `http://localhost:5173`。

> Vite 已配置代理：所有 `/api/**` 请求转发到后端 `http://localhost:8080`。

#### 4. 注册并开始使用

1. 打开 `http://localhost:5173/register` 注册一个账号
2. 在「论文库」上传 PDF（≤ 25MB）
3. 进入论文详情，点击 **AI 总结** / **围绕此论文对话**
4. 登录后首页默认进入「仪表盘」，查看索引进度、上传趋势和高频引用论文
5. 在「知识卡片」中写笔记

### 方式 B：Docker Compose 一键启动

环境要求：Docker 24+、Docker Compose v2+

```bash
cp .env.example .env
# 编辑 .env，设置随机强密码、JWT Secret 和 AI Key
docker compose up -d --build
```

启动后：

- 前端：`http://localhost:5173`
- 后端：`http://localhost:8080`
- MySQL：`localhost:3306`（账号密码来自 `.env`）

停止：

```bash
docker compose down
```

清理数据（**慎用**）：

```bash
docker compose down -v
```

> `docker-compose.yml` 使用 MySQL 8.4，上传目录通过卷持久化，模型目录只读挂载。后端会在 MySQL、模型文件或必要 Secret 缺失时拒绝启动。

### 运行测试

后端：

```powershell
cd backend
.\mvnw.cmd clean test
```

当前后端基线为 Spring Boot 3.5.14、Flyway 12.8.1。普通测试执行 50 项，
MySQL 专项执行 6 项，均包含真实 ONNX CPU 推理。

MySQL 8.4 方案 A 专项验收：

```powershell
$env:MYSQL_IT_ADMIN_URL = "jdbc:mysql://127.0.0.1:3306/mysql?serverTimezone=Asia/Shanghai"
$env:MYSQL_IT_SERVER_URL = "jdbc:mysql://127.0.0.1:3306"
$env:MYSQL_IT_USERNAME = "具备创建临时数据库权限的测试账号"
$env:MYSQL_IT_PASSWORD = "测试账号密码"
.\backend\scripts\验证MySQL方案A.ps1
```

脚本会创建随机临时数据库并在结束后删除，覆盖全新迁移、旧库 baseline、ngram
中英文召回、并发任务领取、租约恢复，以及 MySQL + 真实 ONNX 的完整异步索引。

已覆盖：

- `JwtTokenProviderTest`：token 生成、解析、篡改检测
- `SseTextDeltaParserTest`：Anthropic SSE 文本增量解析（含换行/中文/无匹配）
- `PdfExtractorTest`：PDF 元数据/全文/异常路径
- `AnthropicModelsTest`：模型序列化与首段文本拼接
- `AuthControllerTest`：认证接口 `MockMvc` 测试，覆盖注册/登录响应包装、当前用户鉴权与 401 JSON 响应
- `ApplicationContextTest`：Flyway 迁移后 JPA `validate` 和完整上下文启动
- `EmbeddingProviderTest`：Provider 路由、兼容降级和向量编码
- `OpenAiCompatibleEmbeddingProviderTest`：远程批量协议和返回顺序
- `OnnxEmbeddingProviderTest`：BGE `[CLS]` pooling 和归一化
- `OnnxEmbeddingProviderIntegrationTest`：存在本地模型时执行真实 CPU 推理
- `RagIndexJobServiceTest`：幂等入队、租约领取、过期恢复和指数退避
- `RagIndexProcessorTest`：批量嵌入、模型元数据和二进制向量
- `HybridRetrievalServiceTest`：版本隔离、全文/向量融合排序
- `PaperControllerTest`：列表筛选、单文件上传、详情/全文/大纲/文件预览、索引状态、手工重建、更新、删除、总结
- `PaperControllerBatchTest`：批量上传与批量删除接口的 `MockMvc` 测试
- `NoteControllerTest`：笔记列表、按论文筛选、详情、创建、更新、删除的 `MockMvc` 测试
- `ChatControllerTest`：会话列表/创建/更新/删除、消息列表、普通发送、删除消息、SSE 流式的 `MockMvc` 测试
- `PaperServiceRagIntegrationTest`：上传异步入队、删除清理、AI 总结使用检索片段
- `ChatServiceRagIntegrationTest`：普通与流式对话按当前问题注入 RAG 论文上下文
- `MySqlSchemeAIntegrationTest`：MySQL 8.4 全新迁移、baseline、ngram 召回、并发领取、租约恢复和真实 ONNX 异步索引

## ⚙️ AI 配置说明

所有密钥通过环境变量注入，示例见 `.env.example`：

```yaml
app:
  ai:
    base-url: ${APP_AI_BASE_URL:}
    api-path: /v1/messages
    api-key: ${APP_AI_API_KEY:}
    anthropic-version: "2023-06-01"
    default-model: MiniMax-M2
    default-max-tokens: 4096
    default-system-prompt: |
      你是一名严谨的科研助手……
```

- 端点走 Anthropic `/v1/messages` 协议；
- 默认模型 `MiniMax-M3` 可替换为平台支持的其他模型；
- 生产配置不会提供默认 API Key、数据库密码或 JWT Secret。

### 链路日志与 AOP 调试

后端已内置基于 AOP 的调用链日志，默认开启，可用于排查请求从入口到 AI 客户端的完整链路：

- `RequestTraceFilter`：为每个请求生成或透传 `X-Trace-Id`，记录 `HTTP IN / HTTP OUT / HTTP ASYNC / HTTP COMPLETE`
- `TraceLoggingAspect`：记录 `controller / service / ai` 三层方法的入参、返回值、耗时和异常
- `JwtAuthenticationFilter`：在日志上下文中补充 `userId`
- `TraceLogFormatter`：对密码、token、secret、apiKey 等敏感字段做脱敏，并对长文本/大集合截断

可通过环境变量调节：

```powershell
$env:APP_TRACE_ENABLED = "true"
$env:APP_TRACE_MAX_STRING_LENGTH = "400"
$env:APP_TRACE_MAX_COLLECTION_ITEMS = "5"
```

典型日志关键字：

- `[HTTP IN]`：请求进入后端
- `[TRACE IN][controller]`：进入控制器
- `[TRACE IN][service]`：进入业务服务
- `[TRACE IN][ai]`：进入 AI 客户端
- `[TRACE OUT]` / `[TRACE BIZ]` / `[TRACE ERR]`：返回、业务异常、系统异常
- `[HTTP COMPLETE]`：异步 / SSE 响应最终完成

### 邮件配置（QQ 邮箱）

邮件默认关闭，不影响应用启动。启用 QQ 邮箱 SMTP 时只通过环境变量配置，`APP_MAIL_PASSWORD` 填写 QQ 邮箱生成的 SMTP 授权码，不要把真实授权码或邮箱密码写入仓库、日志或文档。

```powershell
$env:APP_MAIL_ENABLED = "true"
$env:APP_MAIL_HOST = "smtp.qq.com"
$env:APP_MAIL_PORT = "465"
$env:APP_MAIL_USERNAME = "replace-with-your-qq-email@qq.com"
$env:APP_MAIL_PASSWORD = "replace-with-qq-mail-authorization-code"
$env:APP_MAIL_FROM = "replace-with-your-qq-email@qq.com"
$env:APP_MAIL_SMTP_AUTH = "true"
$env:APP_MAIL_SSL_ENABLE = "true"
$env:APP_MAIL_STARTTLS_ENABLE = "false"
```

对应 Spring Boot 配置使用 `spring.mail.*`，应用侧开关使用 `app.mail.enabled`。未配置或关闭时 `MailService` 不发送邮件。

### RAG 配置

- `APP_RAG_PROVIDER=local`：默认使用 CPU ONNX。
- `APP_RAG_PROVIDER=openai`：使用 OpenAI-compatible `/v1/embeddings`。
- `APP_RAG_FALLBACK_PROVIDER`：仅当主备模型标识和维度一致时允许自动降级。
- 上传只创建 MySQL 索引任务；Worker 使用租约、乐观锁、指数退避和失败恢复。
- MySQL 通过 `FULLTEXT ... WITH PARSER ngram` 召回候选，Java 融合全文和余弦分数。

## 🔐 安全说明

- 密码以 **BCrypt** 加盐哈希存储；
- 鉴权使用 **JWT (HS256)**，默认 7 天有效，存储在 `localStorage`；
- CORS 已放开 `http://localhost:5173`；
- 越权：所有资源接口会校验 `ownerId == 当前用户`；
- 修改资料：`PUT /api/auth/me`（昵称 / 邮箱），已对接前端「设置」页；
- 修改密码：`PUT /api/auth/me/password`（原密码 + 新密码），修改成功后强制重新登录。

## 📚 关键 API

| 用途 | 方法 | 路径 |
|------|------|------|
| 注册 | POST | `/api/auth/register` |
| 登录 | POST | `/api/auth/login` |
| 当前用户 | GET | `/api/auth/me` |
| 修改资料 | PUT | `/api/auth/me` |
| 修改密码 | PUT | `/api/auth/me/password` |
| 仪表盘统计 | GET | `/api/dashboard` |
| 论文列表 | GET | `/api/papers?keyword=&page=&size=` |
| 上传 PDF | POST | `/api/papers/upload` (multipart) |
| 论文详情 | GET | `/api/papers/{id}` |
| 全文 | GET | `/api/papers/{id}/full-text` |
| 索引状态 | GET | `/api/papers/{id}/index-status` |
| 重建索引 | POST | `/api/papers/{id}/index/rebuild` |
| AI 总结 | POST | `/api/papers/{id}/summarize` |
| 论文更新 | PUT | `/api/papers/{id}` |
| 论文删除 | DELETE | `/api/papers/{id}` |
| 笔记列表 | GET | `/api/notes?page=&size=` |
| 笔记创建 | POST | `/api/notes` |
| 笔记更新 | PUT | `/api/notes/{id}` |
| 笔记删除 | DELETE | `/api/notes/{id}` |
| 会话列表 | GET | `/api/chat/sessions` |
| 新建会话 | POST | `/api/chat/sessions` |
| 消息列表 | GET | `/api/chat/sessions/{id}/messages` |
| 发送消息（普通） | POST | `/api/chat/sessions/{id}/messages` |
| 发送消息（流式 SSE） | POST | `/api/chat/sessions/{id}/messages/stream` |

详细 Schema 见 Swagger UI。

## 🩹 已知限制 / 路线图

- MySQL 混合检索适合当前数千篇规模；更大规模应迁移 pgvector、Qdrant 或 Milvus
- RAG 无检索结果时回退到摘要或最多 12k 字符的全文节选
- PDF 解析为纯文本，**扫描版 PDF 需要 OCR**（可集成 Tesseract）
- 未实现多用户协作、引用图谱、跨论文对比

## 📜 License

MIT（可自由使用与改造）