DevBrain-CQUPT

面向高校与企业知识场景的 RAG 智能知识库平台

把 PDF、Office、Markdown、网页和飞书文档转成可检索、可追溯、可对话的知识资产。

---

项目简介

DevBrain-CQUPT 是一套前后端分离的智能知识库系统，覆盖「文档采集 → 内容解析 → 智能分块 → Embedding 向量化 → 语义检索 → SSE 流式问答」完整链路。

项目后端采用 Java 17 + Spring Boot 3.5 多模块架构，前端采用 React 18 + Vite，向量存储基于 PostgreSQL + pgvector，并集成 Redis、MinIO、RocketMQ 等中间件。

功能亮点

• 知识库闭环： 知识库、文档、分块、向量、同步历史统一管理。
• RAG 流式问答： 支持 SSE 输出、多轮记忆、查询改写、子问题拆分、深度思考和主动停止。
• 文档处理管线： 支持 PDF、Office、Markdown、HTML 等格式，内置 Apache Tika 和 5 种智能分块策略。
• 可编排摄入 Pipeline： fetcher / parser / enhancer / chunker / enricher / indexer 六类节点，支持任务日志追踪。
• 企业级安全： HttpOnly Cookie JWT、CSRF 双提交、RBAC 权限码、接口资源规则、登录风控、分布式限流。
• AI 多 Provider： Embedding 和 LLM 支持按优先级路由与降级，当前接入 Ollama 与 SiliconFlow。

界面预览

登录	首页
知识问答	后台管理
知识库管理	文档管理
分块查看	流水线编辑

技术架构

React + Vite
    |
    | Cookie + X-XSRF-TOKEN
    v
Spring Boot bootstrap
    |-- Auth / RBAC / CSRF / UserContext
    |-- Knowledge Base / Document / Chunk / Sync
    |-- Ingestion Pipeline / Task / Node Log
    |-- RAG Chat / Retrieval / Conversation Memory
    |
    |-- framework: 统一响应、异常、幂等、追踪、MQ、分布式 ID
    |-- infra-ai: Embedding 路由、LLM 同步与流式调用
    |
    +-- PostgreSQL + pgvector
    +-- Redis
    +-- MinIO
    +-- RocketMQ

技术栈

方向	技术
后端	Java 17、Spring Boot 3.5、MyBatis-Plus、Lombok
前端	React 18、Vite 6、TypeScript、Zustand、React Router、Axios
AI	Ollama、SiliconFlow、Embedding 多 Provider 路由、LLM 流式输出
数据	PostgreSQL 16、pgvector、HNSW、Redis
文档	Apache Tika、Markdown 解析、网页抓取、飞书开放平台
存储与消息	MinIO、AWS S3 SDK、RocketMQ、Redisson
调度与可观测	XXL-JOB（可选）、请求 ID、Trace、节点级任务日志

项目结构

devbrain-cqupt/
├── bootstrap/          # Spring Boot 主应用，包含认证、知识库、文档、Pipeline、RAG 接口
├── framework/          # 通用框架能力：响应、异常、上下文、幂等、追踪、MQ、分布式 ID
├── infra-ai/           # AI 基础设施：EmbeddingService、LLMService、多 Provider 路由
├── mcp-server/         # MCP Server 骨架，默认端口 9099
├── frontend/           # React + Vite 前端应用
├── resources/
│   ├── database/       # schema.sql 与数据库说明
│   └── docker/         # PostgreSQL、Redis、MinIO、RocketMQ Compose
├── docs/               # 架构、功能和部署文档
└── pom.xml             # Maven 父工程

快速开始

环境要求

• JDK 17+
• Maven 3.8+
• Node.js 18+
• Docker 24+ / Docker Compose v2

1. 启动中间件

docker compose -f resources/docker/postgres-pgvector.compose.yaml up -d
docker compose -f resources/docker/redis.compose.yaml up -d
docker compose -f resources/docker/minio.compose.yaml up -d
docker compose -f resources/docker/rocketmq.compose.yaml up -d

Redis Compose 默认发布 6379，后端默认读取 REDIS_PORT=6380。本地启动后端前建议显式设置：$env:REDIS_PORT="6379"。

2. 启动后端

$env:REDIS_PORT="6379"
mvn -q -DskipTests compile
mvn -pl bootstrap -am spring-boot:run

后端默认地址：http://localhost:9090/api/devbrain

3. 启动前端

cd frontend
npm install
npm run dev

前端默认地址：http://localhost:5173

4. 登录系统

