1. 架构设计原则
1.1 设计目标
| 目标 | 描述 | 优先级 |
|---|---|---|
| 高可用性 | 系统可用性达到99.9%以上,支持故障自动转移 | P0 |
| 高性能 | 支持10000+并发用户,接口响应时间<500ms | P0 |
| 可扩展性 | 支持水平扩展,通过增加节点提升系统能力 | P0 |
| 安全性 | 企业级安全标准,数据加密、权限控制、审计追踪 | P0 |
| 可维护性 | 代码规范、文档完善、便于排查问题 | P1 |
| 成本优化 | 资源利用率最大化,降低运维成本 | P2 |
1.2 技术选型原则
- 成熟稳定:选择经过大规模生产验证的技术栈
- 社区活跃:优先选择社区活跃、文档完善的技术
- 云原生:支持容器化部署,适配Kubernetes
- 开源优先:优先选择开源方案,避免厂商锁定
- 团队熟悉:考虑团队技术栈熟悉程度
2. 总体架构设计
2.1 系统分层架构
┌─────────────────────────────────────────────────────────────────┐
│ 客户端层 │
│ Web浏览器 │ 移动APP │ 桌面客户端 │ 第三方集成 │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ 前端应用层(React + TypeScript) │
│ React 18 │ TypeScript 5 │ Vite 5 │ Ant Design 5 │
│ 首页/仪表盘 │ 文档中心 │ AI助手 │ 知识图谱 │ 管理后台 │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ CDN + 负载均衡 │
│ Cloudflare / Nginx / DNS轮询 │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ API网关层 │
│ Spring Cloud Gateway │ 限流熔断 │ 鉴权认证 │ 路由转发 │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ 应用服务层(简化版) │
├─────────────────────────────────────────────────────────────────┤
│ 用户权限服务 │ 文档服务 │ AI服务 │ 搜索服务 │ 文件服务│
│ 知识图谱服务 │ 统计服务 │ │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ 中间件层 │
├──────────────┬──────────────┬──────────────┬───────────────────┤
│ 消息队列 │ 分布式缓存 │ 分布式任务 │ 配置中心 │
│ RocketMQ │ Redis │ XXL-Job │ Nacos │
└──────────────┴──────────────┴──────────────┴───────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ 数据存储层 │
├──────────────┬──────────────┬──────────────┬───────────────────┤
│ 关系数据库 │ 搜索引擎 │ 向量数据库 │ 分布式文件存储 │
│ MySQL集群 │ Elasticsearch│ Milvus │ RustFS │
└──────────────┴──────────────┴──────────────┴───────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ 基础设施层 │
│ Kubernetes │ Docker │ 监控告警 │ 日志收集 │ 服务网格 │
└─────────────────────────────────────────────────────────────────┘2.2 微服务拆分架构
enterprise-knowledge-base/
├── frontend/ # 前端项目(React + TypeScript)
│ ├── src/
│ │ ├── assets/ # 静态资源
│ │ ├── components/ # 通用组件
│ │ ├── pages/ # 页面组件
│ │ ├── hooks/ # 自定义Hooks
│ │ ├── services/ # API服务
│ │ ├── stores/ # 状态管理
│ │ ├── types/ # TypeScript类型
│ │ ├── utils/ # 工具函数
│ │ └── router/ # 路由配置
│ ├── package.json
│ ├── vite.config.ts
│ └── tsconfig.json
│
├── gateway/ # API网关服务
│ └── gateway-service/ # 网关核心服务(统一入口)
│
├── services/ # 业务服务(简化版:7个核心服务)
│ ├── user-auth-service/ # 用户权限服务(合并用户+权限+团队)
│ │ ├── user-api/ # 用户API
│ │ ├── auth-core/ # 认证核心(JWT)
│ │ ├── permission-core/ # 权限核心(RBAC)
│ │ └── team-core/ # 团队/组织架构
│ │
│ ├── document-service/ # 文档服务(核心业务,含审核)
│ │ ├── document-api/ # 文档API
│ │ ├── document-core/ # 文档核心业务(CRUD)
│ │ ├── document-parser/ # 文档解析(Word/PDF等)
│ │ ├── document-version/ # 版本控制
│ │ ├── document-review/ # 文档审核(简化版审核流程)
│ │ ├── category-core/ # 分类管理(合并)
│ │ ├── tag-core/ # 标签管理(合并)
│ │ └── comment-core/ # 评论功能(合并)
│ │
│ ├── ai-service/ # AI智能服务(合并AI+向量)
│ │ ├── ai-api/ # AI API
│ │ ├── ai-core/ # AI核心(问答、摘要)
│ │ ├── rag-service/ # RAG检索增强
│ │ ├── vector-embed/ # 向量嵌入(千问)
│ │ └── vector-store/ # 向量存储(Milvus)
│ │
│ ├── search-service/ # 搜索服务
│ │ ├── search-api/ # 搜索API
│ │ ├── search-core/ # 全文搜索核心
│ │ └── search-index/ # ES索引构建
│ │
│ ├── file-service/ # 文件服务
│ │ ├── file-api/ # 文件API
│ │ ├── file-upload/ # 文件上传
│ │ ├── file-download/ # 文件下载
│ │ └── file-preview/ # 文件预览
│ │
│ ├── knowledge-graph-service/ # 知识图谱服务(保留独立)
│ │ ├── graph-api/ # 图谱API
│ │ ├── graph-engine/ # 图谱引擎(Neo4j)
│ │ └── relation-extract/ # 关系抽取
│ │
│ └── statistics-service/ # 统计服务(保留独立)
│ ├── statistics-api/ # 统计API
│ ├── metrics-collect/ # 指标收集
│ └── report-generate/ # 报表生成
│
├── common/ # 公共模块
│ ├── common-core/ # 核心公共模块
│ │ ├── id-generator/ # 分布式ID生成器
│ │ ├── json-util/ # JSON工具
│ │ ├── date-util/ # 日期工具
│ │ └── validation-util/ # 校验工具
│ │
│ ├── common-web/ # Web公共模块
│ │ ├── web-mvc/ # MVC配置
│ │ ├── web-exception/ # 异常处理
│ │ └── web-interceptor/ # 拦截器
│ │
│ ├── common-security/ # 安全公共模块
│ │ ├── security-jwt/ # JWT工具
│ │ ├── security-encryption/ # 加密工具
│ │ └── security-permission/ # 权限注解
│ │
│ ├── common-database/ # 数据库公共模块
│ │ ├── mybatis-plus/ # MyBatis Plus封装
│ │ ├── database-multitenant/ # 多租户
│ │ └── database-sharding/ # 分库分表
│ │
│ ├── common-redis/ # Redis公共模块
│ │ ├── redis-cache/ # 缓存实现
│ │ ├── redis-lock/ # 分布式锁
│ │ └── redis-limit/ # 限流实现
│ │
│ ├── common-mq/ # 消息队列公共模块
│ │ ├── rocketmq-producer/ # 生产者
│ │ └── rocketmq-consumer/ # 消费者
│ │
│ ├── common-feign/ # Feign公共模块
│ │ ├── feign-builder/ # Feign构建器
│ │ └── feign-fallback/ # 降级处理
│ │
│ ├── common-langchain4j/ # LangChain4j公共模块
│ │ ├── qwen-chat/ # 千问聊天模型
│ │ ├── qwen-embed/ # 千问嵌入模型
│ │ └── milvus-store/ # Milvus向量存储
│ │
│ └── common-rustfs/ # RustFS公共模块
│ ├── rustfs-client/ # RustFS客户端
│ ├── rustfs-upload/ # 上传实现
│ └── rustfs-download/ # 下载实现
│
├── infrastructure/ # 基础设施
│ ├── registry/ # 注册中心
│ ├── gateway/ # 网关配置
│ ├── monitoring/ # 监控配置
│ └── logging/ # 日志配置
│
└── deployment/ # 部署配置
├── docker/ # Docker配置
├── kubernetes/ # K8s配置
└── helm/ # Helm Charts2.3 微服务职责说明
2.3.1 服务合并说明
| 原服务 | 合并到 | 合并原因 |
|---|---|---|
| 用户服务 + 权限服务 + 团队服务 | user-auth-service | 认证授权强相关,频繁交互,合并减少RPC调用 |
| 分类服务 + 标签服务 + 评论服务 + 工作流服务 | document-service | 文档周边功能+简单审核,数据量不大,合并简化架构 |
| AI服务 + 向量服务 | ai-service | 向量是AI的基础能力,强依赖关系 |
| 通知服务 | 内嵌到各服务 | 通知逻辑简单,可通过MQ异步处理 |
| 监控服务 | 基础设施层 | 使用SkyWalking等开源方案,无需自建服务 |
审核流程简化:
- 工作流服务已取消,文档审核功能内嵌到文档服务
- 采用简单状态机实现审核流程:草稿→待审核→已发布/已驳回
- 无复杂工作流引擎,降低系统复杂度
2.3.2 核心服务职责
| 服务名称 | 服务标识 | 核心职责 | 数据库 |
|---|---|---|---|
| 用户权限服务 | user-auth-service | 用户管理、JWT认证、RBAC权限控制、组织架构/团队管理 | kb\_user\_auth |
| 文档服务 | document-service | 文档CRUD、分类管理、标签管理、评论功能、版本控制、文档解析、文档审核 | kb\_document |
| AI服务 | ai-service | AI问答、文档摘要、RAG检索、向量嵌入、向量存储、语义搜索 | kb\_vector |
| 搜索服务 | search-service | 全文检索、搜索建议、高级筛选、ES索引管理 | kb\_search |
| 文件服务 | file-service | 文件上传下载、文件预览、格式转换 | kb\_file |
| 知识图谱服务 | knowledge-graph-service | 实体关系抽取、图谱可视化、关系分析、图数据库操作 | kb\_graph |
| 统计服务 | statistics-service | 数据统计、指标收集、报表生成、数据可视化 | kb\_statistics |
2.3.3 服务间调用关系
┌─────────────┐
│ Gateway │ (API网关 - 统一入口)
└──────┬──────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌──────────────┐
│user-auth-svc │ │document-svc │ │ ai-service │
│ (认证授权) │ │ (核心业务) │ │ (AI能力) │
└───────────────┘ └───────┬──────┘ └──────┬───────┘
│ │
│ ┌────────────┘
│ │
┌──────────────────┼────┼──────────────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌──────────────┐
│search-service │ │file-service │ │knowledge-graph│
│ (全文搜索) │ │ (文件管理) │ │ (图谱) │
└───────────────┘ └──────────────┘ └──────┬───────┘
│
┌────────────────────────────────────┘
│
▼
┌───────────────┐
│statistics-svc │ (独立运行,定期收集数据)
│ (数据统计) │
└───────────────┘调用说明:
- Gateway:所有外部请求的统一入口,负责路由、限流、鉴权
- user-auth-service:其他服务调用此服务验证用户身份和权限
- document-service:核心业务服务,包含简化版审核功能(状态机)
- ai-service:被document-service调用提供AI能力
- search-service:被document-service调用同步搜索索引
- knowledge-graph-service:被document-service调用构建知识图谱
- statistics-service:独立运行,定期从各服务收集数据
2.3.4 服务数据交互方式
| 交互类型 | 技术方案 | 说明 |
|---|---|---|
| 同步调用 | OpenFeign + Sentinel | 服务间同步RPC调用,带熔断降级 |
| 异步消息 | RocketMQ | 解耦服务,削峰填谷 |
| 数据共享 | MySQL | 核心数据存储在各自服务的数据库 |
| 缓存共享 | Redis | 会话、分布式锁、热点数据缓存 |
2.4 前端架构设计
前端定位:采用React + TypeScript + Vite的现代化前端技术栈,结合企业级UI组件库。
2.4.1 前端技术栈
| 技术分类 | 技术选型 | 版本 | 说明 |
|---|---|---|---|
| 核心框架 | React | 18.x | UI框架 |
| 开发语言 | TypeScript | 5.x | 类型安全 |
| 构建工具 | Vite | 5.x | 快速构建 |
| UI组件库 | Ant Design | 5.x | 企业级UI组件 |
| 状态管理 | Zustand / Jotai | 4.x | 轻量级状态管理 |
| 路由 | React Router | 6.x | 客户端路由 |
| HTTP客户端 | Axios | 1.x | 请求封装 |
| Markdown | react-markdown | 9.x | Markdown渲染 |
| 代码编辑器 | CodeMirror 6 | - | 代码编辑 |
| 图表库 | ECharts for React | 6.x | 数据可视化 |
| 表单处理 | React Hook Form | 7.x | 高性能表单 |
| 日期处理 | Day.js | 1.x | 日期工具 |
| CSS方案 | CSS Modules / Tailwind CSS | 3.x | 样式隔离 |
| 图标库 | @ant-design/icons | 5.x | 图标组件 |
| 工具库 | lodash-es | 4.x | 工具函数 |
2.4.2 前端项目结构
enterprise-knowledge-base-frontend/
├── public/ # 静态资源
│ ├── favicon.ico
│ └── logo.png
│
├── src/ # 源代码
│ ├── assets/ # 资源文件
│ │ ├── images/ # 图片
│ │ ├── icons/ # SVG图标
│ │ └── styles/ # 全局样式
│ │ ├── variables.css # CSS变量(设计令牌)
│ │ ├── global.css # 全局样式
│ │ └── reset.css # 样式重置
│ │
│ ├── components/ # 通用组件
│ │ ├── Layout/ # 布局组件
│ │ │ ├── Navbar.tsx # 导航栏
│ │ │ ├── Sidebar.tsx # 侧边栏
│ │ │ └── Footer.tsx # 页脚
│ │ ├── Button/ # 按钮
│ │ ├── Card/ # 卡片
│ │ ├── Table/ # 表格
│ │ ├── Form/ # 表单
│ │ ├── Modal/ # 模态框
│ │ ├── Notification/ # 通知
│ │ └── Dropdown/ # 下拉菜单
│ │
│ ├── pages/ # 页面组件
│ │ ├── Dashboard/ # 仪表盘
│ │ │ ├── index.tsx
│ │ │ └── components/ # 页面私有组件
│ │ ├── Documents/ # 文档中心
│ │ │ ├── index.tsx
│ │ │ ├── DocumentList.tsx
│ │ │ └── DocumentCard.tsx
│ │ ├── DocumentCreate/ # 新建文档
│ │ │ ├── index.tsx
│ │ │ ├── MarkdownEditor.tsx
│ │ │ └── PreviewPanel.tsx
│ │ ├── DocumentDetail/ # 文档详情
│ │ ├── DocumentImport/ # 导入文档
│ │ ├── Search/ # 搜索
│ │ ├── AIAssistant/ # AI助手
│ │ ├── KnowledgeGraph/ # 知识图谱
│ │ ├── UserProfile/ # 个人中心
│ │ └── Admin/ # 管理后台
│ │
│ ├── hooks/ # 自定义Hooks
│ │ ├── useAuth.ts # 认证Hook
│ │ ├── useRequest.ts # 请求Hook
│ │ ├── useDocument.ts # 文档Hook
│ │ └── useWebSocket.ts # WebSocket Hook
│ │
│ ├── services/ # API服务
│ │ ├── api.ts # API基础配置
│ │ ├── auth.service.ts # 认证服务
│ │ ├── document.service.ts # 文档服务
│ │ ├── ai.service.ts # AI服务
│ │ └── user.service.ts # 用户服务
│ │
│ ├── stores/ # 状态管理
│ │ ├── auth.store.ts # 认证状态
│ │ ├── document.store.ts # 文档状态
│ │ └── ui.store.ts # UI状态
│ │
│ ├── types/ # TypeScript类型定义
│ │ ├── api.d.ts # API类型
│ │ ├── document.d.ts # 文档类型
│ │ └── user.d.ts # 用户类型
│ │
│ ├── utils/ # 工具函数
│ │ ├── request.ts # 请求封装
│ │ ├── storage.ts # 存储封装
│ │ ├── format.ts # 格式化工具
│ │ └── validate.ts # 验证工具
│ │
│ ├── router/ # 路由配置
│ │ ├── index.tsx # 路由入口
│ │ └── routes.tsx # 路由配置
│ │
│ ├── App.tsx # 根组件
│ └── main.tsx # 应用入口
│
├── package.json
├── tsconfig.json # TypeScript配置
├── vite.config.ts # Vite配置
└── tailwind.config.js # Tailwind配置2.4.3 企业级设计系统
设计原则:
- 一致性:统一的视觉语言和交互模式
- 可访问性:符合WCAG 2.1 AA标准
- 响应式:支持桌面、平板、移动端
- 性能:组件懒加载、代码分割
设计令牌配置:
| 配置类别 | 配置项 | 示例值 |
|---|---|---|
| 颜色系统 | 主题色 | Primary (10级色阶)、Success、Warning、Danger |
| 间距系统 | spacing scale | 1-12级递增间距(4px-48px) |
| 字体大小 | fontSize | xs/sm/base/lg/xl/2xl/3xl/4xl |
| 圆角 | borderRadius | sm/md/lg/xl/2xl |
设计系统特点:
- 统一的色彩体系,支持浅色/深色主题
- 响应式间距系统,适配不同屏幕尺寸
- 可复用的组件样式库
组件体系(基于Ant Design扩展):
- 布局组件:Navbar、Sidebar、Footer
- 数据展示:Card、Table、List、Tree
- 表单组件:Input、Select、DatePicker、Upload
- 反馈组件:Modal、Message、Notification、Drawer
- 导航组件:Tabs、Breadcrumb、Pagination
- 业务组件:MarkdownEditor、DocumentViewer、KnowledgeGraph
2.4.4 前端页面清单
| 页面名称 | 路由路径 | 组件文件 | 功能说明 | 权限要求 |
|---|---|---|---|---|
| 首页/仪表盘 | / | pages/Dashboard | 数据概览、快捷操作、统计图表 | 所有用户 |
| 文档中心 | /documents | pages/Documents | 文档列表、筛选、搜索、操作 | 所有用户 |
| 新建文档 | /documents/new | pages/DocumentCreate | Markdown编辑器、实时预览 | 登录用户 |
| 文档详情 | /documents/:id | pages/DocumentDetail | 文档内容、评论、版本历史 | 所有用户 |
| 导入文档 | /documents/import | pages/DocumentImport | 文件上传、格式转换 | 登录用户 |
| 搜索页面 | /search | pages/Search | 全文搜索、高级筛选 | 所有用户 |
| AI助手 | /ai | pages/AIAssistant | 智能问答、文档摘要 | 登录用户 |
| 知识图谱 | /knowledge-graph | pages/KnowledgeGraph | 实体关系可视化 | 所有用户 |
| 个人中心 | /profile | pages/UserProfile | 个人信息、头像、偏好设置 | 登录用户 |
| 管理中心 | /admin/* | pages/Admin | 用户管理、分类管理、系统设置 | 管理员 |
| 登录页面 | /login | pages/Login | 用户登录 | 未登录用户 |
2.4.5 前后端交互方式
API服务架构:
| 功能模块 | 说明 |
|---|---|
| 请求封装 | 基于Axios,支持请求/响应拦截器 |
| 类型定义 | TypeScript接口定义,确保类型安全 |
| 错误处理 | 统一错误处理机制,自动重试 |
| 认证管理 | JWT Token自动注入和刷新 |
服务方法:
- GET: 获取数据
- POST: 创建资源
- PUT: 更新资源
- DELETE: 删除资源
业务服务架构:
| 服务类型 | 功能 | 说明 |
|---|---|---|
| 文档服务 | getList | 获取文档列表,支持分页和筛选 |
| getDetail | 获取文档详情 | |
| create | 创建新文档 | |
| update | 更新文档内容 | |
| delete | 删除文档 | |
| submitReview | 提交文档审核 | |
| 用户服务 | login | 用户登录 |
| logout | 用户登出 | |
| getProfile | 获取用户信息 | |
| 搜索服务 | search | 全文搜索 |
| advancedSearch | 高级搜索 |
服务设计原则:
- RESTful风格
- TypeScript类型定义
- 统一错误处理
自定义Hooks架构:
| Hook名称 | 用途 | 返回值 |
|---|---|---|
| useRequest | 数据请求 | data, loading, error, refetch |
| useAuth | 认证状态 | user, token, login, logout |
| useDocument | 文档操作 | 文档CRUD方法 |
| useSearch | 搜索功能 | 搜索结果和方法 |
Hooks设计原则:
- 单一职责,每个Hook专注一个功能
- 可复用性,支持参数化配置
- 响应式更新,自动触发重渲染
认证方式:
- JWT Token存储在localStorage
- Axios拦截器自动添加Token到请求头
- Token过期自动跳转登录页
- 使用Zustand管理全局认证状态
数据格式:
- 请求格式:JSON
- 响应格式:
{ code, message, data } - TypeScript类型定义确保类型安全
- 统一错误处理
3. 核心技术架构
3.1 分布式ID方案
3.1.1 ID设计要求
| 要求 | 说明 |
|---|---|
| 全局唯一 | 分布式环境下ID必须全局唯一 |
| 趋势递增 | 保证ID大致按时间递增,利于索引 |
| 高性能 | ID生成不能成为性能瓶颈 |
| 高可用 | ID生成服务必须高可用 |
| 信息承载 | ID中可包含时间、机器等元信息 |
3.1.2 雪花算法(Snowflake)实现
雪花算法实现说明:
| 组成部分 | 位数 | 说明 | 取值范围 |
|---|---|---|---|
| 符号位 | 1位 | 固定为0 | - |
| 时间戳 | 41位 | 毫秒级时间戳 | 可使用69年 |
| 数据中心ID | 5位 | 数据中心标识 | 0-31 |
| 机器ID | 5位 | 工作节点标识 | 0-31 |
| 序列号 | 12位 | 毫秒内序列 | 0-4095 |
核心特性:
- 全局唯一:分布式环境下保证ID唯一性
- 趋势递增:ID按时间大致递增,利于索引
- 高性能:本地生成,无网络开销
- 高可用:支持时钟回拨检测和容错
关键实现逻辑:
- 时钟回拨检测:检测并处理时钟回拨问题
- 序列号溢出处理:同一毫秒内序列号溢出时等待下一毫秒
- 并发控制:使用synchronized保证线程安全
3.1.3 业务ID规则
| 业务类型 | ID前缀 | 示例 | 说明 |
|---|---|---|---|
| 用户 | U | U123456789012345678 | User |
| 文档 | D | D123456789012345678 | Document |
| 分类 | C | C123456789012345678 | Category |
| 标签 | T | T123456789012345678 | Tag |
| 团队 | TM | TM123456789012345678 | Team |
| 评论 | CM | CM123456789012345678 | Comment |
| 审核记录 | AR | AR123456789012345678 | Approval Record |
| 通知 | N | N123456789012345678 | Notification |
3.1.4 业务ID生成器
雪花算法实现说明:
| 组成部分 | 位数 | 说明 | 取值范围 |
|---|---|---|---|
| 符号位 | 1位 | 固定为0 | - |
| 时间戳 | 41位 | 毫秒级时间戳 | 可使用69年 |
| 数据中心ID | 5位 | 数据中心标识 | 0-31 |
| 机器ID | 5位 | 工作节点标识 | 0-31 |
| 序列号 | 12位 | 毫秒内序列 | 0-4095 |
核心特性:
- 全局唯一:分布式环境下保证ID唯一性
- 趋势递增:ID按时间大致递增,利于索引
- 高性能:本地生成,无网络开销
- 高可用:支持时钟回拨检测和容错
关键实现逻辑:
- 时钟回拨检测:检测并处理时钟回拨问题
- 序列号溢出处理:同一毫秒内序列号溢出时等待下一毫秒
- 并发控制:使用synchronized保证线程安全
3.2 服务间通信架构
3.2.1 同步调用 - OpenFeign
同步通信架构:
| 特性 | 说明 |
|---|---|
| 声明式HTTP客户端 | 使用接口+注解定义服务调用 |
| 负载均衡 | 集成Ribbon,支持轮询、随机等策略 |
| 熔断降级 | 集成Resilience4j,防止雪崩 |
| 超时控制 | 连接超时、读取超时可配置 |
| 日志追踪 | 集成SkyWalking实现链路追踪 |
服务调用流程:
- 服务A通过Feign客户端调用服务B
- 请求经过负载均衡器选择实例
- 发起HTTP调用,携带认证Token
- 服务B处理并返回响应
- 如遇异常,触发熔断或重试
3.2.2 异步消息 - RocketMQ
RocketMQ配置说明:
| 配置项 | 配置内容 | 说明 |
|---|---|---|
| NameServer | 192.168.1.100:9876;192.168.1.101:9876 | MQ服务地址,集群部署 |
| Producer Group | knowledge-base-producer-group | 生产者组标识 |
| 消息超时 | 3000ms | 发送超时时间 |
| 重试次数 | 2次 | 发送失败重试 |
| 消息大小 | 4MB | 单条消息最大限制 |
| 消费者组 | knowledge-base-consumer-group | 消费者组标识 |
| 消费线程 | 5-20 | 最小/最大消费线程数 |
| 消费超时 | 15分钟 | 单条消息消费超时 |
| 最大重试 | 3次 | 消费失败重试次数 |
安全配置:
- AccessKey/SecretKey:生产环境从环境变量读取
- 消息轨迹:启用消息追踪,便于问题排查
消息生产者架构:
| 组件类型 | 说明 | 使用场景 |
|---|---|---|
| 同步发送 | syncSend,等待Broker确认 | 关键业务消息 |
| 异步发送 | asyncSend,回调通知 | 非关键业务,提升性能 |
| 单向发送 | oneway,不等待确认 | 日志收集等低可靠性要求 |
消息消费者架构:
| 消费模式 | 说明 | 适用场景 |
|---|---|---|
| 并发消费 | 多线程并行消费 | 提升吞吐量 |
| 顺序消费 | 单线程顺序消费 | 需要严格顺序的消息 |
| 消费重试 | 失败自动重试 | 处理临时故障 |
3.3 分布式事务方案
3.3.1 Seata配置
Seata分布式事务配置:
| 配置项 | 说明 | 推荐值 |
|---|---|---|
| 事务模式 | AT/TCC/Saga | AT(默认) |
| 服务地址 | TC集群地址 | seata-server:8091 |
| 数据源 | 需要undo\_log表 | MySQL |
| 超时时间 | 全局事务超时 | 60秒 |
| 重试次数 | 失败重试次数 | 3次 |
AT模式特点:
- 无侵入:只需要注解@GlobalTransactional
- 自动回滚:自动生成undo\_log
- 两阶段提交:自动管理分支事务
3.3.2 TCC模式实现
TCC事务模式架构:
| 阶段 | 说明 | 实现要点 |
|---|---|---|
| Try | 预留资源 | 检查资源、锁定资源 |
| Confirm | 确认提交 | 释放锁定,完成事务 |
| Cancel | 取消回滚 | 释放资源,回滚操作 |
TCC实现要求:
- 幂等性:每个阶段支持重复调用
- 无悬挂:Cancel不能先于Try执行
- 防空回滚:Try未执行不能Cancel
4. 数据架构设计
4.1 数据分层存储
┌─────────────────────────────────────────────────────────┐
│ 应用层 │
│ 业务逻辑处理、数据转换、权限控制 │
└─────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼──────┐ ┌───▼────┐ ┌──────▼──────┐
│ MySQL │ │ Redis │ │Elasticsearch│
│ (主数据) │ │ (缓存) │ │ (搜索) │
└──────────────┘ └────────┘ └─────────────┘
│ │ │
┌───────▼─────────────▼────────────────▼───────────┐
│ Milvus向量数据库 │
│ (语义搜索、相似度计算) │
└─────────────────────────────────────────────────┘
│
┌───────▼──────────────────────────────────────────┐
│ RustFS文件存储 │
│ (原始文件、附件、图片) │
└─────────────────────────────────────────────────┘4.2 数据流转架构
数据流向说明:
| 数据流向 | 说明 | 技术实现 |
|---|---|---|
| 写入流程 | 应用→MySQL→Redis | 主从同步,缓存更新 |
| 读取流程 | Redis→MySQL | 缓存优先,缓存未命中回源 |
| 搜索流程 | 应用→Elasticsearch | 异步同步索引 |
| 向量化流程 | 文档→Embedding→Milvus | 定时任务向量化 |
| 文件存储 | 上传→RustFS→返回URL | 分布式文件存储 |
数据一致性保障:
- 写入:先写MySQL,成功后更新Redis
- 读取:先读Redis,未命中读MySQL并回填缓存
- 同步:MQ异步同步到Elasticsearch和Milvus
- 文件:先上传文件,获取URL后存入数据库
4.3 缓存架构
Redis缓存设计:
| 缓存类型 | Key设计 | 过期策略 | 说明 |
|---|---|---|---|
| 数据缓存 | entity:id:{id} | 30分钟 | 实体数据缓存 |
| 列表缓存 | list:page:{page} | 5分钟 | 列表数据缓存 |
| 计数器 | counter:{type}:{id} | 永久 | 访问计数 |
| 分布式锁 | lock:{resource}:{id} | 自动过期 | 并发控制 |
缓存策略:
- Cache-Aside:旁路缓存模式
- 缓存预热:系统启动时加载热点数据
- 缓存更新:数据变更时主动更新缓存
- 缓存穿透:布隆过滤器防护
- 缓存雪崩:过期时间加随机值
5. AI服务架构
5.1 LangChain4j集成架构
AI框架集成:
| 组件 | 说明 | 用途 |
|---|---|---|
| ChatLanguageModel | 大语言模型接口 | 对话、问答 |
| EmbeddingModel | 向量嵌入模型 | 文本向量化 |
| ContentRetriever | 内容检索器 | RAG检索 |
| TokenStream | Token流处理 | 流式输出 |
大模型配置:
- 模型选择:通义千问 qwen-max
- API密钥:从环境变量读取
- 温度参数:0.7(平衡创造性和准确性)
- Token限制:4096
5.2 RAG服务实现
RAG架构设计:
| 步骤 | 组件 | 说明 |
|---|---|---|
| 文档分块 | TextSplitter | 按段落或固定长度分块 |
| 向量化 | EmbeddingModel | 生成向量嵌入 |
| 存储向量 | Milvus | 存储和检索向量 |
| 相似检索 | VectorSearch | 检索TopK相关文档 |
| 上下文组装 | ContextAssembler | 组装Prompt上下文 |
| 生成回答 | LLM | 基于上下文生成答案 |
RAG优化策略:
- 混合检索:向量检索+关键词检索
- 重排序:对检索结果重新排序
- 上下文窗口:动态调整上下文长度
- 答案溯源:返回答案来源文档
6. 安全架构设计
6.1 认证授权架构
认证方案:
| 认证方式 | 说明 | 使用场景 |
|---|---|---|
| JWT认证 | 无状态Token认证 | 前后端分离场景 |
| Session认证 | 有状态会话管理 | 传统Web应用 |
| OAuth2.0 | 第三方登录 | 集成外部系统 |
| API Key | API密钥认证 | 服务间调用 |
授权模型:
- RBAC:基于角色的访问控制
- 权限粒度:模块->功能->操作
- 数据权限:支持行级数据权限控制
安全措施:
- 密码加密:BCrypt哈希算法
- Token有效期:2小时,可刷新
- 防暴力破解:登录失败5次锁定10分钟
- 单点登录:支持SSO
6.2 数据加密架构
加密策略:
| 数据类型 | 加密方式 | 密钥管理 |
|---|---|---|
| 传输加密 | HTTPS/TLS 1.3 | SSL证书 |
| 存储加密 | AES-256 | 密钥管理服务(KMS) |
| 敏感字段 | 字段级加密 | 应用层密钥 |
| 签名验签 | RSA-2048 | 非对称密钥对 |
加密实现:
- 数据库连接:SSL加密
- 配置文件:敏感信息加密存储
- 日志脱敏:手机号、身份证号脱敏
- 密钥轮换:定期更新加密密钥
7. 监控与运维架构
7.1 监控体系
┌─────────────────────────────────────────────────────────┐
│ 监控数据采集层 │
│ 应用指标 │ 系统指标 │ 业务指标 │ 日志 │
└─────────────────────────────────────────────────────────┘
│
┌───────────────┴───────────────┐
│ │
┌───────▼───────────────────────────────▼───────┐
│ SkyWalking OAP Server │
│ (链路追踪 + 指标 + 日志) │
└─────────────────────────────────────────────┘
│
┌───────────────┴───────────────┐
│ │ │
┌───────▼────┐ ┌───────▼────┐ ┌───────▼────┐
│ Prometheus │ │ Grafana │ │ AlertMgr │
│ (指标存储) │ │ (可视化) │ │ (告警) │
└─────────────┘ └─────────────┘ └─────────────┘7.2 SkyWalking链路追踪
链路追踪架构:
| 追踪层次 | 监控内容 | 说明 |
|---|---|---|
| 服务层 | 服务拓扑 | 服务之间的调用关系 |
| 接口层 | 接口性能 | 响应时间、吞吐量、错误率 |
| 数据库层 | SQL性能 | 慢查询、调用次数 |
| 缓存层 | 缓存命中率 | Redis缓存效率 |
| 消息层 | 消息队列 | MQ发送/消费性能 |
追踪配置要点:
- 采样率:生产环境10%,开发环境100%
- 慢查询阈值:数据库查询超过1秒
- 告警规则:错误率超过5%触发告警
- 数据保留:链路数据保留7天
7.3 监控数据采集配置
MyBatis映射说明:
| 映射类型 | 说明 |
|---|---|
| ResultMap | 结果集映射,定义字段映射关系 |
| SQL片段 | 可复用的SQL片段 |
| 动态SQL | if/choose/foreach等动态查询 |
| 关联查询 | 一对一、一对多关联映射 |
映射优化:
- 使用和避免SQL语法错误
- 批量操作使用foreach循环
- 复杂查询使用SQL片段提高复用性
注:完整映射文件请参考项目源码
MyBatis映射说明:
| 映射类型 | 说明 |
|---|---|
| ResultMap | 结果集映射,定义字段映射关系 |
| SQL片段 | 可复用的SQL片段 |
| 动态SQL | if/choose/foreach等动态查询 |
| 关联查询 | 一对一、一对多关联映射 |
映射优化:
- 使用和避免SQL语法错误
- 批量操作使用foreach循环
- 复杂查询使用SQL片段提高复用性
注:完整映射文件请参考项目源码
7.4 微服务监控配置
RocketMQ配置说明:
| 配置项 | 配置内容 | 说明 |
|---|---|---|
| NameServer | 192.168.1.100:9876;192.168.1.101:9876 | MQ服务地址,集群部署 |
| Producer Group | knowledge-base-producer-group | 生产者组标识 |
| 消息超时 | 3000ms | 发送超时时间 |
| 重试次数 | 2次 | 发送失败重试 |
| 消息大小 | 4MB | 单条消息最大限制 |
| 消费者组 | knowledge-base-consumer-group | 消费者组标识 |
| 消费线程 | 5-20 | 最小/最大消费线程数 |
| 消费超时 | 15分钟 | 单条消息消费超时 |
| 最大重试 | 3次 | 消费失败重试次数 |
安全配置:
- AccessKey/SecretKey:生产环境从环境变量读取
- 消息轨迹:启用消息追踪,便于问题排查
7.5 性能监控配置
监控指标采集:
| 指标类型 | 采集内容 | 采集频率 | 说明 |
|---|---|---|---|
| JVM指标 | 堆内存、GC、线程 | 10秒 | JVM运行状态 |
| 应用指标 | QPS、RT、错误率 | 10秒 | 应用性能指标 |
| 数据库指标 | 连接数、慢查询 | 30秒 | 数据库性能 |
| 缓存指标 | 命中率、内存使用 | 30秒 | 缓存效率 |
| 系统指标 | CPU、内存、磁盘 | 10秒 | 服务器资源 |
告警规则:
- 应用错误率 > 5%
- 接口响应时间 > 3秒
- 数据库连接池使用率 > 80%
- Redis内存使用率 > 85%
- 服务器CPU使用率 > 80%(持续5分钟)
8. 部署架构
8.1 Kubernetes部署
配置说明:
| 配置项 | 说明 |
|---|---|
| 基础配置 | 服务端口、应用名称等 |
| 数据源配置 | 数据库连接信息 |
| 缓存配置 | Redis连接配置 |
| 消息队列配置 | MQ连接配置 |
注:完整配置请参考项目配置文件
8.2 SkyWalking部署配置
配置说明:
| 配置项 | 说明 |
|---|---|
| 基础配置 | 服务端口、应用名称等 |
| 数据源配置 | 数据库连接信息 |
| 缓存配置 | Redis连接配置 |
| 消息队列配置 | MQ连接配置 |
注:完整配置请参考项目配置文件
8.3 服务网格配置
配置说明:
| 配置项 | 说明 |
|---|---|
| 基础配置 | 服务端口、应用名称等 |
| 数据源配置 | 数据库连接信息 |
| 缓存配置 | Redis连接配置 |
| 消息队列配置 | MQ连接配置 |
注:完整配置请参考项目配置文件
9. 附录
9.1 技术栈总览
| 分类 | 技术选型 | 版本 | 说明 |
|---|---|---|---|
| 后端开发 | |||
| 开发语言 | Java | 21 LTS | 虚拟线程、记录模式 |
| 应用框架 | Spring Boot | 3.5 | 最新稳定版 |
| 微服务框架 | Spring Cloud | 2024.x | Greenwich |
| 前端开发 | |||
| 核心框架 | React | 18.x | UI框架 |
| 开发语言 | TypeScript | 5.x | 类型安全 |
| 构建工具 | Vite | 5.x | 快速构建 |
| UI组件库 | Ant Design | 5.x | 企业级组件 |
| 状态管理 | Zustand | 4.x | 轻量状态管理 |
| 路由 | React Router | 6.x | 客户端路由 |
| 图表库 | ECharts for React | 6.x | 数据可视化 |
| 代码编辑器 | CodeMirror 6 | - | Markdown编辑 |
| 数据存储 | |||
| 数据库 | MySQL | 8.0 | 主数据库 |
| 缓存 | Redis | 7.2 | 缓存、分布式锁 |
| 搜索 | Elasticsearch | 8.x | 全文检索 |
| 向量数据库 | Milvus | 2.4 | 语义搜索 |
| 图数据库 | Neo4j | 5.x | 知识图谱 |
| 文件存储 | RustFS | 最新 | 分布式文件存储 |
| 中间件 | |||
| 消息队列 | RocketMQ | 5.3 | 消息队列 |
| 分布式事务 | Seata | 2.x | AT/TCC模式 |
| 注册中心 | Nacos | 2.x | 服务注册发现 |
| 配置中心 | Nacos | 2.x | 配置管理 |
| API网关 | Spring Cloud Gateway | 4.x | 网关 |
| 基础设施 | |||
| 容器编排 | Kubernetes | 1.28.x | 容器编排 |
| 监控 | Prometheus | 2.47.x | 指标收集 |
| 可视化 | Grafana | 10.x | 监控面板 |
| 日志 | ELK Stack | 8.x | 日志分析 |
| 链路追踪 | SkyWalking | 8.16.x | 分布式追踪 |
| AI能力 | |||
| AI编排 | LangChain4j | 0.35.x | AI框架 |
| 大模型 | 通义千问 | qwen-max | 大语言模型 |