1. 环境全景图:先搞清楚我们要搭什么
做微服务底座这事儿,最怕一上来就闷头装软件。我先带你把这个“环境准备”到底在准备什么捋清楚,后面每一步都有据可依,不是瞎忙活。
QuickBlue AI 微服务应用底座,名字已经说明了一切。它不是一个业务系统,而是一套“地基工程”——把AI能力、微服务治理、通用中间件全部集成到一个可复用的底座里。简单说,你后续的业务系统不用从零搭建,直接在这个底座上“长”出来就行。它的价值在于:统一了技术栈、沉淀了通用能力、规范了服务治理方式,让团队不再重复造轮子,而是把精力聚焦在业务本身。
环境准备篇是整个QuickBlue系列的第一篇,也是地基中的地基。这一阶段的核心目标非常明确:
- 搞定基础设施:JDK、Maven、Git、Docker这些日常开发必备工具链。
- 拉起核心依赖:Nacos(注册配置中心)、MySQL(关系数据库)、Redis(缓存)、MinIO(对象存储)、Milvus(向量数据库)、RabbitMQ(消息队列)等中间件。
- 配置AI相关能力:大模型API密钥或本地模型服务,以及Spring AI框架的基础接入。
这套环境配好之后,你就能把QuickBlue底座的代码克隆到本地,跑通一个最简版的“服务启动+注册发现+配置拉取+AI对话”完整链路。
很多初学者会问:为什么要这么复杂?直接一个单体应用不香吗?这个问题的答案其实就藏在“微服务”这三个字里。单体应用在业务简单时确实省事,但当团队扩大到几十人、业务模块增加到十几个,单体应用的痛点会被无限放大:代码冲突频繁、构建时间漫长、故障隔离困难、技术选型互相牵制。微服务架构的核心优势在于独立部署、独立扩展、故障隔离(一个服务挂了不影响其他服务)、技术异构(不同服务可以用不同语言)。代价就是——环境复杂度上来了,这也就是我们为什么要花一整篇来准备环境。
我在公司内部推这套环境时,最大的感受是:环境准备做得好,后面联调少烦恼。绝大多数微服务联调中的疑难杂症,根源都能追溯到环境配置不一致。所以这篇我会尽量把细节讲透,包括版本号、配置文件写法、常见坑位,直接照着操作就能跑通。
2. 基础工具链:01、02、03 三步走完的必修课
2.1 JDK 17 + Maven 3.9:版本选不对,后面全是泪
QuickBlue底座的父工程基于Spring Boot 3.x,而Spring Boot 3.x强制要求JDK 17及以上。这不是可选项,是硬性规定。很多老项目还在用JDK 8,如果你也是,那第一步不是安装,而是先给团队做一轮技术栈升级的沟通——因为JDK版本直接决定了你能否用上Spring Boot 3的AOT编译、虚拟线程等新特性。
我推荐直接用JDK 17 LTS版本,选OpenJDK发行版即可。Linux服务器上你可能需要同时跑多个Java项目,建议用update-alternatives来管理JDK版本切换:
# Ubuntu/Debian 安装 OpenJDK 17 sudo apt update sudo apt install openjdk-17-jdk -y # 验证 java -version # 期望输出:openjdk version "17.0.x" 或 "17.x.x"Maven方面,Spring Boot 3.x官方推荐3.6.3或以上版本。请注意,Maven 3.9.x是目前的主流稳定线,不要用太老的3.5、3.6,容易出现依赖解析异常。安装后务必配置阿里云镜像仓库,不然每次拉依赖都要等半天:
<!-- ~/.m2/settings.xml 中添加 mirror --> <mirror> <id>aliyunmaven</id> <mirrorOf>central</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/central</url> </mirror>为什么强调这一步?因为QuickBlue底座的依赖树相当庞大——Spring Cloud Alibaba全家桶、Spring AI框架、MyBatis Plus、Sa-Token认证、分布式链路追踪组件等,几十个模块依赖加起来,如果网络不稳定,你会在mvn clean install这一步反复卡住。
提示:在IDE(IDEA或Eclipse)中导入项目前,先把Maven的settings.xml配置好,并且让IDE使用你本机安装的Maven,而不是自带的Bundled Maven。这个细节很多人会漏,导致IDE内构建和命令行构建的行为不一致,出现“IDEA里能跑,命令行走不通”的诡异问题。
2.2 Git 仓库管理:主分支保护与子模块策略
QuickBlue采用多模块Maven工程结构,整个底座在一个仓库里通过quickblue-xxx的子模块进行划分。这种单仓库多模块的方式,在底座型项目中比多仓库更合适——因为底座各模块之间存在大量内部依赖,拆成多仓库会让版本对齐变得痛苦不堪。
环境准备阶段,你只需要把仓库克隆到本地:
git clone https://github.com/your-group/quickblue-ai-platform.git cd quickblue-ai-platform然后即刻建立分支规范。我个人的做法是:master/main分支只允许PR合并,所有开发在dev/feature/*分支上进行。QuickBlue作为基础设施,一个提交就可能影响所有上层业务,所以哪怕是自己个人开发,也要养成feature/xxx开发、PR评审后合并的习惯。
这里有一个教训:我曾在环境准备阶段就顺手在master上改了配置直接提交,后来三个服务联调时出现了配置漂移(指不同服务读取到不同版本配置的现象),查了一整天才发现是某个pom版本号在master上被随手改过。从那以后,我强制自己所有变更都走分支,哪怕是改一行配置文件。
2.3 IDE 配置:导入工程的正确姿势
IDEA导入QuickBlue工程时,不要选中“Open”直接打开文件夹,而是选择工程的根pom.xml文件,以Maven工程的方式导入。这样IDEA会自动识别多模块结构,并且把所有模块都加载到Project窗口里。
导入后先做三件事:
- 确保Project SDK选择JDK 17:File → Project Structure → Project Settings → Project SDK。
- 设置Java编译级别为17:Settings → Build, Execution, Deployment → Compiler → Java Compiler,确保和pom.xml里的
java.version一致。 - 检查Maven Runner的JRE:Settings → Build Tools → Maven → Runner,JRE选择JDK 17。
做完这三件事,你执行mvn clean compile应该能通过。如果你的IDEA装了阿里代码规约插件或者SonarLint,可以先关闭它们,避免导入阶段产生一堆噪音警告,等环境跑通了再开不迟。
注意:IDEA 2023.1及以上版本对Spring Boot 3.x的支持才比较完善。老版本IDEA(2021.x)在识别
spring.factories和新版spring-configuration-metadata.json时会有兼容性问题,虽然能跑起来,但代码提示和自动补全会不灵。建议用最新稳定版IDEA。
3. 容器化中间件:Nacos、MySQL、Redis、MinIO、Milvus 一套拉齐
3.1 为什么采用 Docker Compose 一键拉起
这是环境准备篇里最实用的一节。QuickBlue底座的中间件依赖非常多,如果全部手工安装,光网络环境差异就能折腾你两三天。我推荐的做法是:所有基础设施中间件全部容器化,用Docker Compose统一编排。
有人可能会问:Docker容器里的MySQL、Redis性能会不会有损耗?常规开发环境完全不用担心,容器本身只是进程隔离,性能损耗几乎可以忽略。更重要的是容器化带来的三个好处:环境一致性(本地和CI/CD用的是同一个镜像,彻底消除环境差异问题)、可重复性(删了重建分分钟恢复,搞坏了不心疼)、资源隔离(不同中间件互相不干扰,端口不冲突)。
所谓“环境一致性”,就是你在自己电脑上能跑起来的环境,到服务器上也能一样跑起来——因为大家用的是同一个Compose文件和同一个镜像版本,而不是各自手工装出来的“差不多但不一样”的环境。这种确定性,在团队协作中极其宝贵。
先创建统一的环境目录:
mkdir -p /opt/quickblue/env && cd /opt/quickblue/env然后编写docker-compose.yml的主体框架。为了方便排查问题,所有容器都加上container_name、restart: always、显式端口映射、统一网络quickblue-net。
3.2 编排文件核心配置实战
把下面的内容保存为docker-compose.yml。注意,这套配置里我对关键项都加了注释,实际操作时可以按需调整端口和密码(但生产环境必改):
version: "3.8" networks: quickblue-net: driver: bridge ipam: config: - subnet: 172.28.0.0/24 services: mysql: image: mysql:8.0.33 container_name: quickblue-mysql restart: always environment: MYSQL_ROOT_PASSWORD: quickblue@123 MYSQL_DATABASE: quickblue_admin TZ: Asia/Shanghai ports: - "3306:3306" command: - --character-set-server=utf8mb4 - --collation-server=utf8mb4_general_ci - --default-time-zone=+8:00 volumes: - mysql-data:/var/lib/mysql - ./init:/docker-entrypoint-initdb.d:ro networks: - quickblue-net healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] interval: 10s timeout: 5s retries: 5 redis: image: redis:7.0.12 container_name: quickblue-redis restart: always ports: - "6379:6379" command: redis-server --requirepass quickblue@123 --appendonly yes volumes: - redis-data:/data networks: - quickblue-net nacos: image: nacos/nacos-server:v2.3.0 container_name: quickblue-nacos restart: always environment: MODE: standalone NACOS_AUTH_ENABLE: "true" NACOS_AUTH_IDENTITY_KEY: quickblue NACOS_AUTH_IDENTITY_VALUE: quickblue NACOS_AUTH_TOKEN: "your-very-long-secret-key-here-please-change" SPRING_DATASOURCE_PLATFORM: mysql MYSQL_SERVICE_HOST: mysql MYSQL_SERVICE_DB_NAME: quickblue_admin MYSQL_SERVICE_PORT: 3306 MYSQL_SERVICE_USER: root MYSQL_SERVICE_PASSWORD: quickblue@123 JVM_XMS: 512m JVM_XMX: 512m JVM_XMN: 256m ports: - "8848:8848" - "9848:9848" volumes: - nacos-logs:/home/nacos/logs depends_on: mysql: condition: service_healthy networks: - quickblue-net minio: image: minio/minio:RELEASE.2024-01-16T16-07-18Z container_name: quickblue-minio restart: always environment: MINIO_ROOT_USER: quickblue MINIO_ROOT_PASSWORD: quickblue@123 command: server /data --console-address ":9001" ports: - "9000:9000" - "9001:9001" volumes: - minio-data:/data networks: - quickblue-net milvus: image: milvusdb/milvus:v2.3.3 container_name: quickblue-milvus restart: always command: ["milvus", "run", "standalone"] environment: ETCD_USE_EMBED: "true" ETCD_DATA_DIR: /var/lib/milvus/etcd COMMON_STORAGETYPE: local ports: - "19530:19530" - "9091:9091" volumes: - milvus-data:/var/lib/milvus networks: - quickblue-net rabbitmq: image: rabbitmq:3.13-management container_name: quickblue-rabbitmq restart: always environment: RABBITMQ_DEFAULT_USER: quickblue RABBITMQ_DEFAULT_PASS: quickblue@123 ports: - "5672:5672" - "15672:15672" networks: - quickblue-net volumes: mysql-data: redis-data: nacos-logs: minio-data: milvus-data:这套编排文件里有几个细节,我特意要拎出来讲:
Nacos 使用 MySQL 持久化。Nacos默认支持内嵌数据库存储配置,但内嵌数据库是Derby,一旦容器重建数据全丢。QuickBlue底座里Nacos承担着配置中心的重任,配置丢了就是灾难。所以上面配置里我把Nacos的数据源指向MySQL,实现配置数据的持久化。启动时如果Nacos报数据库连接失败,原因往往是MySQL容器还没就绪,这就是为什么我加了depends_on+healthcheck,让MySQL确认健康后再启动Nacos。
Redis 开启密码验证。开发环境你可能觉得不设密码方便,但这个习惯一旦带到了生产环境就是重大隐患。Redis未授权访问漏洞曾经让无数公司吃过亏。我建议从一开始就习惯带上--requirepass参数,让连接URL天然包含密码。
MinIO 同时开放API端口9000和控制台端口9001。MinIO是QuickBlue底座中统一存储层,用来保存AI场景下的图片、文档、临时文件等非结构化数据。9000是S3兼容API端口,业务代码走的是这个;9001是浏览器管理页面,方便你上传测试文件、查看bucket,后面验证“MinIO存储对象、微服务通过SDK读写”时都离不开它。
Milvus 的本地存储模式。Milvus是向量数据库,QuickBlue底层做AI知识库检索、向量召回全靠它。我这里配置的是standalone模式加COMMON_STORAGETYPE=local,适合开发环境下跑。如果你的机器只有8G内存,可以把Milvus加一个MEM_LIMIT环境变量来限制资源。生产环境建议用分布式模式,依赖独立的etcd和MinIO集群,但那是后话。
启动整个中间件栈:
docker compose up -d然后通过docker ps检查所有容器状态。确保8个容器全部处于Up状态,并且没有Restarting出现。
需要重点验证的是Nacos:打开http://localhost:8848/nacos,默认账号密码是nacos/nacos。登录后可以看到“配置管理”和“服务管理”两个菜单。待会儿服务启动后,你会在这里看到QuickBlue的各微服务实例注册上来。
3.3 各中间件验证清单
中间件装好不等于环境就绪。我给一份验证清单,每个都要过一遍:
| 中间件 | 验证方式 | 期望结果 |
|---|---|---|
| MySQL | docker exec -it quickblue-mysql mysql -uroot -pquickblue@123 | 能进入MySQL命令行,执行SHOW DATABASES;能看到quickblue_admin库 |
| Redis | docker exec -it quickblue-redis redis-cli -a quickblue@123 ping | 返回PONG |
| Nacos | 浏览器打开http://localhost:8848/nacos | 能登录控制台 |
| MinIO | 浏览器打开http://localhost:9001 | 用quickblue/quickblue@123能登录,并手动创建ai-bucket测试桶 |
| Milvus | `docker logs quickblue-milvus | tail -30` |
| RabbitMQ | 浏览器打开http://localhost:15672 | 用quickblue/quickblue@123能登录管理界面 |
这一份清单我打印出来贴在工位上。每次在新机器搭环境,就照这个单子逐项打勾。别觉得多此一举——中间件一个个验证通过之后再启动业务微服务,才能保证问题出现时你能快速定位是“环境问题”还是“代码问题”。
4. 云端资源与 AI 能力接入:大模型密钥、Spring AI 与本地模型方案
4.1 大模型 API 密钥申请与配置管理
QuickBlue既然是AI微服务底座,AI能力的接入是重头戏。环境准备阶段,你需要获取至少一个大模型服务的API访问能力。当前常见的方案有:
- OpenAI兼容接口服务(如OpenAI官方、国内各模型的兼容网关)
- 各类国内大模型服务(如通义千问、文心一言、智谱GLM、DeepSeek等,它们的API有多种访问模式)
- 自建本地模型服务(如通过Ollama、vLLM部署开源模型,走本地API)
这里面我不去展开某一家具体的注册流程,因为各家平台的注册、实名认证、充值方式差异很大。但从QuickBlue底座的角度,重点不在于“用哪家模型”,而在于抽象层设计:底座里通过Spring AI框架统一封装对不同模型提供商的适配,业务模块不需要直接关心底层调用的是哪家的大模型。这就是“底座”与普通业务系统的区别——它天然就要支持多家模型接入和替换。
在环境准备阶段,你的任务是拿到至少一个可用的API Key,并把它配置到QuickBlue的配置中心Nacos里。这里有一个安全建议:API Key千万不要硬编码在代码里。它应该通过Nacos配置中心进行管理,并且通过环境变量或者配置文件注入。在本地开发时,我习惯在bootstrap.yml里留一个占位符${AI_API_KEY},然后在本机的~/.bashrc或application-dev.yml里设置实际值。
以配置一个OpenAI兼容接口为例,Nacos中创建一个配置,Data ID为quickblue-ai.yaml,内容大致如下:
spring: ai: openai: base-url: https://api.example.com/v1 api-key: ${AI_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7这里的base-url指向的是“兼容OpenAI格式”的网关地址。如果你用的是其他厂商的模型,它们大多提供OpenAI兼容的接口路径,换成对应地址即可。Spring AI就是通过这种统一规范,让上层业务代码得以解耦。
4.2 本地模型部署:没有云上API时的 Plan B
如果你的开发机上有一块不错的显卡(NVIDIA显卡显存12GB以上),又或者你出于成本考虑不想用付费API,那么本地部署一个开源模型是完全可行的。我用过Ollama这个工具,它把模型下载和启动封装得非常简单:
# 安装Ollama(macOS/Linux/WSL2) curl -fsSL https://ollama.ai/install.sh | sh # 拉取一个参数规模适中的模型,例如 qwen2.5:7b ollama pull qwen2.5:7b # 启动服务 ollama serve启动后,Ollama默认暴露在localhost:11434,它提供了一个OpenAI兼容的接口端点/v1/chat/completions。这意味着你可以在Spring AI配置里直接用base-url: http://localhost:11434/v1,api-key随便填一个占位符字符串即可。
用本地模型做开发调试的好处非常明显:无网络依赖、无费用消耗、数据不出本机,对涉及隐私数据的调试场景尤其友好。缺点也实在:响应速度没云上API快(特别是没有GPU的MacBook上跑7B模型,每秒只能吐几个token)、模型能力比不过旗舰大模型(处理复杂任务时效果差一些,适合调试链路而不是生产使用)。
我在实际调试QuickBlue的知识库检索链路时,就是这么干的:本地跑一个7B模型验证接口连通、向量检索召回、回答生成整个流程,确认代码没问题后再把Spring AI配置切回云端API做最终测试。这个“本地先通,云端再测”的习惯,能帮你把“代码逻辑问题”和“模型服务问题”干净地隔离开。
4.3 Spring AI 框架接入的最小配置
QuickBlue底座里对AI的集成,核心引用了spring-ai-starter相关的包。在环境准备阶段,你不需要深入业务代码,但至少要确认这个依赖能被正确拉取和初始化。在任意一个QuickBlue的子模块的pom.xml中添加:
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-openai</artifactId> <version>1.0.0</version> </dependency>然后写一个最简单的测试代码,验证Spring AI容器初始化成功:
@SpringBootTest class AiConnectivityTest { @Autowired private ChatClient chatClient; @Test void testChat() { String response = chatClient.prompt("用一句话介绍你自己").call().content(); System.out.println("AI Response: " + response); Assertions.assertNotNull(response); } }如果这个测试能跑通,说明你的AI环境链路是通的。如果报错,90%的原因是API Key没配置或者base-url写错,优先检查这两处。
5. 项目初始构建与自检:mvn 编译、Nacos 连通、第一个服务启动
5.1 全量构建:mvn clean install 的讲究
中间件环境就绪、AI能力配好之后,可以开始构建QuickBlue工程本身了。在根目录执行:
mvn clean install -DskipTests这一步会编译并安装所有模块到本地Maven仓库。我遇到过很多人在这一步卡住,主要原因无非三种:
- 依赖下载超时——解决方法:确认settings.xml镜像配置正确,必要时开代理(指的是通用网络代理,不是任何被禁用的工具)。
- 模块间版本号不一致——解决方法:不要手动改子模块里的版本号,一律以父pom的
<properties>统一管理。 - Lombok注解处理器版本冲突——解决方法:在
<dependencies>里显式声明Lombok的版本,并确保JDK17下使用1.18.30及以上版本。
构建成功的标志是终端出现BUILD SUCCESS,并且quickblue-ai-*等核心模块的jar包都出现在各自的target目录下。
这里额外提醒一点:-DskipTests是跳过测试代码的编译还是执行?严格说,-DskipTests只是跳过执行,测试类仍会编译,会拖慢整体构建。如果你是纯环境验证,可以加-Dmaven.test.skip=true连测试代码编译一起跳过,速度会快不少。但如果需要跑单元测试验证代码逻辑,-DskipTests=false跑完整测试更稳妥。
5.2 配置中心先行:Nacos 里先建好三类配置
QuickBlue的服务启动时会从Nacos拉配置,所以你不能等应用爆红了才去Nacos补配置,而是应该先把底座各个服务需要的公共配置、数据库表结构和初始数据准备好。
具体来说,在Nacos控制台需要创建三个层面的配置:
- 共享配置:比如
quickblue-common.yaml,存放公共的数据源规则、Redis连接、MinIO连接、日志级别等。 - AI服务专用配置:比如
quickblue-ai.yaml,存放上面提到的大模型API配置。 - 认证服务专用配置:比如
quickblue-auth.yaml,存放JWT密钥、Sa-Token配置和白名单路径等。
每个配置的格式和字段都要保持和bootstrap.yml或application.yml里的spring.config.import规则一致。这一步容易出错的地方在于:Nacos上的Data ID命名,必须遵循${spring.application.name}.${file-extension}的规范,否则你的应用启动时找不到配置,会直接报“无法从config server获取配置”。
另外,QuickBlue底座自带一个数据库初始化脚本目录。环境准备阶段,你需要在MySQL里依次执行这些SQL脚本,把quickblue_admin等基础库的表结构建好。如果你用的是我上面的Docker Compose方案,最省事的方法是把这些.sql脚本放到./init目录下,因为MySQL容器第一次启动时会自动执行/docker-entrypoint-initdb.d下的所有脚本。这个机制可以帮你省掉很多手工导库的琐碎时间。
5.3 启动第一个微服务:从 gateway 到 ai-service
配置就位、数据库就绪后,我们来启动第一个服务。QuickBlue底座默认的服务模块通常包括:
quickblue-gateway:统一API网关,负责路由转发、鉴权拦截、限流熔断。quickblue-auth:认证中心,负责登录鉴权、Token签发和刷新。quickblue-ai:AI服务,负责对话、知识库检索、内容生成等AI能力。quickblue-system:系统管理服务,负责用户、角色、菜单等基础数据。
启动顺序有讲究:先启动不依赖其他服务的底层模块,再启动上层服务。一般来说,gateway和auth都是最先启动的(它们自身对业务服务没有强依赖),然后启动quickblue-ai和quickblue-system。
IDEA里直接找到QuickblueGatewayApplication.java这个类,右键运行。然后观察控制台日志,重点关注这几行:
Nacos registry ... register service success——说明服务已成功注册到Nacos。Tomcat started on port(s): 8080——网关端口启动正常。Finished startup in X seconds——Spring容器初始化完成。
启动完成后,打开Nacos控制台的“服务管理”,如果看到quickblue-gateway等服务的实例列表,说明你的环境已经全部打通。用Postman或浏览器请求一下网关的健康检查接口(通常是http://localhost:8080/actuator/health),返回{"status":"UP"}就对了。
我自己习惯在环境准备阶段就做一遍全链路冒烟测试:通过网关调用AI服务,让它回答一句“你好”,然后看返回结果。虽然这通常属于后面几篇的范畴,但这一句问候一旦通了,就说明网关路由、服务发现、配置中心、AI能力、数据库连接整条链路全部通畅。环境准备篇的目标,到这里就算彻底达成了。
6. 常见问题与排查技巧:环境搭建时的 Top 10 坑
环境搭建过程中踩坑是家常便饭。这一节我挑Top 10最常见的问题,按出现频率排序,附上现象、原因和解决方式,方便你自查。
| 序号 | 问题现象 | 根本原因 | 解决方式 |
|---|---|---|---|
| 1 | Nacos启动后崩溃,日志报No DataSource set | Nacos数据源配置缺失或MySQL未就绪 | 检查SPRING_DATASOURCE_PLATFORM=mysql和MYSQL_SERVICE_*环境变量,确认MySQL健康后再启动Nacos |
| 2 | 微服务启动时报connect to Nacos timeout | 服务所在网络和Nacos不互通,或Nacos未完全启动 | 先docker logs quickblue-nacos确认Nacos就绪,再从服务容器ping nacos排查网络 |
| 3 | mvn clean install卡在依赖下载 | 镜像仓库未配置或Maven版本太旧 | 配置阿里云镜像,升级Maven到3.9.x,必要时删除~/.m2/repository里残留的*.lastUpdated文件 |
| 4 | Spring AI 的ChatClient注入失败 | spring-ai-starter版本和Spring Boot版本不兼容 | 确认Spring Boot版本为3.2.x或以上,Spring AI starter用1.0.0版本 |
| 5 | MySQL容器初始化时只建了库但没建表 | SQL脚本没放到/docker-entrypoint-initdb.d目录 | 确保init目录挂载到容器,并且SQL文件名以.sql结尾(容器只会执行第一次启动时的该目录脚本) |
| 6 | Redis连接报NOAUTH Authentication required | 客户端没带密码 | 检查连接配置里的password字段,QuickBlue统一配置应包含spring.data.redis.password |
| 7 | MinIO上传文件报AccessDenied | bucket不存在或策略不对 | 先在控制台创建bucket,再检查bucket的Access Policy,开发环境可以直接设为public |
| 8 | Milvus容器起停反复 | 内存不足导致OOM | 降低Milvus内存限制,或为Docker增加可用内存;优先保证Milvus所在机器有8G以上空闲内存 |
| 9 | Nacos控制台登录报权限异常 | 开启了鉴权但没有配置有效的NACOS_AUTH_TOKEN | 生成一个超过32字节的Base64密钥,重新配置后重启Nacos容器 |
| 10 | 微服务注册到Nacos后,网关转发仍报404 | 网关路由规则没配置或服务名不匹配 | 检查application.yml里spring.cloud.gateway.routes的uri写的是lb://服务名,并确认服务名和Nacos上注册的名称完全一致 |
除了这个表格之外,再说一个容易被忽略的排查技巧:把日志级别调到DEBUG看关键链路。当你遇到“配置拉到了但没生效”“路由匹配不上”这类问题,直接在应用的application.yml里临时加上:
logging: level: com.alibaba.nacos: DEBUG org.springframework.cloud.gateway: TRACE重启服务后,你会看到Nacos拉取配置的完整日志和网关路由匹配的详细过程。排查完记得改回INFO,不然日志量太大了。
我最后一次搭QuickBlue环境,就是栽在Nacos鉴权这个坑上(表格第9条)。一开始图省事,NACOS_AUTH_ENABLE设置了true但没配NACOS_AUTH_TOKEN,结果服务启动全部报401。当时对着日志看了半小时愣是没反应过来,后来猛然想起鉴权配置还没补全,三分钟就解决了。所以说,排查问题的时候,先从自己最熟悉的“偷懒点”入手,往往效率最高。
7. 迈向联调之前:最后过一遍这套“环境预检”
环境准备篇的内容到这里就差不多完整了。最后送你一套我自己沉淀下来的环境预检清单,每次在新电脑、新服务器、新同事入职时,我都直接把这个清单丢过去,照做一遍就完事。
- JDK版本:
java -version,确认是17.x。 - Maven版本:
mvn -v,确认3.9.x,且settings.xml指向阿里云镜像。 - Docker环境:
docker ps,确认中间件容器都在运行。 - Nacos可达:浏览器访问
http://localhost:8848/nacos,能登录,且能看到预置的配置文件。 - MySQL表结构:
SHOW TABLES;,确认quickblue_admin库下有业务表。 - AI连通:跑一次
AiConnectivityTest,确认大模型API或本地模型能返回应答。 - 项目构建:根目录
mvn clean install -DskipTests全量通过。 - 网关健康:请求
http://localhost:8080/actuator/health返回UP。
这套预检做完,你就从“零裸机”状态彻底进入了“可开发状态”。后续不管是做微服务架构图里某个模块的编码,还是跟其他成员做服务间的联调,环境这块都不会再拖后腿。我个人在实际操作中的体会是,环境准备阶段投入的时间绝对不是浪费——上层的联调、部署、测试环节,省下来的时间往往是环境投入的十倍以上。把地基打牢,后面的活才能真正跑得快。接下来你可以放心地进入QuickBlue底座的模块拆解篇,去研究服务之间的调用链路和业务实现了。