适配版本：Nacos Server 3.1.1、Nacos Client 3.1.1、Spring Cloud Alibaba 2025.1.0.0、Spring Boot 4.0.8、Spring Cloud 2025.1.3、JDK 21
课程定位：配置中心阶段开篇，从分布式配置痛点出发，掌握Nacos配置中心原理与动态配置实战

一、开篇：为什么需要配置中心

第6-9课我们完成了注册中心阶段的全部内容。服务之间可以互相发现了，但另一个问题浮现出来：配置如何管理？

一个典型的微服务系统中，每个服务都有开发、测试、生产三套环境配置，涉及数据库连接、Redis地址、第三方密钥、限流阈值、业务开关等上百个配置项。传统方式下，这些配置散落在各服务的application.yml中，带来四个致命问题：

问题一：修改配置需要重新打包部署。调整一个限流阈值，需要改代码、打包、发布、重启服务，整个过程至少10分钟。紧急场景下（如大促前临时调整阈值），这种延迟无法接受。

问题二：多环境配置管理混乱。开发、测试、生产三套配置分散在不同文件中，容易搞混。生产环境的数据库密码误配到测试环境，可能导致测试数据污染生产。

问题三：敏感信息明文暴露。数据库密码、API密钥明文写在配置文件中，提交到Git仓库后，任何有代码权限的人都能看到。

问题四：配置变更无版本、无追溯。谁在什么时候改了哪个配置？出了问题想回滚到上一个版本？传统方式下无从回答。

Nacos Config正是为解决这些问题而设计的分布式配置中心。本课将从架构原理讲到动态刷新实战，完整覆盖Nacos配置中心的核心能力。

二、Nacos Config核心架构与配置推送原理

2.1 配置模型：Namespace + Group + DataId

Nacos配置模型采用三层标识来唯一定位一份配置：

层级	作用	默认值
Namespace	环境级别隔离（开发/测试/生产）	public
Group	业务/团队级别隔离	DEFAULT_GROUP
DataId	配置的唯一标识（通常是应用名+后缀）	${spring.application.name}

一份配置由 namespaceId + groupName + dataId 三元组唯一确定。发布配置时写入该三元组标识的资源，客户端也通过该三元组查找和订阅配置。

2.2 配置推送原理：从长轮询到gRPC

Nacos配置推送机制经历了从长轮询（HTTP Long Polling） 到gRPC长连接的演进。

Nacos 1.x：HTTP长轮询。 客户端发起一次轮询请求到服务端，当服务端的配置没有任何变更时，这个连接会一直打开，直到服务端有配置变更或者连接超时之后才返回。客户端默认的长轮询超时时间为30秒，服务端在收到请求后，如果在29.5秒内没有配置变更，就等待到超时后返回；如果期间发生了配置变更，立即返回变更通知。

Nacos 2.x/3.x：gRPC长连接。 Nacos 2.x相比1.x最大的架构升级在于通信协议——从HTTP短连接升级为gRPC长连接。客户端与服务端建立一个基于gRPC的持久双向流连接，服务端可以通过该连接主动推送配置变更，延迟更低。

3.x的重要变化：Nacos 3.x Client OpenAPI不再提供HTTP长轮询的配置监听能力。如果需要进行配置监听，必须使用官方SDK中的长连接支持。这意味着在Spring Cloud Alibaba 2025.1.0.0中，配置监听底层完全依赖gRPC长连接。

2.3 配置推送的设计哲学：轻量通知 + 主动拉取

Nacos的配置推送采用了一个务实的设计：推送消息是轻量的，只携带变更的配置标识（DataId + Group），客户端收到通知后重新查询配置内容。

这个设计有两个好处：

• 推送消息本身很小，网络开销低
• 最终内容仍然走正常的查询路径，保证内容一致性

关键原则：不要把变更推送当作配置内容本身。收到通知后，必须重新查询以获取最新内容。

三、2025版适配：关键变化

3.1 Bootstrap废弃，spring.config.import全面替代

这是Spring Cloud Alibaba 2025.1.0.0最关键的破坏性变更。官方文档明确说明：2025.1.x版本已明确废弃Spring Cloud Bootstrap引导启动方式，不再支持通过bootstrap.yml/bootstrap.properties接入Nacos。

在旧版本中，Nacos Config的连接信息写在bootstrap.yml中。在2025.1.x中，必须迁移到application.yml并使用spring.config.import：

spring:
  application:
    name: service-user
  config:
    import:
      - optional:nacos:service-user.yaml
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848

为什么做此改动？ Bootstrap上下文作为主应用上下文的父容器存在，这种“双上下文”模式导致启动速度变慢，且父子容器间的属性覆盖逻辑复杂。spring.config.import机制在单一上下文中完成所有配置解析与加载，提升启动效率。

optional:前缀的作用：表示如果配置不存在不报错。如果省略optional:，当Nacos中不存在对应配置时，应用启动会直接失败。

