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

3. 逻辑架构
3.1 分层架构
系统采用 六层架构,每一层职责清晰、边界明确:

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 模块依赖关系

kb-common 是唯一被所有模块依赖的共享库,提供:
| 类别 | 核心类 | 说明 |
|---|---|---|
| 基础实体 | BaseEntity, BaseEntityWithVersion | Snowflake ID + 审计字段 + 逻辑删除 |
| 统一响应 | Result<T>, PageResult<T> | 标准 REST 响应体 |
| 认证工具 | JwtUtil, SecurityUtil, UserContextUtil | JWT 解析 + ThreadLocal 上下文 |
| 全局配置 | MybatisPlusConfig, CorsConfig, JacksonAutoConfiguration | ORM + 跨域 + 序列化 |
| 异常处理 | 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 模式:

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 数据库分布表
| # | 数据库 | 拥有服务 | 核心表数量 | 扩展存储 |
|---|---|---|---|---|
| 1 | kb_user | kb-user-auth | 8 | — |
| 2 | kb_document | kb-document | 7 | MongoDB(文档内容), ES(全文索引) |
| 3 | kb_search | kb-search | 1 | ES(搜索索引) |
| 4 | kb_file | kb-file | 1 | RustFS(文件存储) |
| 5 | kb_ai | kb-ai | 3 | ES(RAG 向量块) |
| 6 | kb_statistics | kb-statistics | 4 + 7视图 | RabbitMQ(事件消费) |
| 7 | kb_graph | kb-graph | 3 | Neo4j(图存储) |
| 8 | kb_foundation | kb-foundation | 5 | Redis(WebSocket 会话) |
6. 认证与授权体系
6.1 认证架构

6.2 JWT 令牌设计
| 令牌类型 | 有效期 | 用途 |
|---|---|---|
| access\_token | 2 小时 | API 请求身份凭证 |
| refresh\_token | 7 天 | 无感刷新 access\_token |
JWT Payload 结构:
{
"sub": "1000000000000000001",
"username": "admin",
"avatar": "https://...",
"type": "access",
"iat": 1718832000,
"exp": 1718839200
}6.3 RBAC 权限模型

预置角色与权限:
| 角色 | 编码 | 核心权限 |
|---|---|---|
| 超级管理员 | 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 文档审核工作流

7.2 RAG 知识增强问答

7.3 KAG 图谱增强推断

8. API 网关与通信
8.1 路由架构

8.2 网关过滤器链
按优先级排序:
| 顺序 | 过滤器 | 职责 |
|---|---|---|
| -200 | AuthGlobalFilter | JWT 解析 → 提取 userId → 注入 X-User-Id 请求头 |
| -100 | CorsResponseHeaderFilter | 跨域响应头处理 |
| 0 | GlobalLogFilter | 请求/响应日志记录 |
| 100 | UnifiedResponseFilter | 统一响应格式包装 |
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 | 懒加载 + 权限守卫 |
| HTTP | Axios 1.6 + 拦截器链 | 自动 Token 注入 + 无感刷新 |
| 图表 | ECharts 5.6 | 统计仪表盘 |
| 实时通信 | STOMP.js + SockJS | WebSocket 通知推送 |
| 文档渲染 | Mammoth.js + react-pdf | DOCX/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 多模型接入

10.2 RAG 文档分块策略

检索参数:
- Top-K: 5
- 向量相似度: cosine
- BM25 权重: 0.5
- 向量权重: 0.5
- RRF 融合参数 k: 60
10.3 AI 写作引擎

10.4 AI 降级策略

11. 知识图谱架构
11.1 双存储架构

11.2 图谱节点与关系
节点类型:
├── document - 文档节点
├── concept - 概念节点(自动抽取)
├── person - 人物节点(从作者/引用中提取)
├── category - 分类节点
└── tag - 标签节点
关系类型:
├── BELONGS_TO - 文档属于某分类
├── TAGGED_WITH - 文档含某标签
├── REFERENCES - 文档引用概念
├── AUTHORED_BY - 文档作者关系
├── RELATED_TO - 概念间关联
└── SIMILAR_TO - 文档间相似性12. 部署拓扑

