QuickBlue 微服务开发平台（PostgreSQL 版）

基于 Spring Boot 3.5 + Spring Cloud 2025 的企业级全栈平台，集成 AI 智能体能力，面向教学实训场景（类似学习通）持续演进。

目录

• 技术栈

• 项目结构

• 环境准备

• 快速启动

• 模块说明

• AI 智能体架构

• 开发路线图

• 常见问题

技术栈

项目结构

work_quickblue_postgresql/
├── QuickBlue-parent-pg/               # 后端 Maven 父工程
│   ├── QuickBlue-common/              # 公共模块（8 个子模块）
│   │   ├── QuickBlue-common-core      # 核心工具类、异常、枚举
│   │   ├── QuickBlue-common-database  # MyBatis-Plus + Druid 配置
│   │   ├── QuickBlue-common-redis     # Redisson + Redis 工具
│   │   ├── QuickBlue-common-security  # Sa-Token + 权限注解
│   │   ├── QuickBlue-common-swagger   # Knife4j 聚合文档
│   │   ├── QuickBlue-common-web       # Web 通用配置
│   │   ├── QuickBlue-common-log       # 日志注解 + AOP
│   │   └── QuickBlue-common-excel     # EasyExcel 导入导出
│   ├── QuickBlue-api/                 # 远程接口定义（@HttpExchange 声明式 HTTP，5 个子模块）
│   │   ├── QuickBlue-api-system       # 系统管理 API
│   │   ├── QuickBlue-api-business     # 业务 API
│   │   ├── QuickBlue-api-support      # 支撑 API
│   │   ├── QuickBlue-api-ai           # AI 服务 API
│   │   └── QuickBlue-api-report       # 报表 API
│   ├── QuickBlue-modules/             # 业务模块实现（5 个子模块）
│   │   ├── QuickBlue-system           # 系统管理（用户/角色/菜单/部门/数据字典）
│   │   ├── QuickBlue-business         # 业务模块
│   │   ├── QuickBlue-support          # 支撑模块
│   │   ├── QuickBlue-ai               # ★ AI 智能体服务（核心）
│   │   └── QuickBlue-report           # 报表模块
│   ├── QuickBlue-gateway/             # Spring Cloud Gateway 网关
│   ├── QuickBlue-admin/               # Spring Boot Admin 监控
│   ├── nacos_config/                  # Nacos 配置集
│   ├── database/postgresql/           # 数据库初始化脚本
│   └── .env                           # 本地开发环境变量
├── QuickBule-admin-webpg/             # 前端管理平台（Vue 3 + Vite）
│   └── src/
│       ├── views/ai/                  # AI 管理页面（8 个模块）
│       ├── api/ai/                    # AI 模块 API 封装
│       ├── router/                    # 动态路由
│       └── constants/                 # 全局枚举（SmartEnum 插件）
├── doc/                               # 项目文档
├── uploads/                           # 上传文件存储
└── logs/                              # 日志文件

环境准备

必需组件

可选组件

环境变量配置

项目根目录的 .env 文件已预设开发环境变量，按需修改数据库密码等。

xxxxxxxxxx
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=sdgs2026
DB_PASSWORD=sdgs@1234
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=Nq963369
NACOS_SERVER_ADDR=localhost:8848

快速启动

1. 初始化数据库

​x
cd QuickBlue-parent-pg/database/postgresql

# 按顺序执行 SQL 脚本：
# 01_create_databases.sql     - 创建数据库
# 02_migrate_support.sql      - 支撑模块表
# 03_migrate_system.sql       - 系统模块表（含 AI 菜单）
# 04_migrate_business.sql     - 业务模块表
# 05_create_ai_tables.sql      - AI 模块表（需要 pgvector 扩展）

注意：AI 模块依赖 pgvector 扩展，请先在 PostgreSQL 中安装。

2. 启动 Nacos

xxxxxxxxxx
# 单机模式启动
startup.cmd -m standalone

启动后访问 http://localhost:8848/ ，导入 nacos_config/ 目录下的配置。

3. 启动后端服务

xxxxxxxxxx
cd QuickBlue-parent-pg
mvn clean install -DskipTests

