MaxKB4j 开源 RAG 知识库平台技术架构解析

核心模块详解

1. maxkb4j-common (公共模块)

路径: maxkb4j-common/src/main/java/com/maxkb4j/common/

这一层是项目的基石，提供通用的基础设施。比如统一响应封装 R.java 和全局异常处理 GlobalExceptionHandler.java，确保整个系统的交互规范一致。Sa-Token 权限工具 StpKit.java 也在这里集中管理。

2. maxkb4j-core (核心模块)

路径: maxkb4j-core/src/main/java/com/maxkb4j/core/

这里是 AI 能力的核心所在。我们定义了各种类型的助手接口，比如意图分类助手 IntentClassifyAssistant 或自然语言转 SQL 助手 NL2SqlAssistant。事件系统则负责处理文档索引、问题生成等异步操作。

Assistant (AI 助手接口)

Event (事件系统)

LangChain4j 集成

• AppChatMemory - 应用聊天记忆管理
• AssistantServices - 助手服务工厂

3. maxkb4j-service-api (服务 API 层)

路径: maxkb4j-service-api/

定义服务接口、实体、DTO、VO 和 Mapper。这里主要关注数据模型的设计，比如知识库表 KnowledgeEntity、文档表 DocumentEntity 以及向量嵌入表 EmbeddingEntity。

主要实体

数据库表结构

主要数据表：

-- 用户表 user(id, email, phone, nickname, username, password, role, is_active)
-- 知识库表 knowledge (id, name,type, source_type, embedding_model_id,...)
-- 文档表 document (id, knowledge_id, name,type, content,...)
-- 段落表 paragraph (id, document_id, content, title,...)
-- 向量嵌入表 embedding (id, paragraph_id, embedding vector(1536),...)
-- 应用表 application (id, name,type, model_id, workflow,...)
-- 聊天记录表 application_chat_record (id, application_id, chat_id, problem_text, answer_text,...)

4. maxkb4j-service (服务实现层)

路径: maxkb4j-service/

4.1 maxkb4j-application (应用服务)

核心功能: 应用管理、聊天服务（简单聊天、工作流聊天）、访问令牌管理、API Key 管理及聊天记录管理。

关键类: ApplicationService, ChatSimpleServiceImpl, ChatFlowServiceImpl, ChatServiceBuilder。

Pipeline 架构:

PipelineManage
├── GenerateHumanMessageStep # 生成用户消息
├── ResetProblemStep         # 重置问题
├── SearchDatasetStep        # 搜索知识库
└── ChatStep                 # 聊天步骤

4.2 maxkb4j-knowledge (知识库服务)

核心功能: 知识库管理、文档解析（PDF、Word、TXT、Markdown、HTML、URL 等）、文档分块、向量索引及检索服务。

文档解析器:

检索策略: FullTextRetriever (全文检索), HybridRetriever (混合检索), PgVectorIndexService (PostgreSQL 向量索引)。

4.3 maxkb4j-model (模型服务)

核心功能: 模型提供商管理、模型实例构建、多种模型类型支持。

支持的模型提供商:

模型类型: ChatModel, StreamingChatModel, EmbeddingModel, ImageModel, ScoringModel, STTModel, TTSModel。

4.4 maxkb4j-workflow (工作流服务)

核心架构:

WorkFlowActuator (工作流执行器)
├── ChatWorkflowHandler (聊天工作流处理器)
└── KnowledgeWorkflowHandler (知识库工作流处理器)

节点类型 (NodeType 枚举):

条件比较器: EqualCompare, ContainCompare, GTCompare/GECompare, LTCompare/LECompare, IsNullCompare/IsNotNullCompare, IsTrueCompare/IsNotTrueCompare, LengthEqualCompare 等。

4.5 maxkb4j-tool (工具服务)

核心功能: 工具管理、连接验证、导入导出。

关键类: ToolService, ToolProviderService, McpToolUtil, SkillsToolUtil。

5. maxkb4j-start (启动模块)

路径: maxkb4j-start/src/main/java/com/maxkb4j/start/

配置类

监听器

数据库迁移

• V1__init_tables.sql - 初始化表结构
• V2__add_table.sql - 新增表
• V3__add_trigger.sql - 触发器表

6. ui (前端项目)

路径: ui/

技术栈

• 框架: Vue 3.5 + TypeScript
• UI 组件: Element Plus 2.12
• 状态管理: Pinia 3.0
• 路由: Vue Router 4.5
• 工作流编辑器: LogicFlow 1.2
• 图表: ECharts 5.6
• Markdown: md-editor-v3
• 构建工具: Vite 6.2

目录结构

