docs: 迁移 spring-ai 通用文档到 rui-docs
从 docs-local 迁移以下文档： - backend/guides/: AI开发环境配置、Nacos配置、GitNexus指南、OpenCode工作流等 - backend/templates/: Superpowers设计模板、计划模板、审查清单 - backend/config-templates/: 应用配置模板、Nacos配置 - backend/design/: 数据库表结构规划 - backend/specs/: 项目文档治理、MQ统一推送设计 - backend/: 代码分析报告、Feign分析报告、文档治理报告 - frontend/design/: Admin-UI分模块打包设计
This commit is contained in:
@@ -0,0 +1,120 @@
|
||||
# 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 配置（导出为文件存档）
|
||||
Reference in New Issue
Block a user