Spring Boot 4.x 已全面拥抱 Jakarta EE 10，底层基于 Spring Framework 6.x，最低要求 JDK 17。Nacos 3.2.3 作为阿里云开源的最新稳定版，不仅支持 gRPC 长连接，还大幅提升了 AP 集群的可用性。两者结合，堪称Java 微服务领域的新一代“黄金搭档”。

适用场景：微服务架构、云原生配置中心、服务注册与发现
硬性要求：JDK 17+、Nacos 3.0.0+、Spring Boot 4.1.0

本文将从零开始，手把手带你完成：
说明:笔者这里只是Demo Nacos 部署的单机版

• Nacos 3.2.3 单机

• Spring Boot 4.1.0 项目初始化

• 配置中心动态刷新（@RefreshScope）

• 服务注册与发现（Feign 客户端调用）

• 常见坑及解决方案

• Nacos 3.2.3 快速启动（单机版）

Nacos 3.2.3 官网配置说明

笔者提醒: Nacos 3.2.3 版本部署后共有三个端口。

1.nacos.server.main.port=8848（原生核心端口）

• 含义：这是 Nacos最核心的主端口，也是兼容 2.x 时代的“万能入口”。

• 作用：处理HTTP 协议的请求。包括：控制台的 API 调用、Spring Boot 应用通过application.yml拉取配置（Config）、服务实例的心跳上报（HTTP 模式）、以及 Admin 管理接口。

• 注意：虽然 3.x 默认建议用 gRPC，但8848依然是所有客户端必须能访问的入口端口，因为客户端初始化时首先会连接它进行握手和地址拉取。

2.9848（gRPC 长连接核心端口）

• 含义：这是gRPC 协议的服务端监听端口。它不是让你在配置文件里手写的，而是由8848自动偏移计算得出的（计算规则：main.port + 1000，即 8848 + 1000 = 9848）。

• 作用：

  • 服务注册与发现（核心）：Spring Boot 4.x 应用注册到 Nacos 时，心跳维持、服务实例列表的实时推送（Push）全部走的是这个 9848 端口。

  • 配置长轮询：配置中心的动态刷新监听（Long Polling）也复用该 gRPC 连接。

• 致命坑点（必看）：如果你的 Spring Boot 应用部署在容器或 K8s 中，必须在安全组/防火墙中同时开放8848和9848。如果只开8848不开9848，你的服务可以启动（能拉取一次配置），但几秒后就会报错断开连接，且无法收到配置变更推送！

3.nacos.console.port=8080（独立控制台 Web 端口）——3.x 新增

• 含义：这是 Nacos 3.x将前端界面（Console UI）与后端 API 剥离后的独立端口。

• 作用：专用于提供 Nacos 可视化控制台的网页资源（HTML/CSS/JS）和登录页面。

• 为什么拆分：为了让运维人员可以只将8080暴露给公网用于 UI 访问，而将8848和9848封闭在内网，提高 API 安全性。访问地址现在变成了http://你的IP:8080/nacos（注意不再是 8848）。

• 注意：如果该端口被占用，启动会报错，你可以通过-Dnacos.console.port=8081修改。

4.nacos.ai.registry.port=9080（AI 模型注册专用端口）——3.x 重磅新特性

• 含义：这是 Nacos 3.2.3 专门为AI 原生场景开辟的独立 HTTP 端口。

• 作用：专用于AI 智能体（Agent）和大模型（LLM）的注册与发现。它走的是独立的语义化注册流程（支持向量检索和元数据模糊匹配），与传统的 Java 微服务（Spring Boot）注册逻辑隔离。

• 对你当前文章的影响：如果你是标准的 Spring Boot 4.x 微服务，并不需要用到这个端口，你的应用也不会连它。它只服务于 Python 的 AI 客户端（如 Nacos-SDK-Python 3.x）。如果你在写微服务实战，可以在文末提一句“AI 端口仅供模型注册，不影响业务服务”，显得你研究得很深。
  

如果连接超时，可以试试 开放 所有使用到的端口号

startup.sh -m standalone

⚠️ 特别提醒：linux 如果已经安装了低版本JDK，需要修改一下startup.sh 启动文件，在启动文件中指定新安装的高版本JDK路径即可，如上图。 windows 环境一样。

启动部署成功后访问:

创建 Spring Boot 4.1.0 项目

