Spring Boot 3 + Spring Cloud 2024 + Nacos 配置中心完整指南

原创 2025-10-02 10:20:14 1.6k 阅读 AI写同款

收录于

Spring Boot 从入门到精通：掌握现代化后端开发

Spring Cloud 从入门到精通

Spring Cloud Alibaba

龙茶清欢

码龄7年墨衍会员 · AI 创作全网分发

3720粉丝375篇原创

关注

SpringBoot项目接入nacos 注意SpringBoot版本和nacos依赖的版本；CMS的SpringBoot版本是2.5.6，对应的nacos依赖的版本是0.2.12。对应的是 Spring Boot 2.x 版本，版本。对应的是 Spring Boot 1.x 版本。阅读详情

AI摘要

本文详细介绍Spring Boot 3、Spring Cloud 2024与Nacos配置中心的整合方法，涵盖版本兼容性、配置组织、动态刷新、安全实践及运维监控等关键内容，重点说明新版本中spring.config.import替代bootstrap.yml的变化及其最佳实践。

1. 版本兼容性说明

1.1 版本对应关系

组件	版本	说明
Spring Boot	3.2.x	JDK 17+ 要求
Spring Cloud	2023.0.x (aka 2024)	对应 Spring Boot 3.2.x
Spring Cloud Alibaba	2022.0.0.0	对应 Spring Cloud 2023.0.x
Nacos Client	2.2.x	Spring Cloud Alibaba 自动管理
Nacos Server	2.2.x 或 2.3.x	推荐使用最新稳定版

1.2 重要变化

Spring Boot 3：移除了 bootstrap.yml 默认支持，完全推荐使用 spring.config.import
Spring Cloud 2023.0：进一步强化了新配置导入机制
Spring Cloud Alibaba 2022.0.0.0：完全适配 Spring Boot 3 和新配置机制

1.3 Spring Cloud Alibaba 特别说明

Spring Cloud Alibaba：2023.0.1.3 及以上版本 spring.cloud.nacos.config.shared-configs、extension-configs 以及默认加载的 application.name 配置已经废弃，以上版本请统一使用 spring.config.import 方式导入 Nacos 配置，见issue #3998
Spring Cloud 2023：bootstrap.yml 以及 bootstrap.properties 已不推荐使用，请使用 application.yml 或者 application.properties

2. 项目依赖配置

2.1 Maven 依赖

<?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>3.2.0</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>nacos-config-demo</artifactId>
    <version>1.0.0</version>
    <name>nacos-config-demo</name>

    <properties>
        <java.version>17</java.version>
        <spring-cloud.version>2023.0.0</spring-cloud.version>
        <spring-cloud-alibaba.version>2022.0.0.0</spring-cloud-alibaba.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <!-- Spring Cloud 依赖管理 -->
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            
            <!-- Spring Cloud Alibaba 依赖管理 -->
            <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>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <!-- Spring Boot Web Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring Boot Actuator -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

        <!-- Spring Cloud Alibaba Nacos Config -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
        </dependency>

        <!-- Spring Cloud Alibaba Nacos Discovery (可选，如果需要服务发现) -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        </dependency>

        <!-- Spring Cloud 负载均衡，为服务发现提供负载均衡 -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-loadbalancer</artifactId>
        </dependency>

        <!-- Configuration Processor (用于 @ConfigurationProperties 提示) -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>

        <!-- Lombok (可选) -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

2.2 Gradle 依赖

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.4'
}

group = 'com.example'
version = '1.0.0'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

ext {
    set('springCloudVersion', "2023.0.0")
    set('springCloudAlibabaVersion', "2022.0.0.0")
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-config'
    implementation 'com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-discovery'
    annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
        mavenBom "com.alibaba.cloud:spring-cloud-alibaba-dependencies:${springCloudAlibabaVersion}"
    }
}

3. Nacos 配置中心配置文件组织

3.1 配置文件命名规范

Nacos 中的配置文件命名遵循以下规则：