ui/src/
├── App.vue              # 根组件
├── main.ts              # 入口文件
├── components/          # 公共组件
│   ├── ai-chat/         # AI 聊天组件
│   ├── dynamics-form/   # 动态表单组件
│   ├── markdown/        # Markdown 组件
│   └── ...
├── layout/              # 布局组件
├── views/               # 页面视图
│   ├── application/     # 应用管理
│   ├── application-overview/ # 应用概览
│   ├── chat/            # 聊天页面
│   ├── chat-log/        # 聊天日志
│   ├── chat-user/       # 聊天用户
│   ├── document/        # 文档管理
│   ├── knowledge/       # 知识库管理
│   ├── login/           # 登录页面
│   ├── model/           # 模型管理
│   ├── paragraph/       # 段落管理
│   ├── problem/         # 问题管理
│   ├── system/          # 系统管理
│   ├── system-chat-user/ # 系统聊天用户
│   ├── system-setting/  # 系统设置
│   ├── tool/            # 工具管理
│   └── workflow/        # 工作流编辑
└── workflow/            # 工作流相关
    ├── nodes/           # 节点组件
    ├── icons/           # 节点图标
    └── common/          # 公共组件

主要页面

API 接口

认证接口

POST /api/user/login      # 用户登录
POST /api/user/logout     # 用户登出
GET  /api/user/info       # 获取用户信息

应用接口

GET  /api/application          # 获取应用列表
POST /api/application          # 创建应用
PUT  /api/application/{id}     # 更新应用
DELETE /api/application/{id}   # 删除应用
GET  /api/application/{id}     # 获取应用详情
POST /api/application/chat     # 聊天接口

知识库接口

GET  /api/knowledge          # 获取知识库列表
POST /api/knowledge          # 创建知识库
PUT  /api/knowledge/{id}     # 更新知识库
DELETE /api/knowledge/{id}   # 删除知识库
GET  /api/knowledge/{id}     # 获取知识库详情

文档接口

GET  /api/document          # 获取文档列表
POST /api/document          # 上传文档
DELETE /api/document/{id}   # 删除文档
POST /api/document/split    # 文档分块
POST /api/document/index    # 文档索引

模型接口

GET  /api/model          # 获取模型列表
POST /api/model          # 创建模型
PUT  /api/model/{id}     # 更新模型
DELETE /api/model/{id}   # 删除模型
GET  /api/provider       # 获取提供商列表

部署指南

系统要求

• Java 21+
• Maven 3.8+
• PostgreSQL 12+ (启用 pgvector 扩展)
• MongoDB 6.0+ (可选，用于全文搜索)
• Node.js 20+ (前端构建)

Docker 部署

使用官方镜像快速启动服务，注意环境变量配置：

docker run --name maxkb4j -d \
  --restart always \
  -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/MaxKB4j \
  -e SPRING_DATASOURCE_USERNAME=postgres \
  -e SPRING_DATASOURCE_PASSWORD=123456 \
  -e SPRING_DATA_MONGODB_URI=mongodb://admin:123456@localhost:27017/MaxKB4j?authSource=admin \
  registry.cn-hangzhou.aliyuncs.com/tarzanx/maxkb4j

Docker Compose 部署

如果需要同时启动数据库依赖，可以使用以下配置：

version: '3'
services:
  maxkb4j:
    image: registry.cn-hangzhou.aliyuncs.com/tarzanx/maxkb4j
    ports:
      - "8080:8080"
    environment:
      - SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/MaxKB4j
      - SPRING_DATASOURCE_USERNAME=postgres
      - SPRING_DATASOURCE_PASSWORD=123456
      - SPRING_DATA_MONGODB_URI=mongodb://admin:123456@mongo:27017/MaxKB4j?authSource=admin
    depends_on:
      - postgres
      - mongo

  postgres:
    image: pgvector/pgvector:pg15
    environment:
      POSTGRES_DB: MaxKB4j
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: 123456
    volumes:
      - postgres_data:/var/lib/postgresql/data

  mongo:
    image: mongo:6.0
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: 123456
    volumes:
      - mongo_data:/data/db

volumes:
  postgres_data:
  mongo_data:

本地开发

# 后端
cd MaxKB4j
mvn spring-boot:run -pl maxkb4j-start

# 前端
cd ui
npm install
npm run dev

配置说明

application.yml 主要配置

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/MaxKB4j
    username: postgres
    password: 123456
  data:
    mongodb:
      uri: mongodb://admin:123456@localhost:27017/MaxKB4j?authSource=admin

# Sa-Token 配置
sa-token:
  token-name: Authorization
  timeout: 2592000
  active-timeout: -1
  is-concurrent: true
  is-share: true
  token-style: uuid
  is-log: false

扩展开发

添加新的模型提供商

如果你需要接入其他模型，只需继承 AbsModelProvider 类，然后实现必要的方法即可。比如 getModelList() 返回支持的模型列表，buildChatModel() 构建对话模型，最后记得注册为 Spring Bean。

添加新的工作流节点

在 NodeType 枚举中添加新类型，创建对应的节点数据类（继承 AbsNode），编写节点处理器（实现 INodeHandler），并加上 @NodeHandlerType 注解。这样前端就能识别并渲染这个新节点了。

添加新的文档解析器

实现 DocumentParser 接口，注册为 Spring Bean，系统就会自动识别并支持该格式的文档解析。

许可证

GNU General Public License v3.0 (GPLv3)