1. 系统概述

1.1 项目背景

企业智能知识库系统是一套面向中大型企业的 全栈知识管理平台。

它不仅仅是文档存储和管理工具,更是一个融合了 AI 智能写作、检索增强生成(RAG)、知识图谱推理(KAG)的 智能知识引擎。

1.2 核心能力矩阵

能力域功能技术支撑
文档管理富文本/Markdown 编辑、多层级分类、标签、版本管理、审核工作流MySQL + MongoDB + RustFS
智能搜索全文检索、混合检索(BM25+向量)、重排序Elasticsearch
AI 助手多模型对话(Qwen/DeepSeek)、智能写作、RAG 知识增强回答Spring AI + OpenAI-Compatible API
知识图谱实体抽取、关系构建、图遍历检索、KAG 融合推断Neo4j + 图算法
协作审核提交审核 → 审批通过/驳回 → 状态流转 → 通知推送Spring Security RBAC + WebSocket
统计分析文档趋势、用户活跃度、热度排行、操作日志RabbitMQ 事件驱动 + 跨库视图
实时通知WebSocket 推送 + 站内通知 + 模板化消息STOMP + SockJS
权限管控RBAC 角色权限 + 数据级访问控制Spring Security + JWT

1.3 架构设计理念

系统遵循三条核心设计原则:

  1. 数据库隔离,服务自治:每个微服务拥有独立数据库,跨库查询通过视图或 Feign 调用实现,避免分布式事务。
  2. 可演进的模块化单体:微服务拆分粒度适中(10 个服务),服务间职责边界清晰,未来可进一步拆分或合并。
  3. AI 优先但不依赖:所有 AI 增强功能(RAG、KAG、智能写作)均有降级策略,AI 不可用时系统核心 CRUD 功能不受影响。

2. 系统全景架构

图片.png

3. 逻辑架构

3.1 分层架构

系统采用 六层架构,每一层职责清晰、边界明确:

图片.png

3.2 服务职责边界

每个微服务的 "不可侵犯边界":

服务独有职责不负责
kb-user-auth用户 CRUD、角色/权限管理、JWT 签发文档内容、审核逻辑
kb-document文档 CRUD、分类/标签、评论/点赞、版本管理AI 对话、图谱构建
kb-search全文检索、混合检索、搜索历史文档存储、内容管理
kb-file文件上传/下载/预览、格式转换文档元数据、权限
kb-ai多模型对话、RAG 检索增强、KAG 图谱推理、智能写作文档 CRUD、用户管理
kb-graph实体关系抽取、图构建/查询、路径遍历AI 对话、文件管理
kb-statistics数据聚合、趋势分析、跨库统计原始数据管理
kb-foundation通知推送、系统配置、操作日志、字典管理、WebSocket业务逻辑

4. 微服务模块设计

4.1 模块依赖关系

图片.png

kb-common 是唯一被所有模块依赖的共享库,提供:

类别核心类说明
基础实体BaseEntity, BaseEntityWithVersionSnowflake ID + 审计字段 + 逻辑删除
统一响应Result<T>, PageResult<T>标准 REST 响应体
认证工具JwtUtil, SecurityUtil, UserContextUtilJWT 解析 + ThreadLocal 上下文
全局配置MybatisPlusConfig, CorsConfig, JacksonAutoConfigurationORM + 跨域 + 序列化
异常处理GlobalExceptionHandler, BusinessException全局异常拦截与转换
注解切面@OperationLog, @RequirePermission操作日志 + 权限校验 AOP
Feign 拦截FeignInterceptorConfig服务间调用 Token 透传
ID 生成SnowflakeIdGenerator分布式雪花 ID

4.2 包结构规范

所有业务模块遵循统一的分包结构:

com.knowledge.base.{module}/
├── {Module}Application.java          # Spring Boot 启动类
├── config/                           # 模块专属配置
├── controller/                       # REST 控制器(薄层,仅协议转换)
├── service/                          # 业务接口
│   └── impl/                         # 业务实现
├── mapper/                           # MyBatis-Plus Mapper 接口
├── entity/                           # 数据库实体(@TableName)
├── dto/                              # 请求入参对象
├── vo/                               # 响应出参对象
├── feign/                            # Feign 客户端接口
├── event/                            # RabbitMQ 事件处理器
├── task/                             # 定时任务
└── handler/                          # 处理器(WebSocket 等)