${spring.application.name}-${spring.profiles.active}.${file-extension}

示例：

应用名称：user-service
环境：dev
文件格式：yaml

Nacos 配置文件名：user-service-dev.yaml

3.2 Nacos 配置管理界面设置

在 Nacos 控制台中创建配置：

Data ID: user-service-dev.yaml
Group: DEFAULT_GROUP (或自定义分组)
配置格式: YAML
配置内容: YAML 格式的配置内容

3.3 本地配置文件结构

src/main/resources/
├── application.yml           # 公共配置（Nacos 未覆盖的配置）
├── application-dev.yml       # 开发环境本地配置
├── application-test.yml      # 测试环境本地配置  
├── application-staging.yml   # 预发布环境本地配置
└── application-prod.yml      # 生产环境本地配置

4. 详细配置文件示例

4.1 application.yml（主配置文件）

# application.yml - 主应用配置文件
# 说明：包含应用的基础配置和 Nacos 连接信息
# 注意：Spring Boot 3 + Spring Cloud 2024 使用 spring.config.import 方式

# 应用基本信息
spring:
  application:
    name: user-service

  # Nacos 配置中心配置（基础连接信息）
  cloud:
    # 负载均衡配置
    loadbalancer:
      nacos:
        enabled: true
    nacos:
      # Nacos 服务器地址
      server-addr: ${NACOS_SERVER_ADDR:localhost:8848}
      # 用户名和密码（如果 Nacos 启用了认证）
      username: ${NACOS_USERNAME:nacos}
      password: ${NACOS_PASSWORD:nacos}

      # 配置中心特定配置
      config:
        # 是否启用配置中心
        enabled: true
        # 配置中心文件配置是否支持动态刷新
        refresh-enabled: true
        # 命名空间（可选，用于环境隔离）
        namespace: ${NACOS_NAMESPACE:}
        # 配置分组
        group: DEFAULT_GROUP
        # 配置文件扩展名
        file-extension: yaml
        # 文件编码
        encode: UTF-8
        # 配置超时时间（毫秒）
        timeout: 3000
        # 最大重试次数
        max-retry: 3
        # 重试间隔（毫秒）
        config-retry-time: 2000
        # 是否启用配置监听
        enable-remote-sync-config: true
        # 配置导入（Spring Boot 3 新方式）
        import-check:
          enabled: true

      # 服务发现配置（如果使用）
      discovery:
        # 是否启用服务发现
        enabled: true
        # 命名空间（可选，用于环境隔离）
        namespace: ${NACOS_NAMESPACE:}
        # 服务分组
        group: DEFAULT_GROUP

  # 配置导入（关键！Spring Boot 3 的新方式）
  config:
    import:
      # 导入 Nacos 配置
      - optional:nacos:${spring.application.name}.yaml
      # 导入环境特定的 Nacos 配置
      - optional:nacos:${spring.application.name}-${spring.profiles.active:default}.yaml
      # 导入共享配置
      - optional:nacos:common-config.yaml
      - optional:nacos:application.yaml?group=DEFAULT_GROUP&refreshable=true

# 服务器配置
server:
  port: 8080
  servlet:
    context-path: /api

# Actuator 配置
management:
  endpoints:
    web:
      exposure:
        include: health,info,configprops,env,refresh
  endpoint:
    health:
      show-details: always

# 日志配置
logging:
  level:
    root: INFO
    com.example: DEBUG
    com.alibaba.nacos: WARN

# 自定义业务配置（会被 Nacos 配置覆盖）
user:
  service:
    cache-expire-time: 3600
    max-registration-count: 10000
    enable-email-verification: true

4.2 application-dev.yml（开发环境配置）

# application-dev.yml - 开发环境配置文件
# 说明：开发环境特定配置，Nacos 中的同名配置会覆盖此文件

spring:
  profiles:
    active: dev
  
  # 开发环境 Nacos 配置
  cloud:
    nacos:
      server-addr: localhost:8848
      config:
        namespace: dev-namespace  # 开发环境命名空间
        group: DEV_GROUP
        file-extension: yaml

  # 配置导入（环境特定）
  config:
    import:
      - optional:nacos:${spring.application.name}-dev.yaml
      - optional:nacos:common-config-dev.yaml

