1. 项目概述
最近在搭建一个基于JDK21和Spring Boot3.x的新项目,需要集成Nacos3.x作为配置中心和服务发现组件。经过几天的踩坑和实践,终于整理出一套完整的解决方案。本文将分享从Nacos3.x服务部署到Spring Boot项目双配置文件配置的全流程,包含所有关键步骤和避坑指南。
这套方案特别适合需要快速搭建现代化Java微服务架构的开发者,特别是那些想要体验JDK21虚拟线程和Spring Boot3.x新特性的团队。通过本文,你将学会:
- 如何正确部署Nacos3.x服务(含Docker Compose配置)
- Spring Boot3.x项目如何集成Nacos配置中心
- 双配置文件(本地+远程)的最佳实践
- 生产环境下的优化建议
2. 环境准备与Nacos部署
2.1 环境要求
在开始之前,请确保你的开发环境满足以下要求:
| 组件 | 版本要求 | 说明 |
|---|---|---|
| JDK | 21+ | 必须使用21及以上版本以支持虚拟线程 |
| Spring Boot | 3.2.x+ | 适配Jakarta EE规范 |
| Spring Cloud Alibaba | 2025.0.0.0+ | 适配Nacos3.x客户端 |
| Nacos Server | 3.1.1 | 推荐使用稳定版而非latest |
| MySQL | 8.0+ | Nacos3.x外置存储必选 |
注意:Nacos3.x相比2.x版本在架构和配置上有较大变化,务必使用指定版本以避免兼容性问题。
2.2 MySQL数据库初始化
Nacos3.x需要外置MySQL数据库存储配置信息,以下是初始化步骤:
- 创建专用数据库和用户(请替换密码):
sql复制CREATE DATABASE IF NOT EXISTS nacos_config
DEFAULT CHARACTER SET utf8mb4
COLLATE utf8mb4_general_ci;
CREATE USER IF NOT EXISTS 'nacos'@'%'
IDENTIFIED BY 'YourSecurePassword123';
GRANT ALL PRIVILEGES ON nacos_config.* TO 'nacos'@'%';
FLUSH PRIVILEGES;
- 执行Nacos3.1.1的官方初始化脚本:
bash复制wget https://raw.githubusercontent.com/alibaba/nacos/3.1.1/distribution/conf/mysql-schema.sql
mysql -u nacos -p nacos_config < mysql-schema.sql
关键点:Nacos3.x新增了一些表结构,必须使用对应版本的SQL脚本,否则会导致功能异常。
2.3 Docker Compose部署Nacos
推荐使用Docker Compose部署Nacos3.x,以下是完整的docker-compose.yml配置:
yaml复制version: '3.8'
services:
nacos:
image: nacos/nacos-server:v3.1.1
container_name: nacos-3.1.1
restart: always
privileged: true
environment:
- MODE=standalone
# 端口配置(3.x核心变更)
- NACOS_SERVER_PORT=8848 # 客户端SDK通信端口
- SERVER_PORT=8080 # 控制台Web端口
- SERVER_SERVLET_CONTEXT_PATH=/
# JVM内存(3.x最低1G)
- JVM_XMS=1024m
- JVM_XMX=1024m
- JVM_XMN=512m
# MySQL连接配置
- SPRING_DATASOURCE_PLATFORM=mysql
- MYSQL_SERVICE_HOST=your_mysql_host
- MYSQL_SERVICE_PORT=3306
- MYSQL_SERVICE_DB_NAME=nacos_config
- MYSQL_SERVICE_USER=nacos
- MYSQL_SERVICE_PASSWORD=YourSecurePassword123
- MYSQL_SERVICE_DB_PARAM=characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
# 鉴权配置(3.x必填)
- NACOS_AUTH_ENABLE=true
- NACOS_AUTH_TOKEN=YourSecureBase64TokenString
- NACOS_AUTH_IDENTITY_KEY=YourIdentityKey
- NACOS_AUTH_IDENTITY_VALUE=YourIdentityValue
# 关闭自动迁移(避坑)
- NACOS_CONFIG_MIGRATE_ENABLE=false
ports:
- "8080:8080" # 控制台
- "8848:8848" # 客户端
- "8849:8849"
- "9848:9848"
- "9849:9849"
- "9850:9850"
volumes:
- ./logs:/home/nacos/logs
- ./data:/home/nacos/data
networks:
- nacos-network
networks:
nacos-network:
driver: bridge
启动命令:
bash复制docker-compose up -d
docker-compose logs -f nacos # 查看启动日志
关键配置说明:
- NACOS_SERVER_PORT和SERVER_PORT分开配置是Nacos3.x的新特性
- 鉴权配置必须设置,否则会有安全风险
- JVM内存建议不低于1G,否则可能OOM
3. Spring Boot项目配置
3.1 项目依赖配置
首先在pom.xml中添加必要的依赖:
xml复制<properties>
<maven.compiler.source>21</maven.compiler.source>
<maven.compiler.target>21</maven.compiler.target>
<spring-cloud-alibaba.version>2025.0.0.0</spring-cloud-alibaba.version>
<spring-cloud.version>2024.0.0</spring-cloud.version>
</properties>
<dependencies>
<!-- Spring Boot核心依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- Nacos配置中心和服务发现 -->
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<!-- 其他必要依赖... -->
</dependencies>
注意:Spring Boot3.x必须使用Spring Cloud 2024.x和Spring Cloud Alibaba 2025.x版本,否则会有兼容性问题。
3.2 双配置文件配置
Spring Boot项目需要配置两个配置文件:
- application.yml(本地基础配置)
yaml复制spring:
application:
name: jdk21-demo
profiles:
active: dev
config:
import:
- "optional:nacos:${spring.application.name}-${spring.profiles.active}.yaml"
- "optional:nacos:${spring.application.name}.yaml"
cloud:
nacos:
server-addr: localhost:8848
username: nacos
password: nacos
config:
group: DEFAULT_GROUP
file-extension: yaml
discovery:
group: DEFAULT_GROUP
- 在Nacos控制台创建远程配置:
- Data ID: jdk21-demo-dev.yaml
- Group: DEFAULT_GROUP
- 内容示例:
yaml复制server:
port: 8081
app:
name: jdk21-demo
env: dev
配置优先级:Nacos远程配置 > 本地application.yml配置
3.3 启动类配置
启动类需要添加@EnableDiscoveryClient注解:
java复制@SpringBootApplication
@EnableDiscoveryClient
public class Jdk21NacosDemoApplication {
public static void main(String[] args) {
SpringApplication.run(Jdk21NacosDemoApplication.class, args);
}
}
4. 验证与问题排查
4.1 服务启动验证
启动项目后,检查日志中是否有以下内容:
code复制Fetching config from server at : http://localhost:8848
Located environment: name=jdk21-demo, profiles=[dev], label=null
Loaded nacos config: dataId='jdk21-demo-dev.yaml', group='DEFAULT_GROUP'
4.2 常见问题排查
-
配置不生效:
- 检查Data ID是否匹配:${spring.application.name}-${spring.profiles.active}.yaml
- 确认Nacos控制台配置已发布
- 检查项目中的spring.cloud.nacos.config配置是否正确
-
连接Nacos失败:
- 确认Nacos服务已启动且端口开放
- 检查防火墙设置
- 如果是鉴权问题,确认username/password配置正确
-
虚拟线程不生效:
- 确认使用JDK21+
- 在application.yml中配置:spring.threads.virtual.enabled=true
5. 生产环境优化建议
-
安全加固:
- 修改Nacos默认账号密码
- 配置IP白名单
- 启用HTTPS
-
性能优化:
- 调整JVM参数
- 配置Nacos集群
- 启用配置缓存
-
监控告警:
- 集成Prometheus监控
- 配置关键指标告警
- 定期检查日志
这套方案已经在生产环境稳定运行,特别适合需要快速构建现代化Java微服务的团队。通过Nacos3.x的配置中心功能,我们可以实现配置的集中管理和动态更新,大大提高了开发效率和系统可靠性。