用户名：admin
密码：password

该账号仅用于本地开发和演示，非本地环境必须修改默认密码与密钥。

常用命令

# 后端
mvn -q -DskipTests compile
mvn -pl bootstrap -am test
mvn -pl bootstrap -am spring-boot:run

# 前端
cd frontend
npm run build
npm run dev

# 提交前检查
git diff --check

API 概览

所有后端接口统一挂载在：

/api/devbrain

核心接口分组：

• /auth/**：注册、登录、退出、CSRF、密码重置
• /user/**、/users/**、/roles/**、/permissions/**、/resources/**：用户与 RBAC 管理
• /knowledge-base/**、/knowledge-documents/**、/documents/**、/chunks/**：知识库、文档与分块管理
• /sync-tasks/**：在线文档同步与同步历史
• /ingestion/**：摄入流水线与任务执行
• /rag/v3/chat：SSE 流式问答
• /rag/v3/stop：停止指定流式任务

文档入口

• 文档索引
• 功能总结
• Framework 架构说明
• 数据库与中间件搭建
• 用户认证与权限
• 文档上传指南
• 文档分块策略
• 在线文档同步
• Embedding 配置指南
• Embedding 安全方案

配置提示

• 本地数据库 schema 位于 resources/database/schema.sql，PostgreSQL 容器首次启动时会自动初始化。
• resources/docker/.env.example 和 application.yaml 中的密钥仅作本地占位，生产环境必须通过环境变量或密钥管理器覆盖。
• Embedding 模型维度必须与 t_knowledge_vector.embedding 列定义一致，切换模型前请确认 RAG_DEFAULT_DIMENSION。
• RAG 流式接口已接入限流、并发控制与幂等防护，相关配置位于 rag.chat.*。

安全说明

• JWT 存放在 HttpOnly DEV_BRAIN_TOKEN Cookie 中，不写入前端存储。
• 写接口使用 XSRF-TOKEN + X-XSRF-TOKEN 双提交校验。
• 接口权限由 t_resource 资源规则和 RBAC 权限码统一控制。
• 生产环境请开启 HTTPS，并设置 DEVBRAIN_COOKIE_SECURE=true。

已实现功能与模块

模块	已实现能力
认证与会话	用户注册、登录、退出、密码重置、个人资料维护、HttpOnly Cookie JWT、Redis 会话、CSRF 双提交防护。
RBAC 权限	用户管理、角色管理、权限码管理、接口资源规则、角色权限分配、用户角色分配、请求级权限校验。
登录风控	IP 级登录限流、账号失败次数锁定、密码 BCrypt 加密、登录审计。
知识库管理	知识库创建、分页查询、详情、更新、逻辑删除、collection_name 唯一校验、删除保护。
文档管理	本地文档上传、文档分页查询、启用/禁用、删除、文件扩展名校验、MIME 检测、文件名清理、上传并发限制。
文档解析	Apache Tika 多格式解析、Markdown 专用解析、解析状态流转、失败重试、文本清理、异步解析任务。
文档分块	固定大小、递归字符、结构感知、问答对、表格感知 5 种分块策略；支持分块查询、编辑、删除和批量启用/禁用。
向量与检索	pgvector 向量存储、HNSW 索引、余弦相似度 Top-K 检索、分块变更后自动同步向量。
Embedding 服务	Ollama / SiliconFlow 多 Provider 路由、候选模型优先级降级、向量维度校验、批量 Embedding。
在线同步	飞书文档同步、URL 抓取同步、内容哈希比对、手动触发、定时调度、同步历史和同步概览。
摄入 Pipeline	Pipeline 定义 CRUD、6 类节点注册、JSON 来源任务、文件上传任务、节点级状态与日志记录。
RAG 问答	SSE 流式问答、多轮对话记忆、会话摘要、查询改写、子问题拆分、意图识别、深度思考、停止生成。
问答防护	聊天限流、并发队列控制、短窗口幂等提交、防重复请求、防资源占用。
前端应用	登录注册、用户工作台、后台管理、知识库管理、文档管理、分块查看、同步任务、Pipeline 编排、RAG 对话页面。
基础框架	统一响应、全局异常、请求 ID、用户上下文、MyBatis-Plus 自动填充、幂等、追踪、Redis Key 序列化、RocketMQ 适配、分布式 ID。
MCP Server	独立 Spring Boot 模块骨架，默认端口 9099，预留后续 MCP 工具扩展入口。

许可证

本项目由 liuqiyang 个人开发并开源。