# 服务器配置
server:
  port: 8081

# 开发环境数据库配置（会被 Nacos 覆盖）
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/user_db_dev
    username: dev_user
    password: dev_password

# 开发环境自定义配置
user:
  service:
    cache-expire-time: 60      # 开发环境短缓存
    enable-email-verification: false  # 开发环境不启用邮箱验证

# 开发环境日志
logging:
  level:
    root: DEBUG
    com.example: DEBUG
    org.springframework.web: DEBUG

4.3 application-test.yml（测试环境配置）

# application-test.yml - 测试环境配置文件

spring:
  profiles:
    active: test
  
  cloud:
    nacos:
      server-addr: test-nacos:8848
      config:
        namespace: test-namespace
        group: TEST_GROUP
        file-extension: yaml

  config:
    import:
      - optional:nacos:${spring.application.name}-test.yaml
      - optional:nacos:common-config-test.yaml

# 测试环境服务器配置
server:
  port: 8082

# 测试环境数据源（使用 H2 内存数据库）
spring:
  datasource:
    driver-class-name: org.h2.Driver
    url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1
    username: sa
    password: 

# 测试环境自定义配置
user:
  service:
    cache-expire-time: 10      # 测试环境极短缓存
    max-registration-count: 999999
    enable-email-verification: false

# 测试环境日志
logging:
  level:
    root: INFO
    com.example: DEBUG
    org.springframework.test: DEBUG

4.4 application-staging.yml（预发布环境配置）

# application-staging.yml - 预发布环境配置文件

spring:
  profiles:
    active: staging
  
  cloud:
    nacos:
      server-addr: staging-nacos-cluster:8848
      username: ${NACOS_STAGING_USERNAME}
      password: ${NACOS_STAGING_PASSWORD}
      config:
        namespace: staging-namespace
        group: STAGING_GROUP
        file-extension: yaml

  config:
    import:
      - nacos:${spring.application.name}-staging.yaml  # 非 optional，必须存在
      - nacos:common-config-staging.yaml

# 预发布环境服务器配置
server:
  port: 8080
  ssl:
    enabled: true
    key-store: classpath:staging-keystore.p12
    key-store-password: ${SSL_KEYSTORE_PASSWORD}

# 预发布环境自定义配置
user:
  service:
    cache-expire-time: 3600    # 1小时缓存
    max-registration-count: 500000
    enable-email-verification: true

# 预发布环境日志
logging:
  level:
    root: INFO
    com.example: INFO

4.5 application-prod.yml（生产环境配置）

# application-prod.yml - 生产环境配置文件

spring:
  profiles:
    active: prod
  
  cloud:
    nacos:
      server-addr: ${NACOS_PROD_SERVER_ADDR}  # 从环境变量获取
      username: ${NACOS_PROD_USERNAME}
      password: ${NACOS_PROD_PASSWORD}
      config:
        namespace: ${NACOS_PROD_NAMESPACE}
        group: PROD_GROUP
        file-extension: yaml
        timeout: 5000
        max-retry: 5

  config:
    import:
      - nacos:${spring.application.name}-prod.yaml  # 必须存在
      - nacos:common-config-prod.yaml

# 生产环境服务器配置
server:
  port: 8080
  servlet:
    context-path: /api
  tomcat:
    max-threads: 500
    min-spare-threads: 25
    connection-timeout: 10000

# 生产环境自定义配置
user:
  service:
    cache-expire-time: 7200    # 2小时缓存
    max-registration-count: 1000000
    enable-email-verification: true

# 生产环境 Actuator（严格限制）
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      show-details: when_authorized

# 生产环境日志
logging:
  level:
    root: WARN
    com.example: INFO
  file:
    name: /var/log/user-service/user-service.log
    max-size: 100MB
    max-history: 90