1. 父项目pom文件

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>4.1.0</version> <relativePath/> </parent> <groupId>com.work</groupId> <artifactId>sirius-workspace</artifactId> <version>1.0</version> <packaging>pom</packaging> <modules> <module>sirius-iaas</module> <module>sirius-common</module> <module>sirius-iaas/gateway</module> </modules> <properties> <java.version>25</java.version> <spring-cloud.version>2025.1.2</spring-cloud.version> <spring-cloud-alibaba.version>2025.1.0.0</spring-cloud-alibaba.version> <cloud-starter-bootstrap.version>5.0.2</cloud-starter-bootstrap.version> <webmvc-ui.version>3.0.3</webmvc-ui.version> <hutool.version>5.8.21</hutool.version> <mysql.version>8.4.0</mysql.version> <mybatis-plus.version>3.5.17</mybatis-plus.version> <dynamic.version>4.5.0</dynamic.version> <commons-lang3.version>3.20.0</commons-lang3.version> <jjwt.version>0.13.0</jjwt.version> <jasypt.version>4.0.4</jasypt.version> <validation.version>4.1.0</validation.version> </properties> <dependencies> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> </dependency> </dependencies> <!-- 依赖管理 先指定版本 后面就不需要指定版本了--> <dependencyManagement> <dependencies> <!-- 1. Spring Cloud 依赖 BOM（Bill of Materials） 作用：统一管理 Spring Cloud 生态下所有组件（如 OpenFeign、LoadBalancer、Gateway）的版本。 原理：type=pom + scope=import 会将此 POM 中的 dependencyManagement 导入当前工程， 避免为每个微服务组件单独指定版本号，确保版本兼容性。 --> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-dependencies</artifactId> <version>${spring-cloud.version}</version> <type>pom</type> <scope>import</scope> </dependency> <!-- 2. Spring Cloud Alibaba 依赖 BOM 作用：统一管理 Alibaba 系微服务组件版本，包括： - Nacos（服务注册/配置中心） - Sentinel（流量熔断/限流） - Seata（分布式事务） 注意：请确保 ${spring-cloud-alibaba.version} 与上方的 Spring Cloud 版本严格对应。 --> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-alibaba-dependencies</artifactId> <version>${spring-cloud-alibaba.version}</version> <type>pom</type> <scope>import</scope> </dependency> <!-- 3. Spring Cloud Bootstrap 启动器 作用：让 Spring Boot 应用重新支持读取 bootstrap.yml / bootstrap.properties 配置文件。 --> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-bootstrap</artifactId> <version>${cloud-starter-bootstrap.version}</version> </dependency> <!-- 4. Hutool 全量工具包 作用：提供丰富的 Java 工具方法，涵盖字符串处理、日期计算、加密解密、HTTP 客户端、Excel 导出、二维码生成等。比 Apache Commons 更简洁，且无额外依赖。 --> <dependency> <groupId>cn.hutool</groupId> <artifactId>hutool-all</artifactId> <version>${hutool.version}</version> </dependency> <!-- springfox-swagger2 生成 OpenAPI v2 (Swagger 2.0) 格式的 RESTful API 文档接口。--> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>${webmvc-ui.version}</version> <scope>compile</scope> </dependency> <!--MySQL JDBC 驱动--> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <version>${mysql.version}</version> <scope>compile</scope> </dependency> <!-- 动态数据源（多数据源）Starter --> <dependency> <groupId>com.baomidou</groupId> <artifactId>dynamic-datasource-spring-boot-starter</artifactId> <version>${dynamic.version}</version> </dependency> <!-- mybatis-plus-boot-starter 自动配置 SqlSessionFactory、事务管理、分页插件等，并提供通用 Mapper、条件构造器等增强功能。 --> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>${mybatis-plus.version}</version> <scope>compile</scope> </dependency> <!--mybatis-plus-annotation --> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-annotation</artifactId> <version>${mybatis-plus.version}</version> <scope>compile</scope> </dependency> <!-- commons-lang3-提供 Java 核心库的增强工具类 --> <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-lang3</artifactId> <version>${commons-lang3.version}</version> </dependency> <!-- ==================== JWT 令牌支持 ==================== --> <dependency> <groupId>io.jsonwebtoken</groupId> <artifactId>jjwt-api</artifactId> <version>${jjwt.version}</version> </dependency> <!-- JJWT 的默认实现模块，提供 JWT 签名、加密等具体逻辑。 --> <dependency> <groupId>io.jsonwebtoken</groupId> <artifactId>jjwt-impl</artifactId> <version>${jjwt.version}</version> <scope>runtime</scope> </dependency> <!--将 Jackson 作为 JJWT 的 JSON 序列化/反序列化实现--> <dependency> <groupId>io.jsonwebtoken</groupId> <artifactId>jjwt-jackson</artifactId> <version>${jjwt.version}</version> <scope>runtime</scope> </dependency> <!-- 对 Spring Boot 配置文件 中的敏感信息（如数据库密码、密钥）进行加密和解密，只需在配置中使用 ENC(加密值) 格式，自动在运行时解密。 --> <dependency> <groupId>com.github.ulisesbocchio</groupId> <artifactId>jasypt-spring-boot-starter</artifactId> <version>${jasypt.version}</version> <scope>compile</scope> </dependency> <!-- spring-boot-starter-validation 对 Controller 入参、Service 层方法参数及实体类字段进行声明式校验。--> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> <version>${validation.version}</version> <scope>compile</scope> </dependency> </dependencies> </dependencyManagement> </project>

