QuickBlue 微服务技术架构说明文档

版本: 1.0 最后更新: 2026年5月1日 适用对象: 架构师、技术负责人、高级开发者

1. 整体架构概览

QuickBlue 采用 分层微服务架构，遵循领域驱动设计（DDD）原则，分为以下核心层次：

1.1 架构特点

✅ 松耦合: 各微服务通过 REST API 和消息队列通信，无直接数据库依赖
✅ 高可用: 关键服务支持集群部署，自动故障转移
✅ 可扩展: 水平扩展能力，支持按需增加服务实例
✅ 可观测: 全链路监控、日志、追踪三位一体
✅ 安全可控: 统一认证授权，细粒度权限控制

2. 核心组件架构

2.1 API 网关 (QuickBlue-gateway)

定位: 系统统一入口，负责路由、鉴权、限流、熔断

技术栈: Spring Cloud Gateway + WebFlux

核心功能:

✅ 动态路由配置（支持 Nacos 配置中心）
✅ JWT Token 认证与权限校验
✅ 请求/响应日志记录
✅ 全局跨域配置
✅ 白名单机制（静态资源、登录接口等）
✅ 路由重写与路径转换

2.2 系统管理服务 (QuickBlue-system)

定位: 用户认证、权限管理、组织架构、系统配置

核心模块:

用户管理（增删改查、密码策略）
角色权限管理（RBAC 模型）
部门组织架构（树形结构）
登录认证（JWT + Sa-Token）
系统参数配置

2.3 业务服务 (QuickBlue-business)

定位: 核心业务逻辑实现

典型业务:

教师管理（含部门信息展示逻辑）
课程管理
学生管理
教学计划管理
OA 办公流程

2.4 AI 服务 (QuickBlue-ai)

定位: 智能体应用管理和知识库管理

核心能力:

Agent 开发框架
知识库管理（文档上传、向量化、检索）
智能对话引擎
工作流编排

2.5 支撑服务 (QuickBlue-support)

定位: 通用功能支撑

提供能力:

文件上传下载（本地/云存储）
邮件发送
短信通知
Excel 导入导出（EasyExcel 封装）
公共工具类

3. 数据流与控制流

3.1 典型请求流程


客户端 → API Gateway → 认证中心 → 业务服务 → 数据库
     ↓          ↓           ↓
   日志      链路追踪     缓存
     ↓          ↓
   Prometheus  Zipkin

3.2 异步消息流

✅ 事件驱动架构：使用消息队列处理异步任务
✅ 典型场景：邮件发送、短信通知、文件处理
✅ 消息格式：JSON Schema 标准化

4. 服务治理架构

组件	技术选型	作用
服务注册发现	Nacos	服务自动注册、健康检查、动态路由
配置中心	Nacos	统一配置管理、灰度发布、环境隔离
API 文档	Knife4j + SpringDoc	自动生成 REST API 文档
服务监控	Spring Boot Admin	实时监控服务状态、JVM 指标
链路追踪	Micrometer Tracing + Zipkin	分布式调用链路分析
指标监控	Micrometer + Prometheus	系统性能指标采集

5. 安全架构

5.1 认证授权体系

认证方式: JWT Token + Sa-Token 框架
Token 策略:
- Access Token: 2小时有效期
- Refresh Token: 7天有效期
- 双 Token 机制防止 Token 泄露
权限模型: RBAC（角色-权限-用户）+ ABAC（属性基访问控制）

5.2 数据安全

✅ 敏感数据加密存储（AES-256）
✅ 数据库连接池加密配置
✅ SQL 注入防护（MyBatis Plus 自动转义）
✅ XSS 防护（前端 Vue 框架内置）

6. 监控与可观测性架构

6.1 三位一体监控体系

类型	工具	特点
Metrics	Micrometer + Prometheus	实时性能指标（QPS、响应时间、错误率）
Logging	Logback + ELK	结构化日志，支持 Trace ID 关联
Tracing	Micrometer Tracing + Zipkin	分布式调用链路追踪

6.2 监控指标分类

基础设施指标: CPU、内存、磁盘、网络
JVM 指标: 堆内存、GC 次数、线程数
应用指标: HTTP 请求统计、数据库连接池、缓存命中率
业务指标: 登录成功率、订单创建率、API 调用成功率

7. 数据存储架构

7.1 数据库选型

主数据库: PostgreSQL 14+（关系型数据存储）
缓存数据库: Redis 7+（分布式缓存、会话存储）
文件存储: 本地存储 + 阿里云 OSS（对象存储）

7.2 PostgreSQL 适配方案

✅ Boolean 类型映射：SmallintBooleanTypeHandler
✅ 序列权限管理：GRANT ALL ON ALL SEQUENCES
✅ 默认权限配置：DEFAULT PRIVILEGES
✅ 复杂查询优化：分区表、物化视图

8. 前端架构

8.1 技术栈

框架: Vue 3 + Composition API
构建工具: Vite 4+
UI 组件库: Element Plus
状态管理: Pinia
路由: Vue Router

8.2 前端模块划分

模块	功能
`api/`	接口请求封装
`views/`	页面组件
`components/`	可复用组件
`store/`	状态管理
`router/`	路由配置
`utils/`	工具函数
`constants/`	常量定义

9. 部署架构

9.1 环境划分

环境	用途	特点
开发环境	本地开发	单机部署，快速启动
测试环境	功能测试	完整微服务，模拟生产
预发布环境	上线前验证	与生产环境一致
生产环境	正式运行	高可用集群，负载均衡

9.2 部署方式

✅ Docker 容器化部署
✅ Kubernetes 编排（可选）
✅ Jenkins CI/CD 流水线
✅ Nacos 配置中心统一管理

10. 架构演进路线

阶段	时间	目标
V1.0	2024	微服务基础架构搭建
V2.0	2025	AI 智能体平台集成
V3.0	2026	Serverless 架构探索
V4.0	2027	边缘计算支持

当前版本: QuickBlue v3.0（基于 Spring Boot 3.x + Micrometer Tracing）

附录：架构决策记录 (ADR)

决策	日期	内容
链路追踪技术选型	2025-12-15	选择 Micrometer Tracing 替代 Sleuth，兼容 Spring Boot 3.x
数据库选型	2024-03-20	PostgreSQL 替代 MySQL，支持 JSONB、全文检索等高级特性
前端框架	2024-06-10	Vue 3 + Vite 替代 Vue 2 + Webpack，提升开发体验
配置中心	2024-08-05	Nacos 替代 Spring Cloud Config，支持动态配置推送

文档维护: 本架构文档由架构委员会维护，重大架构变更需经过评审后更新。