QuickBlue AI 微服务应用底座-环境准备篇

495 阅读6分钟

QuickBlue-MicroAI 安装环境准备手册

本手册指导如何准备 QuickBlue-MicroAI 微服务平台的开发/部署环境,涵盖后端(Java 微服务)、前端(Vue3 管理端)、数据库及中间件的安装与配置。


1. 需要安装什么(组件清单)

组件版本要求是否必装用途
JDK21+✅ 必装运行后端全部微服务
Maven3.9+✅ 必装后端打包
MySQL8.0+✅ 必装业务数据(4 个库)
Redis6+✅ 必装缓存 / 分布式锁 / 会话
Nacos2.4.3✅ 必装注册中心 + 配置中心
Node.js24+✅ 必装运行与构建前端
PostgreSQL + pgvector14+ / 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 或更高版本。

  1. 下载安装:
  2. 配置环境变量(Windows 示例):
    • 新建 JAVA_HOME = C:\Program Files\Java\jdk-21
    • 在 Path 中追加 %JAVA_HOME%\bin
  3. 验证:
java -version
# 输出应包含 "21.x"

3.2 Maven 3.9+

  1. 下载:<maven.apache.org/download.cg… apache-maven-3.9.x-bin.zip)
  2. 解压到本地目录,例如 D:\tools\apache-maven-3.9.9
  3. 配置环境变量:
    • 新建 MAVEN_HOME = D:\tools\apache-maven-3.9.9
    • 在 Path 中追加 %MAVEN_HOME%\bin
  4. (可选)配置国内镜像加速,编辑 %MAVEN_HOME%\conf\settings.xml:
<mirror>
    <id>aliyunmaven</id>
    <mirrorOf>*</mirrorOf>
    <name>阿里云公共仓库</name>
    <url>https://maven.aliyun.com/repository/public</url>
</mirror>
  1. 验证:
mvn -v
# 输出应显示 Maven 3.9.x 与 Java 21

3.3 MySQL 8.0+

项目使用 4 个业务库:quickblue_system、quickblue_business、quickblue_support、quickblue_ai。

  1. 下载安装: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
    
  2. 初始化数据库,按顺序执行项目自带脚本(位于 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
  1. 创建业务账号(参考 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;
  1. 验证:
mysql -uroot -p -e "SHOW DATABASES;"
# 应能看到 quickblue_system / quickblue_business / quickblue_support / quickblue_ai

3.4 Redis 6+

用于缓存、Spring Cache、Redisson 分布式锁与会话。

  1. 安装方式任选其一:
    docker run -d --name quickblue-redis \
      -p 6379:6379 \
      redis:6 --requirepass "budaos"
    
  2. 默认配置约定(与 Nacos 公共配置 redis-common.yaml 对应,可通过环境变量覆盖):
    • 地址:REDIS_HOST(默认 localhost)
    • 端口:REDIS_PORT(默认 6379)
    • 密码:REDIS_PASSWORD(默认 budaos,生产环境务必修改)
    • 数据库:REDIS_DATABASE(默认 1)
  3. 验证:
redis-cli -h localhost -p 6379 -a budaos ping
# 返回 PONG

3.5 Nacos 2.4.3(注册中心 + 配置中心)

  1. 下载:github.com/alibaba/nac… (选择 nacos-server-2.4.3.zip)
  2. 解压后进入 bin 目录启动:
    # Windows(单机模式)
    startup.cmd -m standalone
    # Linux / macOS
    sh startup.sh -m standalone
    
    如果想windows下自启动:可以阅读: Windows下安装nacos随电脑开机启动:juejin.cn/post/765561…
  3. 控制台验证:浏览器访问 http://localhost:8848/nacos,默认账号密码 nacos/nacos。

    首次启动后建议立即修改默认密码。

  4. 创建命名空间:
    • Namespace ID:QuickBlue-dev
    • 名称:QuickBlue开发环境
  5. 导入配置:参考 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。
  6. 服务端连接参数(各服务 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。

  1. 下载安装:nodejs.org/ (选择 v24 LTS),或使用 nvm 管理多版本:
    nvm install 24
    nvm use 24
    
  2. (可选)配置 npm 镜像加速:
    npm config set registry https://registry.npmmirror.com
    
  3. 验证:
    node -v   # v24.x
    npm -v
    

4. 可选组件安装(按需启用)

4.1 PostgreSQL 14+ 与 pgvector 0.7+(AI 知识库向量检索)

仅当需要使用 AI 知识库的向量检索功能时安装。

  1. 安装 PostgreSQL 14+:www.postgresql.org/download/
  2. 安装 pgvector 扩展(0.7.0+):
    docker run -d --name quickblue-pg \
      -p 5432:5432 \
      -e POSTGRES_PASSWORD=你的密码 \
      pgvector/pgvector:pg16
    
  3. 启用扩展并初始化:
    CREATE EXTENSION IF NOT EXISTS vector;
    
  4. 切换数据源:将各服务 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. 后端构建与启动

  1. 克隆/获取源码后,在 QuickBlue-MicroAI/ 目录下编译打包:
mvn clean install -DskipTests
  1. 按顺序启动服务(建议先启动 Nacos,再启动各服务):
服务模块默认端口
网关QuickBlue-gateway8080
系统服务QuickBlue-modules/QuickBlue-system8081
业务服务QuickBlue-modules/QuickBlue-business8082
支持服务QuickBlue-modules/QuickBlue-support8083
AI 服务QuickBlue-modules/QuickBlue-ai8084
监控中心QuickBlue-admin9090
  1. 验证:
    • Nacos 控制台「服务列表」应出现全部微服务实例
    • 网关 Swagger 聚合页:http://localhost:8080/doc.html

API.png

6. 前端构建与启动

cd QuickBule-MicroAI-web

# 安装依赖
npm install

# 本地开发启动(连接 localhost 网关)
npm run localhost

# 生产构建
npm run build:prod

启动后按终端提示的地址(默认 http://localhost:5173)访问管理端。

logon.png

7. 环境变量速查表

环境变量默认值说明
NACOS_SERVER_ADDRlocalhost:8848Nacos 地址
NACOS_NAMESPACEQuickBlue-devNacos 命名空间
NACOS_GROUPQuickBlue_GROUPNacos 分组
NACOS_USERNAME / NACOS_PASSWORDnacos / 见 bootstrap.yamlNacos 认证
REDIS_HOSTlocalhostRedis 地址
REDIS_PORT6379Redis 端口
REDIS_PASSWORDbudaosRedis 密码
REDIS_DATABASE1Redis 库编号

8. 常见问题排查

  1. 服务启动报 Nacos 连接失败:确认 Nacos 已启动(http://localhost:8848/nacos 可访问),检查 NACOS_SERVER_ADDR、命名空间、账号密码是否正确。
  2. 数据库连接失败:确认 MySQL/PostgreSQL 已启动、4 个库已创建、账号已授权,且 Nacos 中数据库连接配置正确。
  3. Redis 认证失败:检查 REDIS_PASSWORD 与 Redis 服务端 requirepass 是否一致。
  4. 前端 npm install 报 Node 版本不满足:engines 要求 Node >= 24,使用 nvm use 24 切换版本。
  5. Maven 下载依赖慢:配置阿里云镜像(见 3.2 节)。
  6. 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 配置模板