2. 子项目pom文件

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>com.work</groupId> <artifactId>sirius-workspace</artifactId> <version>1.0</version> <relativePath>../../pom.xml</relativePath> </parent> <artifactId>gateway</artifactId> <description>系统网关</description> <dependencies> <!-- 引入Spring Boot核心 --> <dependency> <groupId>com.work</groupId> <artifactId>sirius-common</artifactId> <version>1.0</version> </dependency> <!-- gateway 网关--> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-gateway</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!--gateway网关负载均衡依赖--> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-loadbalancer</artifactId> </dependency> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId> </dependency> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-bootstrap</artifactId> </dependency> <!--限流引入redis--> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis-reactive</artifactId> </dependency> <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-pool2</artifactId> </dependency> <!-- Jasypt --> <dependency> <groupId>com.github.ulisesbocchio</groupId> <artifactId>jasypt-spring-boot-starter</artifactId> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>

2. 配置文件bootstrap.yml（必选）

#启用配置文件 spring: profiles: active: ${profile:dev}

2. 1 配置文件bootstrap-dev.yml（必选）

spring: application: name: gateway cloud: nacos: discovery: server-addr: ${NACOS_SERVER:127.0.0.1:19110} namespace: ${NAME_SPACE:mation} username: ENC(kk6UhLPBlBwrj0IEY/MrxMidlUDI4XrpA7KbVHDEWsq1qAceSGP9q0sYMWODWky9) password: ENC(b7rpZxmlFOLK8R9hSKVu7RTFJp/JHcmATdBICFfw8027w6d3OSfE5fzbrpCz5iMoJ67mfj8xIzt8GHcyyTphTw==) group: ${GROUP_ID:DEFAULT_GROUP_DEV} config: server-addr: ${NACOS_SERVER:127.0.0.1:19110} file-extension: yaml namespace: ${NAME_SPACE:mation} username: ENC(kk6UhLPBlBwrj0IEY/MrxMidlUDI4XrpA7KbVHDEWsq1qAceSGP9q0sYMWODWky9) password: ENC(b7rpZxmlFOLK8R9hSKVu7RTFJp/JHcmATdBICFfw8027w6d3OSfE5fzbrpCz5iMoJ67mfj8xIzt8GHcyyTphTw==) group: ${GROUP_ID:DEFAULT_GROUP_DEV} refresh-enabled: true enabled: true bootstrap: enabled: true # nacos:${spring.application.name}-dev.yaml?group=DEFAULT_GROUP_DEV&namespace=mation&server-addr=127.0.0.1:19110 加密原字符串 config: import: ENC(JHcmATdBICFlFOLK8R9hSKVu7RTFJp/JHcmATdBICFfw8027w6d3OSfE5fzbrpCz5iMoJ67mfj8xIzt8GHcyyTphTBICFfw8027ww/MrxMidlUDI4XrpA7KbVHDEWsq1qAceSGP==) logging: level: com.alibaba.nacos.client.naming: WARN com.alibaba.nacos: WARN jasypt: encryptor: password: ${JASYPT_PASSWORD}

注: nacos 3.2.3 配置方式已经换成了spring.config.import,但是上面那个spring.cloud.nacos.config 也不能删除，启动会报错

在启动参数中加入密码:

3. 主启动类

package com.work; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cloud.client.discovery.EnableDiscoveryClient; import org.springframework.cloud.context.config.annotation.RefreshScope; /** * @version 1.0 * @Description: 网关启动类 * @Author 天@狼 * @date 2026-07-17 14:32 */ @SpringBootApplication @EnableDiscoveryClient @RefreshScope public class GatewayApplication { private static Log log = LogFactory.getLog(GatewayApplication.class); public static void main(String[] args) { SpringApplication.run(GatewayApplication.class,args); log.info("网关启动成功"); } }

到此，填坑完成,尽情玩刷吧，对你如果有帮助，请给我个赞!