4.3 关键设计模式

模式应用场景关键类
继承基类所有实体统一审计字段BaseEntity
适配器模式多 AI 模型统一接口AiChatService / RagSearchService
策略模式审核流程分支(通过/驳回)DocumentReviewService.approveReview() / rejectReview()
观察者模式RabbitMQ 事件驱动统计更新StatisticsEventDTO + @RabbitListener
门面模式Gateway 统一入口路由AuthGlobalFilter + route 配置
模板方法文件上传预处理 + 后处理FileService.upload()

5. 数据库架构设计

5.1 数据库隔离策略

系统严格遵循 Database per Service 模式:

图片.png

5.2 跨库视图设计

kb-statistics 服务通过 MySQL 跨库视图直接读取其他服务的数据库,无需 Feign 调用:

-- kb_statistics 库中的跨库视图(7 个)
-- 视图: kb_document         → 来源: kb_document.kb_document
-- 视图: kb_user             → 来源: kb_user.kb_user
-- 视图: kb_comment          → 来源: kb_document.kb_comment
-- 视图: kb_operation_log    → 来源: kb_foundation.kb_operation_log
-- 视图: kb_category         → 来源: kb_document.kb_category
-- 视图: kb_ai_conversation  → 来源: kb_ai.kb_ai_conversation
-- 视图: kb_ai_message       → 来源: kb_ai.kb_ai_message

设计意图:统计服务的聚合查询避免走 N 次 Feign 调用,直接 SQL 跨库 JOIN 效率更高。

5.3 通用表字段规范

所有业务表遵循统一的字段规范:

-- 每张表的标准字段模板
`id`           BIGINT NOT NULL    COMMENT 'Snowflake 雪花 ID',
`created_at`   DATETIME NOT NULL  DEFAULT CURRENT_TIMESTAMP,
`updated_at`   DATETIME NOT NULL  DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
`create_by`    BIGINT DEFAULT NULL,
`update_by`    BIGINT DEFAULT NULL,
`deleted`      TINYINT NOT NULL   DEFAULT 0  COMMENT '逻辑删除: 0-正常, 1-已删除'
  • 主键策略:所有表统一使用 SnowflakeIdGenerator 生成 19 位 BIGINT ID,IdType.INPUT
  • 逻辑删除:@TableLogic 自动追加 deleted = 0 条件
  • 审计字段:MyMetaObjectHandler 自动填充 created_at/updated_at/create_by/update_by
  • 字符集:全部 utf8mb4 + utf8mb4_unicode_ci

5.4 数据库分布表

#数据库拥有服务核心表数量扩展存储
1kb_userkb-user-auth8—
2kb_documentkb-document7MongoDB(文档内容), ES(全文索引)
3kb_searchkb-search1ES(搜索索引)
4kb_filekb-file1RustFS(文件存储)
5kb_aikb-ai3ES(RAG 向量块)
6kb_statisticskb-statistics4 + 7视图RabbitMQ(事件消费)
7kb_graphkb-graph3Neo4j(图存储)
8kb_foundationkb-foundation5Redis(WebSocket 会话)

6. 认证与授权体系

6.1 认证架构

图片.png

6.2 JWT 令牌设计

令牌类型有效期用途
access\_token2 小时API 请求身份凭证
refresh\_token7 天无感刷新 access\_token

JWT Payload 结构:

{
  "sub": "1000000000000000001",
  "username": "admin",
  "avatar": "https://...",
  "type": "access",
  "iat": 1718832000,
  "exp": 1718839200
}

6.3 RBAC 权限模型

图片.png

预置角色与权限:

角色编码核心权限
超级管理员ROLE_SUPER_ADMIN全部权限
知识管理员ROLE_ADMIN文档管理 + 分类/标签/版本 + 审核
知识编辑者ROLE_EDITOR文档查看 + 创建 + AI 对话
审核员ROLE_REVIEWER文档查看 + 审核
知识成员ROLE_USER文档查看/创建/编辑/删除 + AI 对话
游客ROLE_VISITOR文档查看(只读)

权限校验方式:

// 方式1:方法级注解(推荐)
@PreAuthorize("hasAuthority(T(...DocumentPermissionConstants).DOCUMENT_REVIEW)")
public Result<Boolean> reviewDocument(...) { ... }

// 方式2:自定义注解(带权限码)
@RequirePermission("document:edit")
public Result<Boolean> updateDocument(...) { ... }