踩坑提示：如果引入了spring-cloud-starter-alibaba-nacos-config但未配置spring.config.import，启动时会报错。可以通过spring.cloud.nacos.config.import-check.enabled=false关闭检测，但不建议这么做——该检查能帮助你发现多余的依赖。

3.2 敏感字段自动脱敏

Spring Cloud Alibaba 2025.1.0.0引入了敏感字段掩码功能。系统会非侵入式地拦截Nacos配置对象的序列化过程，对password、secret、token等关键词对应的值进行自动脱敏处理。这是一项开箱即用的安全增强，无需修改任何业务代码。

四、基础配置加载实战

4.1 添加依赖

在 service-user 模块的POM中添加Nacos Config依赖：

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

版本由父POM中导入的Spring Cloud Alibaba BOM统一管理。

4.2 在Nacos控制台创建配置

登录Nacos控制台（http://localhost:8080），进入配置管理 → 配置列表，点击“创建配置”：

• Data ID：service-user.yaml
• Group：DEFAULT_GROUP
• 配置格式：YAML
• 配置内容：

app:
  name: service-user
  version: 1.0.0
  feature:
    new-user-register: true

4.3 配置application.yml

在 service-user/src/main/resources/application.yml 中：

server:
  port: 8081

spring:
  application:
    name: service-user
  config:
    import:
      - optional:nacos:service-user.yaml
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        namespace: public
        group: DEFAULT_GROUP
        file-extension: yaml
      username: nacos
      password: nacos

配置项说明：

配置项	说明	默认值
server-addr	Nacos Server地址	无，必须配置
prefix	DataId前缀	${spring.application.name}
group	配置分组	DEFAULT_GROUP
file-extension	DataId后缀及内容格式	properties
namespace	命名空间ID	public

4.4 读取配置

方式一：@Value + @RefreshScope

@RestController
@RefreshScope
public class ConfigController {

    @Value("${app.name:default}")
    private String appName;

    @Value("${app.feature.new-user-register:false}")
    private boolean newUserRegister;

    @GetMapping("/config")
    public Result<String> getConfig() {
        return Result.success("appName=" + appName + ", newUserRegister=" + newUserRegister);
    }
}

方式二：@ConfigurationProperties（推荐）

@Component
@RefreshScope
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    private String version;
    private Feature feature;

    // getter / setter
    public static class Feature {
        private boolean newUserRegister;
        // getter / setter
    }
}

五、动态刷新机制深度解析

5.1 @RefreshScope的工作原理

@RefreshScope是Spring Cloud Commons提供的一个特殊作用域，用于标记那些需要在运行时动态重新加载配置的Bean。

核心机制：被@RefreshScope标记的Bean会被代理包装。当触发配置刷新事件时，这些Bean的缓存实例会被销毁，下次调用时重建并注入最新配置。它基于@Scope("refresh")的作用域代理实现，被Bean工厂创建后会加入refresh scope的Bean缓存中。

重要限制：只有通过@Value或@ConfigurationProperties注入的属性才能被刷新；静态字段、构造器注入均不支持。

5.2 完整刷新链路

Nacos配置变更到@RefreshScope生效的完整链路如下：

Nacos Server
    ↓ (gRPC推送变更通知，仅携带DataId+Group)
Nacos Client (com.alibaba.nacos.client)
    ↓ (回调Listener，重新查询配置内容)
NacosContextRefresher (Spring Cloud Alibaba)
    ↓ (发布RefreshEvent事件)
RefreshEventListener (Spring Cloud Commons)
    ↓ (调用refreshAll())
RefreshScope
    ↓ (销毁缓存Bean实例，下次调用时重建)
Your @RefreshScope Bean → 使用新配置

整个过程无需手动调用 /actuator/refresh，由Nacos客户端自动完成。

5.3 配置刷新开关

spring.cloud.nacos.config.refresh.enabled控制是否启用自动刷新，默认为true。如果需要关闭：

spring:
  cloud:
    nacos:
      config:
        refresh:
          enabled: false

踩坑提示：spring.config.import中的refreshEnabled参数与上述配置项不同。在spring.config.import中，可以通过?refreshEnabled=true显式开启刷新：

spring:
  config:
    import:
      - nacos:service-user.yaml?refreshEnabled=true

六、配置优先级与多环境管理

6.1 配置加载优先级

Nacos配置加载的完整优先级（从低到高）为：

主配置 (dataId=${spring.application.name})
    < 共享配置 (shared-configs)
    < 扩展配置 (extension-configs)
    < 本地配置 (application.yml)
    < 命令行参数

核心规则：后加载的配置会覆盖先加载的。因此，本地配置的优先级高于Nacos远程配置。这意味着如果application.yml中定义了server.port=8081，而Nacos中也有server.port=9090，最终生效的是8081。

6.2 共享配置与扩展配置

共享配置（shared-configs） ：多个服务共享的配置，如公共的Redis地址、日志配置。

spring:
  cloud:
    nacos:
      config:
        shared-configs:
          - dataId: common-redis.yaml
            group: DEFAULT_GROUP
            refresh: true
          - dataId: common-logging.yaml
            group: DEFAULT_GROUP
            refresh: true

