☰
微服务底座环境搭建实战:从Docker Compose到Spring AI全链路打通
2026/9/27 1:10:56 网站建设 项目流程

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窗口里。

导入后先做三件事:

  1. 确保Project SDK选择JDK 17:File → Project Structure → Project Settings → Project SDK。
  2. 设置Java编译级别为17:Settings → Build, Execution, Deployment → Compiler → Java Compiler,确保和pom.xml里的java.version一致。
  3. 检查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 各中间件验证清单

中间件装好不等于环境就绪。我给一份验证清单,每个都要过一遍:

中间件验证方式期望结果
MySQLdocker exec -it quickblue-mysql mysql -uroot -pquickblue@123能进入MySQL命令行,执行SHOW DATABASES;能看到quickblue_admin库
Redisdocker 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-milvustail -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仓库。我遇到过很多人在这一步卡住,主要原因无非三种:

  1. 依赖下载超时——解决方法:确认settings.xml镜像配置正确,必要时开代理(指的是通用网络代理,不是任何被禁用的工具)。
  2. 模块间版本号不一致——解决方法:不要手动改子模块里的版本号,一律以父pom的<properties>统一管理。
  3. 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最常见的问题,按出现频率排序,附上现象、原因和解决方式,方便你自查。

序号问题现象根本原因解决方式
1Nacos启动后崩溃,日志报No DataSource setNacos数据源配置缺失或MySQL未就绪检查SPRING_DATASOURCE_PLATFORM=mysql和MYSQL_SERVICE_*环境变量,确认MySQL健康后再启动Nacos
2微服务启动时报connect to Nacos timeout服务所在网络和Nacos不互通,或Nacos未完全启动先docker logs quickblue-nacos确认Nacos就绪,再从服务容器ping nacos排查网络
3mvn clean install卡在依赖下载镜像仓库未配置或Maven版本太旧配置阿里云镜像,升级Maven到3.9.x,必要时删除~/.m2/repository里残留的*.lastUpdated文件
4Spring AI 的ChatClient注入失败spring-ai-starter版本和Spring Boot版本不兼容确认Spring Boot版本为3.2.x或以上,Spring AI starter用1.0.0版本
5MySQL容器初始化时只建了库但没建表SQL脚本没放到/docker-entrypoint-initdb.d目录确保init目录挂载到容器,并且SQL文件名以.sql结尾(容器只会执行第一次启动时的该目录脚本)
6Redis连接报NOAUTH Authentication required客户端没带密码检查连接配置里的password字段,QuickBlue统一配置应包含spring.data.redis.password
7MinIO上传文件报AccessDeniedbucket不存在或策略不对先在控制台创建bucket,再检查bucket的Access Policy,开发环境可以直接设为public
8Milvus容器起停反复内存不足导致OOM降低Milvus内存限制,或为Docker增加可用内存;优先保证Milvus所在机器有8G以上空闲内存
9Nacos控制台登录报权限异常开启了鉴权但没有配置有效的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. 迈向联调之前:最后过一遍这套“环境预检”

环境准备篇的内容到这里就差不多完整了。最后送你一套我自己沉淀下来的环境预检清单,每次在新电脑、新服务器、新同事入职时,我都直接把这个清单丢过去,照做一遍就完事。

  1. JDK版本:java -version,确认是17.x。
  2. Maven版本:mvn -v,确认3.9.x,且settings.xml指向阿里云镜像。
  3. Docker环境:docker ps,确认中间件容器都在运行。
  4. Nacos可达:浏览器访问http://localhost:8848/nacos,能登录,且能看到预置的配置文件。
  5. MySQL表结构:SHOW TABLES;,确认quickblue_admin库下有业务表。
  6. AI连通:跑一次AiConnectivityTest,确认大模型API或本地模型能返回应答。
  7. 项目构建:根目录mvn clean install -DskipTests全量通过。
  8. 网关健康:请求http://localhost:8080/actuator/health返回UP。

这套预检做完,你就从“零裸机”状态彻底进入了“可开发状态”。后续不管是做微服务架构图里某个模块的编码,还是跟其他成员做服务间的联调,环境这块都不会再拖后腿。我个人在实际操作中的体会是,环境准备阶段投入的时间绝对不是浪费——上层的联调、部署、测试环节,省下来的时间往往是环境投入的十倍以上。把地基打牢,后面的活才能真正跑得快。接下来你可以放心地进入QuickBlue底座的模块拆解篇,去研究服务之间的调用链路和业务实现了。

需要专业的网站建设服务?

联系我们获取免费的网站建设咨询和方案报价,让我们帮助您实现业务目标

立即咨询