6.4 网关白名单

以下路径无需 JWT 认证即可访问:

/api/auth/auth/login       # 登录
/api/auth/auth/register    # 注册
/api/auth/auth/refresh     # 刷新令牌
/api/document/share/**     # 文档分享链接
/api/ai/**                 # AI 对话(匿名可选)
/api/config/public         # 公开配置
/ws/**                     # WebSocket 连接
/doc.html                  # API 文档

7. 核心业务流程

7.1 文档审核工作流

图片.png

7.2 RAG 知识增强问答

图片.png

7.3 KAG 图谱增强推断

图片.png

8. API 网关与通信

8.1 路由架构

图片.png

8.2 网关过滤器链

按优先级排序:

顺序过滤器职责
-200AuthGlobalFilterJWT 解析 → 提取 userId → 注入 X-User-Id 请求头
-100CorsResponseHeaderFilter跨域响应头处理
0GlobalLogFilter请求/响应日志记录
100UnifiedResponseFilter统一响应格式包装

8.3 服务间通信

同步通信(Feign):

// kb-ai 调用 kb-document 获取文档内容
@FeignClient(name = "kb-document", path = "/document")
public interface DocumentFeignClient {
    @GetMapping("/{documentId}")
    Result<DocumentVO> getDocument(@PathVariable Long documentId);
}

关键设计:FeignInterceptorConfig 自动将当前用户的 JWT Token 透传到下游服务,保证调用链中用户身份不丢失。

异步通信(RabbitMQ):

// 文档更新后发布事件
rabbitTemplate.convertAndSend("document.exchange", "document.updated",
    new DocumentEventDTO(documentId, userId));

// kb-statistics 消费事件,更新统计表
@RabbitListener(queues = "statistics.document.queue")
public void handleDocumentEvent(DocumentEventDTO event) {
    statisticsService.updateDocumentStats(event.getDocumentId());
}

9. 前端架构设计

9.1 技术栈

层面技术说明
框架React 18.3 + TypeScript 5.3函数组件 + Hooks
构建Vite 5.1 (SWC)秒级热更新
UI 库Ant Design 5.14企业级组件库
状态管理Zustand 4.5 + Immer轻量级、不可变更新
路由React Router 6.22懒加载 + 权限守卫
HTTPAxios 1.6 + 拦截器链自动 Token 注入 + 无感刷新
图表ECharts 5.6统计仪表盘
实时通信STOMP.js + SockJSWebSocket 通知推送
文档渲染Mammoth.js + react-pdfDOCX/PDF 预览

9.2 Zustand Store 架构

// 以 document.store.ts 为例
export const useDocumentStore = create<DocumentState>()(
  devtools((set, get) => ({
    // 状态
    documents: [],
    currentDocument: null,
    loading: false,

    // 异步操作
    fetchDocuments: async (params) => {
      set({ loading: true });
      const result = await documentService.listDocuments(params);
      set({ documents: result.records, loading: false });
    },

    // 点赞(乐观更新 + 后端同步)
    likeDocument: async (id: string) => {
      // Phase 1: 乐观 UI 更新
      set((state) => ({
        currentDocument: { ...state.currentDocument, isLiked: true }
      }));
      // Phase 2: 后端请求 + 真实数据同步
      await documentService.likeDocument(id);
      const doc = await documentService.getDocument(id);
      set((state) => ({
        currentDocument: { ...state.currentDocument,
          likeCount: doc.likeCount, isLiked: doc.isLiked }
      }));
    }
  }))
);

9.3 Axios 拦截器链

// 请求拦截器
request.interceptors.request.use((config) => {
  // 1. 自动注入 JWT Token
  const token = getToken();
  if (token) config.headers.Authorization = `Bearer ${token}`;
  // 2. 添加请求 ID 用于链路追踪
  config.headers['X-Request-Id'] = generateRequestId();
  return config;
});

// 响应拦截器
request.interceptors.response.use(
  (response) => response.data,  // 解包统一响应体
  async (error) => {
    if (error.response?.status === 401) {
      // Token 过期 → 无感刷新 → 重试原请求
      return refreshTokenQueue.enqueue(error.config);
    }
    return Promise.reject(error);
  }
);

9.4 前端页面结构

src/pages/
├── DashboardPage           # 仪表盘
├── DocumentDetailPage      # 文档详情(点赞/评论/分享)
├── CreateDocumentPage      # 创建文档(富文本/Markdown)
├── EditDocumentPage        # 编辑文档
├── MyDocumentsPage         # 我的文档
├── DraftsPage              # 草稿箱
├── DocumentReviewWorkspacePage  # 审核工作台
├── DocumentVersionsPage    # 版本历史
├── SearchPage              # 全文搜索
├── KnowledgeGraphPage      # 知识图谱可视化
├── AIAssistantPage         # AI 对话助手
├── AIWritingPage           # AI 智能写作
├── ProfilePage             # 个人中心
├── NotificationCenterPage  # 通知中心
├── RecentAccessPage        # 最近访问
├── FavoritesPage           # 我的收藏
└── admin/                  # 管理后台
    ├── AdminCenter          # 管理总览
    ├── UsersManagement      # 用户管理
    ├── RolesPage            # 角色管理
    ├── PermissionsPage      # 权限管理
    ├── CategoriesPage       # 分类管理
    ├── TeamsPage            # 团队管理
    ├── ReviewPage           # 审核管理
    ├── StatisticsPage       # 数据统计
    ├── SystemConfigPage     # 系统配置
    ├── DictionaryManagePage # 字典管理
    ├── OperationLogPage     # 操作日志
    └── NotificationTemplatePage  # 通知模板

10. AI 引擎架构

10.1 多模型接入

图片.png

10.2 RAG 文档分块策略

图片.png

检索参数:

  • Top-K: 5
  • 向量相似度: cosine
  • BM25 权重: 0.5
  • 向量权重: 0.5
  • RRF 融合参数 k: 60

10.3 AI 写作引擎

图片.png

10.4 AI 降级策略

图片.png

11. 知识图谱架构

11.1 双存储架构

图片.png

11.2 图谱节点与关系

节点类型:
  ├── document   - 文档节点
  ├── concept    - 概念节点(自动抽取)
  ├── person     - 人物节点(从作者/引用中提取)
  ├── category   - 分类节点
  └── tag        - 标签节点

关系类型:
  ├── BELONGS_TO    - 文档属于某分类
  ├── TAGGED_WITH   - 文档含某标签
  ├── REFERENCES    - 文档引用概念
  ├── AUTHORED_BY   - 文档作者关系
  ├── RELATED_TO    - 概念间关联
  └── SIMILAR_TO    - 文档间相似性

12. 部署拓扑

图片.png

建议资源配置:

服务实例数规格说明
kb-gateway22C4G无状态,水平扩展
kb-user-auth22C4G高频调用
kb-document24C8G核心业务,内存密集型
kb-search24C8GES 查询密集
kb-file22C4GIO 密集型
kb-ai38C16GAI 调用 + 向量计算,资源大户
kb-graph24C8G图计算密集
kb-statistics12C4G非实时,单实例即可
kb-foundation22C4GWebSocket 长连接
MySQL1主2从8C16G读写分离
Redis34C8GCluster 模式
Elasticsearch38C16G数据 + 向量检索
Neo4j38C16G图计算
RabbitMQ32C4G高可用队列
RustFS34C8G分布式存储
Nacos32C4G注册中心 + 配置中心

13. 技术选型

13.1 后端技术栈

类别技术版本选型理由
语言Java21LTS 版本,虚拟线程(Loom)可用
框架Spring Boot3.2.0企业级生态,自动配置
微服务Spring Cloud2023.0.0服务发现 + 配置管理 + 网关
注册中心Nacos2.2+阿里巴巴出品,兼具服务发现和配置中心
ORMMyBatis-Plus3.5.8类型安全 Lambda 查询,分页、乐观锁、逻辑删除开箱即用
认证Spring Security + JJWT0.12.3无状态 JWT 方案,适配微服务
文档存储MongoDB6.0+富文本/Markdown 大字段存储,JSON 原生支持
全文检索Elasticsearch8.xBM25 + kNN 向量检索,混合检索 RRF 融合
图数据库Neo4j5.x知识图谱原生存储,Cypher 查询
缓存Redis7.2高性能缓存 + 分布式会话
消息队列RabbitMQ3.12事件驱动解耦,管理界面友好
文件存储RustFS-分布式文件系统,S3 兼容 API
API 文档Knife4j4.3.0Swagger 增强,支持 Jakarta EE
工具库Hutool5.8.24国产工具集,覆盖绝大多数常见操作
JSONFastJSON22.0.43高性能序列化
连接池Druid1.2.20阿里巴巴出品,完善的监控能力

13.2 前端技术栈

类别技术版本选型理由
框架React18.3.1函数组件 + Hooks,生态丰富
语言TypeScript5.3.3类型安全,降低运行时错误
构建Vite5.1.0SWC 编译,HMR 秒级响应
UI 库Ant Design5.14.0企业级组件,中文优先
状态Zustand4.5.0比 Redux 轻 10x,API 简洁
路由React Router6.22.0懒加载 + 布局路由
HTTPAxios1.6.7拦截器链 + Token 刷新队列
图表ECharts5.6.0国产顶级图表库
样式CSS Modules + Ant Design Token-作用域隔离 + 主题定制

14. 扩展性设计

14.1 水平扩展点

组件扩展方式关键配置
Gateway无状态,Nginx upstream 增加节点upstream gateway { ... }
业务服务Nacos 服务发现自动负载均衡spring.cloud.nacos.discovery
MySQL主从复制 + 读写分离spring.datasource.dynamic
RedisCluster 模式,动态加节点redis-cli --cluster add-node
Elasticsearch分片 + 副本,滚动扩容number_of_shards: 3
RabbitMQ集群 + 镜像队列rabbitmqctl join_cluster
RustFS水平扩容 Bucket 分片自动 rebalance

14.2 架构演进路径

当前 (v1.0): 模块化微服务 (10 服务)
  │
  ├─→ 可选拆分1: kb-document 拆为 document-core + document-review
  │     触发条件: 审核功能成为独立产品线
  │
  ├─→ 可选拆分2: kb-ai 拆为 ai-chat + ai-rag + ai-writing
  │     触发条件: AI 各子模块独立迭代频率差异大
  │
  ├─→ 可选合并: kb-notification 合并回 kb-foundation(已执行)
  │     触发条件: 通知服务调用量低,独立部署成本高于收益
  │
  └─→ 未来: Service Mesh (Istio) 替代部分 Spring Cloud 能力
        触发条件: 服务数量 > 20,需要更细粒度的流量管控

14.3 插件化扩展

  • AI 模型插件化:新增模型只需实现 ModelProvider 接口 + 注册到 ModelProviderFactory
  • 规则引擎插件化:审核规则可配置化加载,支持热更新
  • 通知渠道插件化:WebSocket → 邮件 → 短信 → 企业微信,按渠道实现 NotificationSender 接口

15. 安全设计

15.1 安全分层

图片.png

15.2 令牌安全设计

  • Token 刷新队列:并发 401 请求自动排队,不会重复刷新
  • Token 黑名单:登出时 Token 加入 Redis 黑名单,TTL = Token 剩余有效期
  • 设备指纹绑定:可选开启,Token 与 User-Agent + IP 前缀绑定

16. 性能优化

16.1 多级缓存策略

图片.png

16.2 数据库优化

策略实现
连接池Druid,最小 10,最大 50
索引优化联合索引 (user_id, deleted)、覆盖索引减少回表
分页MyBatis-Plus 分页插件,自动 count 优化
读写分离动态数据源,写走主库,读走从库
大文本分离文档列表不加载 content 字段,详情页按需查询

16.3 ES 搜索优化

策略配置
分片策略3 主分片 + 1 副本
刷新间隔refresh_interval: 5s(非实时可放宽)
向量索引HNSW 算法,m=16, ef_construction=200
查询优化search\_after 深度分页,避免 from+size

附录

术语表

术语全称说明
RAGRetrieval-Augmented Generation检索增强生成:从知识库检索相关内容,注入 LLM 上下文
KAGKnowledge-Augmented Generation知识增强生成:从知识图谱中检索实体关系,与 RAG 融合
RRFReciprocal Rank Fusion倒数排名融合:融合向量检索和 BM25 检索结果的排序算法
SnowflakeSnowflake IDTwitter 雪花算法:分布式唯一 ID 生成方案
RBACRole-Based Access Control基于角色的访问控制
JWTJSON Web Token无状态身份令牌
HNSWHierarchical Navigable Small World分层导航小世界:高性能近似最近邻搜索算法
STOMPStreaming Text Oriented Messaging Protocol面向文本流的消息协议,用于 WebSocket 通信
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