1. 架构设计原则

1.1 设计目标

目标描述优先级
高可用性系统可用性达到99.9%以上,支持故障自动转移P0
高性能支持10000+并发用户,接口响应时间<500msP0
可扩展性支持水平扩展,通过增加节点提升系统能力P0
安全性企业级安全标准,数据加密、权限控制、审计追踪P0
可维护性代码规范、文档完善、便于排查问题P1
成本优化资源利用率最大化,降低运维成本P2

1.2 技术选型原则

  1. 成熟稳定:选择经过大规模生产验证的技术栈
  2. 社区活跃:优先选择社区活跃、文档完善的技术
  3. 云原生:支持容器化部署,适配Kubernetes
  4. 开源优先:优先选择开源方案,避免厂商锁定
  5. 团队熟悉:考虑团队技术栈熟悉程度

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 Charts

2.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-serviceAI问答、文档摘要、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 前端技术栈

技术分类技术选型版本说明
核心框架React18.xUI框架
开发语言TypeScript5.x类型安全
构建工具Vite5.x快速构建
UI组件库Ant Design5.x企业级UI组件
状态管理Zustand / Jotai4.x轻量级状态管理
路由React Router6.x客户端路由
HTTP客户端Axios1.x请求封装
Markdownreact-markdown9.xMarkdown渲染
代码编辑器CodeMirror 6-代码编辑
图表库ECharts for React6.x数据可视化
表单处理React Hook Form7.x高性能表单
日期处理Day.js1.x日期工具
CSS方案CSS Modules / Tailwind CSS3.x样式隔离
图标库@ant-design/icons5.x图标组件
工具库lodash-es4.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 scale1-12级递增间距(4px-48px)
字体大小fontSizexs/sm/base/lg/xl/2xl/3xl/4xl
圆角borderRadiussm/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数据概览、快捷操作、统计图表所有用户
文档中心/documentspages/Documents文档列表、筛选、搜索、操作所有用户
新建文档/documents/newpages/DocumentCreateMarkdown编辑器、实时预览登录用户
文档详情/documents/:idpages/DocumentDetail文档内容、评论、版本历史所有用户
导入文档/documents/importpages/DocumentImport文件上传、格式转换登录用户
搜索页面/searchpages/Search全文搜索、高级筛选所有用户
AI助手/aipages/AIAssistant智能问答、文档摘要登录用户
知识图谱/knowledge-graphpages/KnowledgeGraph实体关系可视化所有用户
个人中心/profilepages/UserProfile个人信息、头像、偏好设置登录用户
管理中心/admin/*pages/Admin用户管理、分类管理、系统设置管理员
登录页面/loginpages/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年
数据中心ID5位数据中心标识0-31
机器ID5位工作节点标识0-31
序列号12位毫秒内序列0-4095

核心特性:

  • 全局唯一:分布式环境下保证ID唯一性
  • 趋势递增:ID按时间大致递增,利于索引
  • 高性能:本地生成,无网络开销
  • 高可用:支持时钟回拨检测和容错

关键实现逻辑:

  • 时钟回拨检测:检测并处理时钟回拨问题
  • 序列号溢出处理:同一毫秒内序列号溢出时等待下一毫秒
  • 并发控制:使用synchronized保证线程安全

3.1.3 业务ID规则

业务类型ID前缀示例说明
用户UU123456789012345678User
文档DD123456789012345678Document
分类CC123456789012345678Category
标签TT123456789012345678Tag
团队TMTM123456789012345678Team
评论CMCM123456789012345678Comment
审核记录ARAR123456789012345678Approval Record
通知NN123456789012345678Notification

3.1.4 业务ID生成器

雪花算法实现说明:

组成部分位数说明取值范围
符号位1位固定为0-
时间戳41位毫秒级时间戳可使用69年
数据中心ID5位数据中心标识0-31
机器ID5位工作节点标识0-31
序列号12位毫秒内序列0-4095

核心特性:

  • 全局唯一:分布式环境下保证ID唯一性
  • 趋势递增:ID按时间大致递增,利于索引
  • 高性能:本地生成,无网络开销
  • 高可用:支持时钟回拨检测和容错

关键实现逻辑:

  • 时钟回拨检测:检测并处理时钟回拨问题
  • 序列号溢出处理:同一毫秒内序列号溢出时等待下一毫秒
  • 并发控制:使用synchronized保证线程安全

3.2 服务间通信架构

3.2.1 同步调用 - OpenFeign

同步通信架构:

特性说明
声明式HTTP客户端使用接口+注解定义服务调用
负载均衡集成Ribbon,支持轮询、随机等策略
熔断降级集成Resilience4j,防止雪崩
超时控制连接超时、读取超时可配置
日志追踪集成SkyWalking实现链路追踪

服务调用流程:

  1. 服务A通过Feign客户端调用服务B
  2. 请求经过负载均衡器选择实例
  3. 发起HTTP调用,携带认证Token
  4. 服务B处理并返回响应
  5. 如遇异常,触发熔断或重试

3.2.2 异步消息 - RocketMQ

RocketMQ配置说明:

配置项配置内容说明
NameServer192.168.1.100:9876;192.168.1.101:9876MQ服务地址,集群部署
Producer Groupknowledge-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/SagaAT(默认)
服务地址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检索
TokenStreamToken流处理流式输出

大模型配置:

  • 模型选择:通义千问 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 KeyAPI密钥认证服务间调用

授权模型:

  • RBAC:基于角色的访问控制
  • 权限粒度:模块->功能->操作
  • 数据权限:支持行级数据权限控制

安全措施:

  • 密码加密:BCrypt哈希算法
  • Token有效期:2小时,可刷新
  • 防暴力破解:登录失败5次锁定10分钟
  • 单点登录:支持SSO

6.2 数据加密架构

加密策略:

数据类型加密方式密钥管理
传输加密HTTPS/TLS 1.3SSL证书
存储加密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片段
动态SQLif/choose/foreach等动态查询
关联查询一对一、一对多关联映射

映射优化:

  • 使用和避免SQL语法错误
  • 批量操作使用foreach循环
  • 复杂查询使用SQL片段提高复用性
注:完整映射文件请参考项目源码

MyBatis映射说明:

映射类型说明
ResultMap结果集映射,定义字段映射关系
SQL片段可复用的SQL片段
动态SQLif/choose/foreach等动态查询
关联查询一对一、一对多关联映射

映射优化:

  • 使用和避免SQL语法错误
  • 批量操作使用foreach循环
  • 复杂查询使用SQL片段提高复用性
注:完整映射文件请参考项目源码

7.4 微服务监控配置

RocketMQ配置说明:

配置项配置内容说明
NameServer192.168.1.100:9876;192.168.1.101:9876MQ服务地址,集群部署
Producer Groupknowledge-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 技术栈总览

分类技术选型版本说明
后端开发
开发语言Java21 LTS虚拟线程、记录模式
应用框架Spring Boot3.5最新稳定版
微服务框架Spring Cloud2024.xGreenwich
前端开发
核心框架React18.xUI框架
开发语言TypeScript5.x类型安全
构建工具Vite5.x快速构建
UI组件库Ant Design5.x企业级组件
状态管理Zustand4.x轻量状态管理
路由React Router6.x客户端路由
图表库ECharts for React6.x数据可视化
代码编辑器CodeMirror 6-Markdown编辑
数据存储
数据库MySQL8.0主数据库
缓存Redis7.2缓存、分布式锁
搜索Elasticsearch8.x全文检索
向量数据库Milvus2.4语义搜索
图数据库Neo4j5.x知识图谱
文件存储RustFS最新分布式文件存储
中间件
消息队列RocketMQ5.3消息队列
分布式事务Seata2.xAT/TCC模式
注册中心Nacos2.x服务注册发现
配置中心Nacos2.x配置管理
API网关Spring Cloud Gateway4.x网关
基础设施
容器编排Kubernetes1.28.x容器编排
监控Prometheus2.47.x指标收集
可视化Grafana10.x监控面板
日志ELK Stack8.x日志分析
链路追踪SkyWalking8.16.x分布式追踪
AI能力
AI编排LangChain4j0.35.xAI框架
大模型通义千问qwen-max大语言模型
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