建议资源配置:
| 服务 | 实例数 | 规格 | 说明 |
|---|---|---|---|
| kb-gateway | 2 | 2C4G | 无状态,水平扩展 |
| kb-user-auth | 2 | 2C4G | 高频调用 |
| kb-document | 2 | 4C8G | 核心业务,内存密集型 |
| kb-search | 2 | 4C8G | ES 查询密集 |
| kb-file | 2 | 2C4G | IO 密集型 |
| kb-ai | 3 | 8C16G | AI 调用 + 向量计算,资源大户 |
| kb-graph | 2 | 4C8G | 图计算密集 |
| kb-statistics | 1 | 2C4G | 非实时,单实例即可 |
| kb-foundation | 2 | 2C4G | WebSocket 长连接 |
| MySQL | 1主2从 | 8C16G | 读写分离 |
| Redis | 3 | 4C8G | Cluster 模式 |
| Elasticsearch | 3 | 8C16G | 数据 + 向量检索 |
| Neo4j | 3 | 8C16G | 图计算 |
| RabbitMQ | 3 | 2C4G | 高可用队列 |
| RustFS | 3 | 4C8G | 分布式存储 |
| Nacos | 3 | 2C4G | 注册中心 + 配置中心 |
13. 技术选型
13.1 后端技术栈
| 类别 | 技术 | 版本 | 选型理由 |
|---|---|---|---|
| 语言 | Java | 21 | LTS 版本,虚拟线程(Loom)可用 |
| 框架 | Spring Boot | 3.2.0 | 企业级生态,自动配置 |
| 微服务 | Spring Cloud | 2023.0.0 | 服务发现 + 配置管理 + 网关 |
| 注册中心 | Nacos | 2.2+ | 阿里巴巴出品,兼具服务发现和配置中心 |
| ORM | MyBatis-Plus | 3.5.8 | 类型安全 Lambda 查询,分页、乐观锁、逻辑删除开箱即用 |
| 认证 | Spring Security + JJWT | 0.12.3 | 无状态 JWT 方案,适配微服务 |
| 文档存储 | MongoDB | 6.0+ | 富文本/Markdown 大字段存储,JSON 原生支持 |
| 全文检索 | Elasticsearch | 8.x | BM25 + kNN 向量检索,混合检索 RRF 融合 |
| 图数据库 | Neo4j | 5.x | 知识图谱原生存储,Cypher 查询 |
| 缓存 | Redis | 7.2 | 高性能缓存 + 分布式会话 |
| 消息队列 | RabbitMQ | 3.12 | 事件驱动解耦,管理界面友好 |
| 文件存储 | RustFS | - | 分布式文件系统,S3 兼容 API |
| API 文档 | Knife4j | 4.3.0 | Swagger 增强,支持 Jakarta EE |
| 工具库 | Hutool | 5.8.24 | 国产工具集,覆盖绝大多数常见操作 |
| JSON | FastJSON2 | 2.0.43 | 高性能序列化 |
| 连接池 | Druid | 1.2.20 | 阿里巴巴出品,完善的监控能力 |
13.2 前端技术栈
| 类别 | 技术 | 版本 | 选型理由 |
|---|---|---|---|
| 框架 | React | 18.3.1 | 函数组件 + Hooks,生态丰富 |
| 语言 | TypeScript | 5.3.3 | 类型安全,降低运行时错误 |
| 构建 | Vite | 5.1.0 | SWC 编译,HMR 秒级响应 |
| UI 库 | Ant Design | 5.14.0 | 企业级组件,中文优先 |
| 状态 | Zustand | 4.5.0 | 比 Redux 轻 10x,API 简洁 |
| 路由 | React Router | 6.22.0 | 懒加载 + 布局路由 |
| HTTP | Axios | 1.6.7 | 拦截器链 + Token 刷新队列 |
| 图表 | ECharts | 5.6.0 | 国产顶级图表库 |
| 样式 | CSS Modules + Ant Design Token | - | 作用域隔离 + 主题定制 |
14. 扩展性设计
14.1 水平扩展点
| 组件 | 扩展方式 | 关键配置 |
|---|---|---|
| Gateway | 无状态,Nginx upstream 增加节点 | upstream gateway { ... } |
| 业务服务 | Nacos 服务发现自动负载均衡 | spring.cloud.nacos.discovery |
| MySQL | 主从复制 + 读写分离 | spring.datasource.dynamic |
| Redis | Cluster 模式,动态加节点 | 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 安全分层

15.2 令牌安全设计
- Token 刷新队列:并发 401 请求自动排队,不会重复刷新
- Token 黑名单:登出时 Token 加入 Redis 黑名单,TTL = Token 剩余有效期
- 设备指纹绑定:可选开启,Token 与 User-Agent + IP 前缀绑定
16. 性能优化
16.1 多级缓存策略

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 |
附录
术语表
| 术语 | 全称 | 说明 |
|---|---|---|
| RAG | Retrieval-Augmented Generation | 检索增强生成:从知识库检索相关内容,注入 LLM 上下文 |
| KAG | Knowledge-Augmented Generation | 知识增强生成:从知识图谱中检索实体关系,与 RAG 融合 |
| RRF | Reciprocal Rank Fusion | 倒数排名融合:融合向量检索和 BM25 检索结果的排序算法 |
| Snowflake | Snowflake ID | Twitter 雪花算法:分布式唯一 ID 生成方案 |
| RBAC | Role-Based Access Control | 基于角色的访问控制 |
| JWT | JSON Web Token | 无状态身份令牌 |
| HNSW | Hierarchical Navigable Small World | 分层导航小世界:高性能近似最近邻搜索算法 |
| STOMP | Streaming Text Oriented Messaging Protocol | 面向文本流的消息协议,用于 WebSocket 通信 |