5. Nacos 配置中心中的配置示例

5.1 user-service-dev.yaml（Nacos 中）

# Nacos 配置：user-service-dev.yaml
# Group: DEV_GROUP
# Namespace: dev-namespace

# 数据源配置（覆盖本地配置）
spring:
  datasource:
    url: jdbc:mysql://dev-mysql-cluster:3306/user_db_dev
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5

# Redis 配置
spring:
  redis:
    host: dev-redis-cluster
    port: 6379
    database: 1
    timeout: 2000

# 业务配置（覆盖本地配置）
user:
  service:
    cache-expire-time: 300    # 5分钟缓存（覆盖本地的60秒）
    sms-api-url: https://dev-sms-api.example.com
    sms-api-key: ${SMS_API_KEY}

# 第三方服务配置
third-party:
  payment:
    gateway-url: https://dev-payment-gateway.example.com
    merchant-id: dev-merchant-123

5.2 user-service-prod.yaml（Nacos 中）

# Nacos 配置：user-service-prod.yaml
# Group: PROD_GROUP  
# Namespace: prod-namespace

# 生产数据源配置
spring:
  datasource:
    url: jdbc:mysql://prod-mysql-cluster:3306/user_db_prod?useSSL=true
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: 50
      minimum-idle: 10
      connection-timeout: 20000
      idle-timeout: 300000
      max-lifetime: 1200000

# 生产 Redis 配置
spring:
  redis:
    cluster:
      nodes:
        - prod-redis-1:7000
        - prod-redis-2:7001  
        - prod-redis-3:7002
    timeout: 2000
    lettuce:
      pool:
        max-active: 20
        max-idle: 10

# 生产业务配置
user:
  service:
    cache-expire-time: 7200    # 2小时缓存
    max-registration-count: 10000000
    enable-email-verification: true
    email-verification-expire-hours: 48
    sms-api-url: https://prod-sms-api.example.com
    sms-api-key: ${SMS_API_KEY}

# 安全配置
security:
  jwt:
    secret: ${JWT_SECRET}
    expiration: 259200000  # 3天

# 监控配置
monitoring:
  apm:
    enabled: true
    server-url: https://prod-apm.example.com

5.3 common-config.yaml（Nacos 共享配置）

# Nacos 配置：common-config.yaml
# Group: DEFAULT_GROUP
# 适用于所有环境的共享配置

# 公共业务配置
app:
  version: 1.0.0
  build-time: ${BUILD_TIME}
  contact-email: support@example.com

# 公共第三方服务配置
third-party:
  common:
    timeout: 5000
    retry:
      max-attempts: 3
      backoff-multiplier: 2.0

# 公共安全配置
security:
  cors:
    allowed-origins:
      - https://example.com
      - https://www.example.com
    allowed-methods:
      - GET
      - POST
      - PUT
      - DELETE
    allowed-headers: "*"
    allow-credentials: true

6. 高级配置特性

6.1 配置动态刷新

6.1.1 使用 @RefreshScope

@RestController
@RefreshScope  // 支持配置动态刷新
public class UserController {
    
    @Value("${user.service.cache-expire-time}")
    private int cacheExpireTime;
    
    @Value("${user.service.max-registration-count}")
    private int maxRegistrationCount;
    
    @GetMapping("/config")
    public Map<String, Object> getConfig() {
        Map<String, Object> config = new HashMap<>();
        config.put("cacheExpireTime", cacheExpireTime);
        config.put("maxRegistrationCount", maxRegistrationCount);
        return config;
    }
}

6.2.2 使用 @ConfigurationProperties

@Data
@Component
@ConfigurationProperties(prefix = "user.service")
@RefreshScope  // 支持动态刷新
public class UserServiceProperties {
    
    private int cacheExpireTime = 3600;
    
    private int maxRegistrationCount = 10000;
    
    private boolean enableEmailVerification = true;
    
    private int emailVerificationExpireHours = 24;
    
    private String smsApiUrl;
    
    private String smsApiKey;
}

