QuickBlue-MicroAI 安装环境准备手册
本手册指导如何准备 QuickBlue-MicroAI 微服务平台的开发/部署环境,涵盖后端(Java 微服务)、前端(Vue3 管理端)、数据库及中间件的安装与配置。
1. 需要安装什么(组件清单)
| 组件 | 版本要求 | 是否必装 | 用途 |
|---|---|---|---|
| JDK | 21+ | ✅ 必装 | 运行后端全部微服务 |
| Maven | 3.9+ | ✅ 必装 | 后端打包 |
| MySQL | 8.0+ | ✅ 必装 | 业务数据(4 个库) |
| Redis | 6+ | ✅ 必装 | 缓存 / 分布式锁 / 会话 |
| Nacos | 2.4.3 | ✅ 必装 | 注册中心 + 配置中心 |
| Node.js | 24+ | ✅ 必装 | 运行与构建前端 |
| PostgreSQL + pgvector | 14+ / 0.7+ | 🔴 可选 | 仅 AI 知识库向量检索需要 |
| RocketMQ / Seata / Sentinel | — | 🔴 可选 | 消息队列 / 分布式事务 / 熔断降级,按需启用 |
2. 系统要求
- 操作系统:Windows 10/11、Linux(CentOS 7+ / Ubuntu 20+)或 macOS
- 内存:建议 16GB 及以上(微服务数量多,需同时运行网关 + 4 个业务服务 + 中间件)
- 磁盘:建议 20GB 以上可用空间
- 网络:可访问 Maven 中央仓库或国内镜像、npm 镜像
3. 必装组件安装
3.1 JDK 21+
后端基于 Spring Boot 3.5.x(java.version=21),必须使用 JDK 21 或更高版本。
- 下载安装:
- Oracle JDK:www.oracle.com/java/techno…
- 或开源版 Eclipse Temurin:adoptium.net/zh-CN/temur… Temurin 21 LTS)
- 配置环境变量(Windows 示例):
- 新建
JAVA_HOME=C:\Program Files\Java\jdk-21 - 在
Path中追加%JAVA_HOME%\bin
- 新建
- 验证:
java -version
# 输出应包含 "21.x"
3.2 Maven 3.9+
- 下载:<maven.apache.org/download.cg…
apache-maven-3.9.x-bin.zip) - 解压到本地目录,例如
D:\tools\apache-maven-3.9.9 - 配置环境变量:
- 新建
MAVEN_HOME=D:\tools\apache-maven-3.9.9 - 在
Path中追加%MAVEN_HOME%\bin
- 新建
- (可选)配置国内镜像加速,编辑
%MAVEN_HOME%\conf\settings.xml:
<mirror>
<id>aliyunmaven</id>
<mirrorOf>*</mirrorOf>
<name>阿里云公共仓库</name>
<url>https://maven.aliyun.com/repository/public</url>
</mirror>
- 验证:
mvn -v
# 输出应显示 Maven 3.9.x 与 Java 21
3.3 MySQL 8.0+
项目使用 4 个业务库:quickblue_system、quickblue_business、quickblue_support、quickblue_ai。
- 下载安装:dev.mysql.com/downloads/i… (选择 MySQL Community Server 8.0+)
- 或使用 Docker:
docker run -d --name quickblue-mysql \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=你的root密码 \ mysql:8.0 - 初始化数据库,按顺序执行项目自带脚本(位于
QuickBlue-MicroAI/database/mysql/):
# 1. 创建 4 个数据库
mysql -uroot -p < 01_create_databases.sql
# 2. 依次导入各库表结构与数据
mysql -uroot -p < 02_migrate_support.sql
mysql -uroot -p < 03_migrate_system.sql
mysql -uroot -p < 04_migrate_business.sql
mysql -uroot -p < 05_create_ai_tables.sql
- 创建业务账号(参考 Nacos 配置中使用的账号体系):
system_user、business_user、support_user、ai_user,按库授权:
CREATE USER 'system_user'@'%' IDENTIFIED BY '你的密码';
GRANT ALL PRIVILEGES ON quickblue_system.* TO 'system_user'@'%';
-- business_user / support_user / ai_user 同理
FLUSH PRIVILEGES;
- 验证:
mysql -uroot -p -e "SHOW DATABASES;"
# 应能看到 quickblue_system / quickblue_business / quickblue_support / quickblue_ai
3.4 Redis 6+
用于缓存、Spring Cache、Redisson 分布式锁与会话。
- 安装方式任选其一:
- Windows:github.com/tporadowski… (或使用 WSL2)
- Docker(推荐):
docker run -d --name quickblue-redis \ -p 6379:6379 \ redis:6 --requirepass "budaos" - 默认配置约定(与 Nacos 公共配置
redis-common.yaml对应,可通过环境变量覆盖):- 地址:
REDIS_HOST(默认localhost) - 端口:
REDIS_PORT(默认6379) - 密码:
REDIS_PASSWORD(默认budaos,生产环境务必修改) - 数据库:
REDIS_DATABASE(默认1)
- 地址:
- 验证:
redis-cli -h localhost -p 6379 -a budaos ping
# 返回 PONG
3.5 Nacos 2.4.3(注册中心 + 配置中心)
- 下载:github.com/alibaba/nac… (选择
nacos-server-2.4.3.zip) - 解压后进入
bin目录启动:如果想windows下自启动:可以阅读: Windows下安装nacos随电脑开机启动:juejin.cn/post/765561…# Windows(单机模式) startup.cmd -m standalone # Linux / macOS sh startup.sh -m standalone - 控制台验证:浏览器访问
http://localhost:8848/nacos,默认账号密码nacos/nacos。首次启动后建议立即修改默认密码。
- 创建命名空间:
- Namespace ID:
QuickBlue-dev - 名称:
QuickBlue开发环境
- Namespace ID:
- 导入配置:参考
nacos_config/Nacos配置手册.md,将nacos_config/common/下的公共配置(mysql-common.yaml、redis-common.yaml、sa-token-common.yaml、common-config.yaml等)与nacos_config/services/下的服务配置导入到QuickBlue-dev命名空间,Group 统一为QuickBlue_GROUP。 - 服务端连接参数(各服务
bootstrap.yaml中,支持环境变量覆盖):NACOS_SERVER_ADDR(默认localhost:8848)NACOS_NAMESPACE(默认QuickBlue-dev)NACOS_GROUP(默认QuickBlue_GROUP)NACOS_USERNAME/NACOS_PASSWORD
3.6 Node.js 24+
前端 QuickBule-MicroAI-web 基于 Vue 3 + Vite 8,package.json 中 engines.node >= 24。
- 下载安装:nodejs.org/ (选择 v24 LTS),或使用 nvm 管理多版本:
nvm install 24 nvm use 24 - (可选)配置 npm 镜像加速:
npm config set registry https://registry.npmmirror.com - 验证:
node -v # v24.x npm -v
4. 可选组件安装(按需启用)
4.1 PostgreSQL 14+ 与 pgvector 0.7+(AI 知识库向量检索)
仅当需要使用 AI 知识库的向量检索功能时安装。
- 安装 PostgreSQL 14+:www.postgresql.org/download/
- 安装 pgvector 扩展(0.7.0+):
- 源码编译:github.com/pgvector/pg…
- 或使用自带 pgvector 的 Docker 镜像:
docker run -d --name quickblue-pg \ -p 5432:5432 \ -e POSTGRES_PASSWORD=你的密码 \ pgvector/pgvector:pg16 - 启用扩展并初始化:
CREATE EXTENSION IF NOT EXISTS vector; - 切换数据源:将各服务
bootstrap.yaml中的共享配置由mysql-common.yaml改为postgresql-common.yaml,并导入 Nacos 的*-pg.yaml服务配置,详见nacos_config/Nacos配置手册.md中「数据库类型切换」章节。
4.2 RocketMQ(消息队列)
# Docker 快速部署(含 NameServer 与 Broker)
docker run -d --name rmqnamesrv -p 9876:9876 apache/rocketmq:5.3.1 sh mqnamesrv
docker run -d --name rmqbroker -p 10911:10911 -p 10909:10909 \
-e "NAMESRV_ADDR=宿主机IP:9876" apache/rocketmq:5.3.1 sh mqbroker
4.3 Seata(分布式事务)
下载:github.com/apache/seat… (Seata 2.x),解压后修改 conf/application.yaml 将注册与配置指向 Nacos,再执行 bin/seata-server.sh 启动。
4.4 Sentinel(熔断降级)
- Sentinel 核心依赖已集成在后端中,如需控制台:
# 下载 sentinel-dashboard 1.8.8 java -Dserver.port=8858 -jar sentinel-dashboard-1.8.8.jar - 访问
http://localhost:8858(默认sentinel/sentinel)。
Windows下安装Sentinel随电脑开机启动:juejin.cn/post/765582…
5. 后端构建与启动
- 克隆/获取源码后,在
QuickBlue-MicroAI/目录下编译打包:
mvn clean install -DskipTests
- 按顺序启动服务(建议先启动 Nacos,再启动各服务):
| 服务 | 模块 | 默认端口 |
|---|---|---|
| 网关 | QuickBlue-gateway | 8080 |
| 系统服务 | QuickBlue-modules/QuickBlue-system | 8081 |
| 业务服务 | QuickBlue-modules/QuickBlue-business | 8082 |
| 支持服务 | QuickBlue-modules/QuickBlue-support | 8083 |
| AI 服务 | QuickBlue-modules/QuickBlue-ai | 8084 |
| 监控中心 | QuickBlue-admin | 9090 |
- 验证:
- Nacos 控制台「服务列表」应出现全部微服务实例
- 网关 Swagger 聚合页:
http://localhost:8080/doc.html
6. 前端构建与启动
cd QuickBule-MicroAI-web
# 安装依赖
npm install
# 本地开发启动(连接 localhost 网关)
npm run localhost
# 生产构建
npm run build:prod
启动后按终端提示的地址(默认 http://localhost:5173)访问管理端。
7. 环境变量速查表
| 环境变量 | 默认值 | 说明 |
|---|---|---|
NACOS_SERVER_ADDR | localhost:8848 | Nacos 地址 |
NACOS_NAMESPACE | QuickBlue-dev | Nacos 命名空间 |
NACOS_GROUP | QuickBlue_GROUP | Nacos 分组 |
NACOS_USERNAME / NACOS_PASSWORD | nacos / 见 bootstrap.yaml | Nacos 认证 |
REDIS_HOST | localhost | Redis 地址 |
REDIS_PORT | 6379 | Redis 端口 |
REDIS_PASSWORD | budaos | Redis 密码 |
REDIS_DATABASE | 1 | Redis 库编号 |
8. 常见问题排查
- 服务启动报 Nacos 连接失败:确认 Nacos 已启动(
http://localhost:8848/nacos可访问),检查NACOS_SERVER_ADDR、命名空间、账号密码是否正确。 - 数据库连接失败:确认 MySQL/PostgreSQL 已启动、4 个库已创建、账号已授权,且 Nacos 中数据库连接配置正确。
- Redis 认证失败:检查
REDIS_PASSWORD与 Redis 服务端requirepass是否一致。 - 前端 npm install 报 Node 版本不满足:
engines要求 Node >= 24,使用nvm use 24切换版本。 - Maven 下载依赖慢:配置阿里云镜像(见 3.2 节)。
- AI 向量检索不可用:确认 PostgreSQL 已安装 pgvector 扩展并执行
CREATE EXTENSION vector;,服务已切换到postgresql-common.yaml配置。
9. 参考文档
nacos_config/Nacos配置手册.md:Nacos 配置导入、MySQL/PostgreSQL 切换详细步骤database/mysql/:数据库初始化脚本nacos_config/common/、nacos_config/services/:全部 Nacos 配置模板