rui-docs/backend/guides/Nacos配置管理规范.md

Nacos 配置管理规范

1. 配置分类

配置类型	文件位置	是否推送 Nacos	说明
本地开发配置	config/application-dev.yml	❌ 不推送	本地环境专属，已加入 .gitignore
Nacos 配置文件	docs/nacos/*.yaml	✅ 必须推送	所有服务的 Nacos 配置源文件
应用模板	docs/application-template.yml	❌ 不推送	新建模块的模板，不直接推送

2. 核心规则

规则 1：修改必须推送

除 config/application-dev.yml 外，任何对 docs/nacos/*.yaml 的修改必须推送至 Nacos 服务器。

⚠️ 禁止行为：只修改本地文件不推送。这会导致：

• 本地测试正常，线上环境异常
• 多人协作时配置不同步
• 生产环境使用旧配置，引发故障

规则 2：统一推送脚本

使用根目录 push-nacos-config.sh 统一推送：

# 推送所有配置（推荐，确保所有配置同步）
bash push-nacos-config.sh

# 只推送单个配置（快速修复时）
bash push-nacos-config.sh rui-common.yaml

规则 3：推送前检查清单

推送前请确认：

• 配置文件语法正确（YAML 格式）
• 敏感信息使用 ${} 环境变量注入，不硬编码
• 端口配置与 项目实施规范.md 一致
• 修改内容已 git commit

规则 4：推送后验证

推送后必须验证配置是否生效：

# 1. 查看 Nacos 控制台确认配置已更新
# 2. 重启对应服务使配置生效
# 3. 检查服务日志确认配置加载成功

3. 配置文件说明

3.1 公共配置（rui-common.yaml）

配置项	说明	示例
spring.data.redis	Redis 连接配置	host、port、password
spring.jackson	JSON 序列化配置	date-format、time-zone
security.oauth2.ignore-urls	免认证 URL 白名单	/entry/**、/actuator/**
feign.providers	Feign 服务名映射	user、system、auth

3.2 数据配置（rui-data.yaml）

配置项	说明
spring.datasource	MySQL + Druid 连接池配置
mybatis-plus	MyBatis Plus 全局配置

3.3 网关配置（rui-gateway.yaml）

配置项	说明
spring.cloud.gateway.routes	路由规则
grayscale	灰度发布规则

3.4 服务专属配置（rui-service-*.yaml）

配置项	说明
server.port	服务端口

4. 命名空间与分组

环境	命名空间	Group
开发环境	rui-dev	DEFAULT_GROUP
测试环境	rui-test	DEFAULT_GROUP
生产环境	rui-prod	DEFAULT_GROUP

推送脚本默认使用 rui-dev，生产环境推送需手动指定命名空间。

5. 常见问题

Q1: 为什么修改了本地配置但服务没变化？

因为 Spring Cloud 应用启动时会从 Nacos 拉取配置，本地修改不影响运行中的服务。必须推送至 Nacos 后重启服务才能生效。

Q2: 可以同时修改多个配置吗？

可以，但建议每次只修改一个配置文件，避免推送时出错难以排查。

Q3: 推送失败怎么办？

检查以下几点：

1. Nacos 服务器是否可访问（http://192.168.31.210:8848）
2. 用户名密码是否正确（默认 nacos/nacos）
3. 命名空间是否存在（rui-dev）
4. YAML 格式是否正确（缩进、特殊字符等）

Q4: 如何回滚配置？

Nacos 控制台支持配置历史版本回滚，或手动将旧配置内容重新推送。

6. 最佳实践

1. 先修改本地文件 → 测试验证 → git commit → 推送 Nacos → 重启服务
2. 多人协作时，推送前先看一眼 Nacos 控制台的当前配置，避免覆盖他人修改
3. 生产环境配置修改建议先修改测试环境验证，再同步到生产
4. 定期备份 Nacos 配置（导出为文件存档）