Nacos 配置管理完整指南一、核心概念 1. 三大核心标识（定位唯一配置） DataId：配置唯一 ID，常用格式服

一、核心概念

1. 三大核心标识（定位唯一配置）

DataId：配置唯一 ID，常用格式 服务名-环境-配置名.yaml，例 user-service-dev.yaml
Group：配置分组，默认 DEFAULT_GROUP，区分业务模块、租户
Namespace：命名空间，隔离环境（dev/test/prod），默认 public

三元组：Namespace + Group + DataId = 唯一配置文件

2. 配置模型

配置格式：YAML、Properties、JSON、TEXT、XML
配置类型：持久化配置（存数据库）、临时配置（内存，重启丢失）
灰度 / 灰度发布：按客户端 IP、版本灰度推送配置变更

二、Nacos 配置中心核心能力

动态配置推送：配置修改无需重启服务，实时生效
多环境隔离：Namespace 区分开发、测试、生产
配置灰度发布：分批推送，故障快速回滚
配置监听：客户端长轮询感知配置变更
版本回滚：保存历史配置快照，一键回退
权限管控：用户、角色、命名空间读写权限
配置加密：支持明文 / 加密存储数据库密码、密钥

三、SpringBoot / SpringCloud 接入 Nacos Config

1. 依赖（Maven）

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

2. bootstrap.yml（必须用 bootstrap，优先加载配置中心）

spring:
  cloud:
    nacos:
      config:
        # Nacos服务地址
        server-addr: 127.0.0.1:8848
        # 命名空间ID，dev/test/prod
        namespace: dev
        # 分组
        group: DEFAULT_GROUP
        # 配置文件后缀
        file-extension: yaml
        # DataId自动拼接规则：${spring.application.name}-${spring.profiles.active}.${file-extension}
  application:
    name: user-service
  profiles:
    active: dev

自动拼接完整 DataId：user-service-dev.yaml

3. 读取配置两种方式

方式 1：@Value（单个配置）

@RestController
public class ConfigController {
    @Value("${server.port}")
    private Integer port;
    @Value("${custom.name}")
    private String name;
}

方式 2：@ConfigurationProperties（批量绑定）

@Component
@ConfigurationProperties(prefix = "custom")
public class CustomConfig {
    private String name;
    private Integer age;
    // getter/setter
}

4. 配置自动刷新

@RefreshScope（推荐，控制器 / Bean 加注解，变更自动刷新）

@RestController
@RefreshScope
public class ConfigController {}

全局自动刷新（无需注解，配置文件开启）

spring.cloud.nacos.config.refresh-enabled: true

四、Nacos 控制台配置操作

1. 创建配置

命名空间切换至对应环境（dev）
配置管理 → 配置列表 → 新建配置
填写：
- Data ID：user-service-dev.yaml
- 分组：DEFAULT_GROUP
- 配置格式：YAML
- 配置内容：
```
custom:
  name: nacos配置
  age: 18
server:
  port: 8080
```
发布 → 保存

2. 修改 & 发布配置

编辑配置 → 修改内容 → 发布客户端会在30s 内感知变更，自动刷新（长轮询机制）

3. 历史版本回滚

配置列表 → 操作栏「历史版本」→ 选择快照 → 回滚此版本

4. 灰度发布流程

编辑配置 → 灰度发布
选择灰度规则：客户端 IP / 应用版本
填入灰度范围，发布灰度配置
验证无误后：全量发布；异常则终止灰度

五、多配置文件加载（共享配置、扩展配置）

1. 共享公共配置（多服务共用）

spring:
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        namespace: dev
        # 共享配置数组
        shared-configs:
          - data-id: common-dev.yaml
            group: DEFAULT_GROUP
            refresh: true # 开启自动刷新

2. 扩展配置（优先级高于自动拼接 DataId）

extension-configs:
  - data-id: redis-dev.yaml
    refresh: true

加载优先级（从低到高，后面覆盖前面）

共享配置 < 扩展配置 < 自动生成的业务配置

六、配置加密（敏感信息）

1. 内置 AES 加密

Nacos 控制台 → 配置加密工具，明文密码生成密文
配置中使用 {aes}加密字符串

db:
  password: {aes}abc123xyzxxxx

bootstrap 开启加密解析

spring.cloud.nacos.config.encrypt.key: 自定义密钥

七、底层原理：客户端如何感知配置变更

长轮询（Long Polling） 客户端定时（默认 30s）向 Nacos 服务端发起 http 长请求；
- 配置无变更：服务端 hold 住请求 30s 后返回空，客户端立刻发起下一轮轮询
- 配置发生变更：服务端立即返回变更标识，客户端立刻拉取最新配置
本地缓存：配置文件缓存到客户端本地磁盘，服务端宕机可本地兜底

八、常见问题

配置不刷新
- 缺少 @RefreshScope
- refresh-enabled 未开启
- 命名空间、group、dataId 不匹配
bootstrap.yml 不生效缺少 spring-cloud-starter-bootstrap 依赖
启动报错找不到配置核对 namespace ID（不是名称）、环境、DataId 拼写
生产环境配置泄露使用命名空间隔离生产、开启配置加密、控制台账号权限隔离

九、Nacos 配置 vs Spring Cloud Config

表格

特性	Nacos Config	Spring Cloud Config
动态推送	服务端主动感知，长轮询	需手动触发 / 总线 MQ
灰度发布	原生支持	无原生灰度
多环境隔离	Namespace+Group	Profile + 分支
内置控制台	可视化管理	无 UI，依赖 Git
依赖中间件	内置数据库	依赖 Git/MQ