# 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
# 推送所有配置（推荐，确保所有配置同步）
bash push-nacos-config.sh

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

### 规则 3：推送前检查清单

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

### 规则 4：推送后验证

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

```bash
# 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 配置（导出为文件存档）