# 按顺序启动各模块（IDEA 中直接运行 Application 主类）
# 1. QuickBlue-system   (端口 8081)
# 2. QuickBlue-business (端口 8082)
# 3. QuickBlue-support  (端口 8083)
# 4. QuickBlue-ai       (端口 8084)
# 5. QuickBlue-gateway  (端口 8080)
# 6. QuickBlue-report   (端口 8085)

4. 启动前端

xxxxxxxxxx
cd QuickBule-admin-webpg
npm install
npm run dev

访问 http://localhost:5173/ ，默认账号 admin / 密码 admin。

模块说明

系统管理 (QuickBlue-system)

AI 智能体 (QuickBlue-ai)

详见 AI 智能体架构 章节。

网关 (QuickBlue-gateway)

• 统一入口（端口 8080）

• 路由转发 + 负载均衡

• Sa-Token 认证校验

• CORS 跨域处理

• 请求日志记录

监控 (QuickBlue-admin)

• Spring Boot Admin Server

• 服务健康检查、内存/线程监控

• 通过 Nacos 自动发现

AI 智能体架构

整体架构

xxxxxxxxxx
┌─────────────────────────────────────────────────────────────┐
│                      前端管理平台                             │
│  agent/ │ knowledge/ │ model/ │ tool/ │ prompt/ │ session/ │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP/SSE
┌──────────────────────────▼──────────────────────────────────┐
│                    AI 服务 (端口 8084)                        │
│                                                             │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ AgentScope   │  │ ChatModel    │  │  Tool Registry     │  │
│  │ v2.0 推理引擎│  │ Factory/6家  │  │  ConcurrentHashMap │  │
│  │ ReAct + SSE  │  │ 供应商       │  │  DynamicToolWrapper│  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬──────────┘  │
│         │                 │                    │             │
│  ┌──────▼─────────────────▼────────────────────▼──────────┐  │
│  │                 LangChain4j 工具层                      │  │
│  │  ChatLanguageModel │ EmbeddingModel │ ToolExecutor     │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                    RAG 管道                              │  │
│  │  Tika 解析 → 分段(chunk=500) → 向量化 → PgVector 存储   │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                             │
│  数据层: PostgreSQL + pgvector │ Redis 缓存 │ Nacos 配置     │
└─────────────────────────────────────────────────────────────┘

核心模块清单

内置工具

API 接口速览

开发路线图

第一阶段：基础设施补全 ✅ 已完成

• ✅ 知识库文档管道（上传→解析→分段→向量化→存储）

• ✅ 提示词管理（{{变量}} 渲染引擎）

• ✅ 工具管理 API（HTTP/Script 执行器、动态注册）

• ✅ 前端 8 个管理页面（agent/knowledge/doc/model/tool/prompt/app/session）

• ✅ 4 个内置工具（Calculator/WebSearch/DatabaseQuery/FileRead）

• ✅ 数据库菜单集成、Maven 编译通过

第二阶段：教学核心能力（规划中）

第三阶段：工作流与多 Agent

第四阶段：运营与分析

常见问题

Q: 需要哪些 LLM API Key？

项目支持 6 家模型供应商，至少配置一家即可使用 AI 功能：

• 通义千问（DashScope）：需阿里云 API Key

• OpenAI：需 OpenAI API Key

• 智谱 AI：需智谱 API Key

• 百度千帆：需百度云 API Key

• Ollama：本地部署，无需 API Key

• Anthropic：需 Anthropic API Key

在 AI 服务 Nacos 配置（QuickBlue-ai-pg.yaml）中填写对应 API Key。

Q: pgvector 扩展如何安装？

xxxxxxxxxx
-- 在 PostgreSQL 中执行
CREATE EXTENSION vector;

如果提示找不到扩展，需先安装 pgvector 插件（参考 pgvector GitHub）。

Q: 端口冲突怎么办？

在 application.yaml 或 Nacos 配置中修改各服务端口：

• 系统服务：8081

• 业务服务：8082

• 支撑服务：8083

• AI 服务：8084

• 报表服务：8085

• 网关：8080

• 监控：9090

Q: 前端动态路由不出菜单？

确认 router/index.js 的 buildRoutes() 正常执行（从后端菜单数据库动态构建路由），检查菜单表 t_menu 是否有数据，以及当前用户角色是否有授权。

相关文档