扩展配置（extension-configs） ：为特定服务提供额外的配置。

spring:
  cloud:
    nacos:
      config:
        extension-configs:
          - dataId: service-user-feature.yaml
            group: DEFAULT_GROUP
            refresh: true

踩坑提示：shared-configs和extension-configs的refresh字段默认为false。如果不显式设置为true，配置变更不会触发自动刷新。

6.3 多环境配置方案

方案一：通过Namespace隔离环境。

# application-dev.yml
spring.cloud.nacos.config.namespace: dev

# application-prod.yml
spring.cloud.nacos.config.namespace: prod

启动时通过--spring.profiles.active=dev指定环境。

方案二：通过DataId后缀区分环境。

spring:
  config:
    import:
      - optional:nacos:service-user-dev.yaml

推荐方案：优先使用Namespace隔离环境，因为不同环境的服务在Nacos控制台中完全隔离，避免误操作。

七、配置加密实战

Nacos提供了配置加密功能，用于保护数据库密码、API密钥等敏感信息。

7.1 AES加密插件

Nacos通过SPI机制抽象加解密操作，默认提供AES实现。客户端和服务端都需要添加以下依赖：

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-aes-encryption-plugin</artifactId>
    <version>${nacos-aes-encryption-plugin.version}</version>
</dependency>

7.2 创建加密配置

在Nacos控制台创建配置时，DataId使用cipher-aes-前缀标识该配置需要加密：

cipher-aes-service-user.yaml

系统会自动识别并加密。配置在传输过程中是密文的，控制台发布的配置会在服务端进行处理。客户端读取时自动解密。

7.3 数据库表结构变更

使用配置加密功能前，需要确保数据库表config_info、config_info_beta、his_config_info中已添加encrypted_data_key字段，用于存储每个配置项加密使用的密钥。

八、踩坑指南

坑一：Bootstrap未迁移到spring.config.import

现象：服务启动时报No spring.config.import property has been defined。

原因：2025.1.x已废弃bootstrap.yml，必须使用spring.config.import。

解决：将配置迁移到application.yml，添加spring.config.import: optional:nacos:xxx.yaml。

坑二：@RefreshScope未添加导致配置不刷新

现象：Nacos中修改了配置，但服务中的@Value字段仍是旧值。

原因：未添加@RefreshScope注解。

解决：在需要动态刷新的Bean上添加@RefreshScope。注意：@ConfigurationProperties类也需要@RefreshScope才能动态刷新。

坑三：shared-configs的refresh默认为false

现象：共享配置修改后不生效。

原因：shared-configs和extension-configs的refresh字段默认为false。

解决：显式设置refresh: true。

坑四：本地配置覆盖了远程配置

现象：Nacos中配置了server.port=9090，但服务仍使用本地application.yml中的8081。

原因：本地配置优先级高于Nacos远程配置。

解决：这是设计行为。如果需要远程配置优先生效，从本地application.yml中移除该配置项，或使用spring.cloud.config.override-none等配置项调整覆盖策略。

坑五：静态字段无法刷新

现象：static修饰的配置字段无法动态刷新。

原因：@RefreshScope通过代理实现，静态字段不经过代理。

解决：将静态字段改为实例字段，或使用@ConfigurationProperties。

九、课后作业

作业一：在Nacos控制台创建service-user.yaml配置，包含app.feature.new-user-register开关。在service-user中通过@Value和@ConfigurationProperties两种方式读取，并通过/config接口验证。

作业二：在Nacos控制台修改app.feature.new-user-register的值，观察@RefreshScope Bean是否自动刷新。记录从修改到生效的时间。

作业三：创建shared-configs共享配置common-config.yaml，在service-user和service-order中同时引入，验证共享配置的加载。注意设置refresh: true。

作业四（进阶） ：配置Nacos AES加密插件，创建cipher-aes-service-user.yaml加密配置，在服务中读取并验证解密是否正常。

十、下节预告

第11课将进入多环境、多服务配置隔离 & 配置优先级详解。我们将深入命名空间+分组+DataId三层隔离的实战配置，多环境配置切换的完整方案，配置文件优先级的精确控制，本地配置与远程配置的覆盖规则，以及公共配置的继承机制。配置中心阶段的Nacos Config核心能力将在本课基础上进一步深化。

🔗《最新版 SpringCloud 2025 从入门到实战》系列课程导航

去订阅

第一部分：微服务前置基础 & 新版环境搭建（第1-5课）
第二部分：注册中心核心（Nacos 最新版）（第6-9课）
第三部分：配置中心核心（Nacos配置中心）（第10-12课）
第四部分：服务通信核心（OpenFeign + LoadBalancer）（第13-16课）
第五部分：网关核心（SpringCloud Gateway 新版）（第17-20课）
第六部分：熔断、限流、降级（Sentinel 新版）（第21-24课）
第七部分：微服务监控、链路追踪、日志体系（第25-28课）
第八部分：微服务高阶特性 & 分布式核心能力（第29-31课）
第九部分：企业级完整项目实战 & 架构复盘（第32-35课）