6.2.3 手动触发刷新

# POST 请求触发配置刷新
curl -X POST http://localhost:8080/actuator/refresh

# 返回被刷新的属性列表
["user.service.cache-expire-time", "user.service.max-registration-count"]

6.3 配置监听器

@Component
public class NacosConfigListener {
    
    private static final Logger log = LoggerFactory.getLogger(NacosConfigListener.class);
    
    @EventListener
    public void handleConfigChangeEvent(RefreshScopeRefreshedEvent event) {
        log.info("配置已刷新: {}", event);
        // 执行自定义逻辑
    }
    
    // 或者监听具体的配置变化
    @EventListener
    public void handleEnvironmentChangeEvent(EnvironmentChangeEvent event) {
        Set<String> changedKeys = event.getKeys();
        log.info("变化的配置项: {}", changedKeys);
    }
}

7. 安全配置最佳实践

7.1 敏感信息处理

# ❌ 错误做法：硬编码敏感信息
spring:
  datasource:
    password: "hardcoded_password"

# ✅ 正确做法：使用环境变量
spring:
  datasource:
    password: ${DB_PASSWORD}

# ✅ 更好的做法：使用 Nacos 的加密功能
spring:
  datasource:
    password: ENC(encrypted_password_here)

7.2 Nacos 认证配置

# application.yml
spring:
  cloud:
    nacos:
      server-addr: ${NACOS_SERVER_ADDR}
      # 启用认证
      username: ${NACOS_USERNAME}
      password: ${NACOS_PASSWORD}
      # 或使用 AccessKey/SecretKey
      access-key: ${NACOS_ACCESS_KEY}
      secret-key: ${NACOS_SECRET_KEY}

7.3 配置加密

// 配置解密处理器
@Configuration
public class EncryptionConfig {
    
    @Bean
    public TextEncryptor textEncryptor() {
        // 使用 Jasypt 或其他加密库
        return new AesTextEncryptor("encryption-key");
    }
}

8. 部署和运维

8.1 Docker 环境变量配置

# Dockerfile
FROM openjdk:17-jdk-slim

COPY target/user-service.jar app.jar

ENV NACOS_SERVER_ADDR=nacos-cluster:8848
ENV NACOS_NAMESPACE=prod-namespace  
ENV DB_PASSWORD=your-db-password
ENV JWT_SECRET=your-jwt-secret

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "/app.jar"]

8.2 启动参数覆盖

# 命令行参数优先级最高
java -jar user-service.jar \
  --spring.profiles.active=prod \
  --spring.cloud.nacos.server-addr=prod-nacos:8848 \
  --user.service.cache-expire-time=1800

9. 故障排查和监控

9.1 配置加载日志

# 启用详细日志
logging:
  level:
    com.alibaba.nacos: DEBUG
    org.springframework.cloud.bootstrap: DEBUG
    org.springframework.boot.context.config: DEBUG

9.2 Actuator 端点

# 查看所有配置属性
GET /actuator/env

# 查看特定属性
GET /actuator/env/user.service.cache-expire-time

# 查看配置属性源
GET /actuator/configprops

# 查看 Nacos 配置状态
GET /actuator/nacosconfig

9.3 健康检查

@Component
public class NacosConfigHealthIndicator extends AbstractHealthIndicator {
    
    @Override
    protected void doHealthCheck(Health.Builder builder) throws Exception {
        // 检查 Nacos 连接状态
        if (nacosConfigService.isConnected()) {
            builder.up().withDetail("status", "connected");
        } else {
            builder.down().withDetail("status", "disconnected");
        }
    }
}

10. 总结和最佳实践

10.1 配置组织原则

环境隔离：使用 Nacos 命名空间或 Group 隔离不同环境
配置分层：
- 共享配置：common-config.yaml
- 应用配置：{app-name}.yaml
- 环境配置：{app-name}-{profile}.yaml
敏感信息：绝不硬编码，使用环境变量或加密
版本控制：Nacos 配置变更应有审计和回滚机制