@llryiop/avatar-boot-cli 1.0.0

package/templates/.claude/skills/avatar-boot-starter-nacos/SKILL.md

@@ -0,0 +1,901 @@
+---
+name: avatar-boot-nacos-config
+description: Avatar Boot Nacos 配置完整参考 - 服务发现、配置中心和 Spring Cloud Alibaba 集成。当用户提到 Nacos、服务发现、配置中心、配置管理、Spring Cloud Alibaba、服务注册、动态配置时使用此技能，或当用户正在编辑涉及 Nacos 设置的 application.yml/application.properties 文件时触发。当用户询问微服务配置、环境隔离（使用命名空间的 dev/test/prod）、共享配置或排查 Nacos 连接问题时也应触发。此技能提供配置示例、生成完整配置文件、验证最佳实践并提供故障排查指导。
+---
+
+# Avatar Boot Nacos 配置参考
+
+Avatar Boot 应用中配置 Nacos 服务发现和配置管理的完整指南。
+
+## 快速开始
+
+### ⚠️ 重要：Spring Cloud Alibaba 2023.x 配置要求
+
+**Spring Cloud Alibaba 2023.x 强制要求**使用 `spring.config.import` 声明 Nacos 配置源，否则会报错：
+- `No spring.config.import property has been defined`
+- `dataId must be specified`
+
+### 最小配置
+
+**application.yml** (主配置):
+```yaml
+spring:
+  application:
+    name: my-service  # 必填：服务名称
+
+server:
+  port: 8080
+```
+
+**application-dev.yml** (环境配置):
+```yaml
+spring:
+  config:
+    import:
+      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+
+  cloud:
+    nacos:
+      server-addr: 127.0.0.1:8848  # 必填：Nacos 服务器地址
+      namespace: ${NACOS_NAMESPACE:dev}
+      username: ${NACOS_USERNAME:nacos}
+      password: ${NACOS_PASSWORD:nacos}
+
+      config:
+        enabled: true
+        file-extension: yaml
+        group: DEFAULT_GROUP
+
+      discovery:
+        enabled: true
+        register-enabled: true
+        ephemeral: true
+```
+
+### 添加依赖
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-nacos</artifactId>
+</dependency>
+```
+
+版本由 `avatar-boot-dependency` BOM 管理 - 永远不要显式指定版本。
+
+## 配置方式
+
+### ⚠️ Spring Cloud Alibaba 2023.x 唯一推荐方式
+
+**必须使用 `spring.config.import`**，这是 Spring Cloud Alibaba 2023.x 的强制要求。
+
+#### 正确的配置格式
+
+```yaml
+spring:
+  application:
+    name: avatar-demo-service
+
+  config:
+    import:
+      # 应用配置
+      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+      # 共享配置
+      - optional:nacos:common-database.yaml?group=SHARED_GROUP&refreshEnabled=true
+      - optional:nacos:common-redis.yaml?group=SHARED_GROUP&refreshEnabled=true
+
+  cloud:
+    nacos:
+      server-addr: 127.0.0.1:8848
+      namespace: ${NACOS_NAMESPACE:}
+      username: ${NACOS_USERNAME:nacos}
+      password: ${NACOS_PASSWORD:nacos}
+
+      config:
+        enabled: true
+        file-extension: yaml
+        group: DEFAULT_GROUP
+
+      discovery:
+        enabled: true
+        register-enabled: true
+        ephemeral: true
+        group: DEFAULT_GROUP
+        metadata:
+          version: 1.0.0
+          environment: ${spring.profiles.active:dev}
+```
+
+**格式说明**:
+- `optional:` - 配置不存在时不会导致启动失败（推荐）
+- `nacos:` - 指定配置源类型
+- `{dataId}` - 配置文件的 Data ID，可使用变量 `${spring.application.name}`
+- `?group=XXX` - 指定配置分组（必需）
+- `&refreshEnabled=true` - 启用配置自动刷新
+
+#### ❌ 常见错误
+
+```yaml
+# 错误 1: 缺少 spring.config.import
+spring:
+  cloud:
+    nacos:
+      config:
+        enabled: true  # ❌ 会报错: No spring.config.import property has been defined
+
+# 错误 2: 空的 dataId
+spring:
+  config:
+    import:
+      - "nacos:"  # ❌ 会报错: dataId must be specified
+
+# 错误 3: 变量未解析
+spring:
+  config:
+    import:
+      - "optional:nacos:${spring.applicyaml"  # ❌ 缺少 group 参数
+
+# 错误 4: 位置错误
+spring:
+  cloud:
+    nacos:
+      config:
+        import:  # ❌ 应该在 spring.config.import，不是这里
+          - "nacos:xxx"
+
+# 错误 5: spring.application.name 定义位置错误
+spring:
+  config:
+    activate:
+      on-profile: dev  # ❌ 不应该在主配置文件中
+  application:
+    name: my-service
+```
+
+#### ✅ 推荐的配置结构
+
+**application.yml** (主配置 - 所有环境共享):
+```yaml
+spring:
+  application:
+    name: avatar-demo-service  # 必须在主配置文件中定义
+
+server:
+  port: 8080
+```
+
+**application-dev.yml** (开发环境):
+```yaml
+spring:
+  config:
+    import:
+      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+      - optional:nacos:common-database.yaml?group=SHARED_GROUP&refreshEnabled=true
+
+  cloud:
+    nacos:
+      server-addr: 172.29.242.247:8848
+      namespace: dev
+      username: ${NACOS_USERNAME:nacos}
+      password: ${NACOS_PASSWORD:nacos}
+      config:
+        enabled: true
+        file-extension: yaml
+        group: DEFAULT_GROUP
+      discovery:
+        enabled: true
+        register-enabled: true
+        ephemeral: true
+        group: DEFAULT_GROUP
+```
+
+**application-prod.yml** (生产环境):
+```yaml
+spring:
+  config:
+    import:
+      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+      - optional:nacos:common-database.yaml?group=SHARED_GROUP&refreshEnabled=true
+
+  cloud:
+    nacos:
+      server-addr: nacos-prod.example.com:8848
+      namespace: prod
+      username: ${NACOS_USERNAME}  # 从环境变量读取
+      password: ${NACOS_PASSWORD}
+      config:
+        enabled: true
+        file-extension: yaml
+        group: DEFAULT_GROUP
+      discovery:
+        enabled: true
+        register-enabled: true
+        ephemeral: true
+        group: DEFAULT_GROUP
+```
+
+## 配置详解
+
+### 服务发现配置
+
+```yaml
+spring:
+  cloud:
+    nacos:
+      discovery:
+        enabled: true              # 启用服务发现
+        register-enabled: true     # 注册此服务
+        ephemeral: true           # 临时实例（推荐用于云原生）
+        group: DEFAULT_GROUP      # 服务分组
+        cluster-name: DEFAULT     # 集群名称
+        weight: 1.0              # 服务权重（0.01-100.0）
+
+        # 网络设置
+        prefer-ip-address: true   # 使用 IP 而非主机名
+        # ip: 192.168.1.100       # 手动指定 IP（未设置时自动检测）
+        # port: 8080              # 手动指定端口（未设置时使用 server.port）
+        # network-interface: eth0  # 多网卡场景
+
+        # 健康检查
+        heart-beat-interval: 5000      # 心跳间隔（毫秒）
+        heart-beat-timeout: 15000      # 心跳超时（毫秒）
+        ip-delete-timeout: 30000       # IP 删除超时（毫秒）
+
+        # 元数据 - 用于路由/监控的自定义标签
+        metadata:
+          version: 1.0.0
+          environment: ${spring.profiles.active:dev}
+          region: cn-east
+          team: backend
+```
+
+**实例类型：**
+- **临时实例（Ephemeral）**: `ephemeral: true` - 推荐用于云原生
+    - 下线时自动删除
+    - 维护成本低
+    - 适用于：容器、自动扩缩容
+
+- **持久化实例（Persistent）**: `ephemeral: false` - 传统部署
+    - 下线后仍保留
+    - 需要手动清理
+    - 适用于：虚拟机、固定 IP
+
+### 配置中心配置
+
+```yaml
+spring:
+  cloud:
+    nacos:
+      config:
+        enabled: true                    # 启用配置中心
+        file-extension: yaml             # 配置格式：yaml/properties/json/xml
+        group: DEFAULT_GROUP             # 配置分组
+        refresh-enabled: true            # 启用自动刷新
+
+        # 超时和重试
+        timeout: 3000                    # 连接超时（毫秒）
+        config-long-poll-timeout: 46000  # 长轮询超时（毫秒）
+        config-retry-time: 2000          # 重试间隔（毫秒）
+        max-retry: 10                    # 最大重试次数
+
+        # 远程同步
+        enable-remote-sync-config: false
+```
+
+### 多环境配置
+
+使用 **命名空间（namespaces）** 实现环境隔离：
+
+```yaml
+---
+# 开发环境
+spring:
+  config:
+    activate:
+      on-profile: dev
+  cloud:
+    nacos:
+      server-addr: 127.0.0.1:8848
+      namespace: dev-namespace-id
+      config:
+        group: DEV_GROUP
+      discovery:
+        group: DEV_GROUP
+
+---
+# 测试环境
+spring:
+  config:
+    activate:
+      on-profile: test
+  cloud:
+    nacos:
+      server-addr: nacos-test.example.com:8848
+      namespace: test-namespace-id
+      config:
+        group: TEST_GROUP
+      discovery:
+        group: TEST_GROUP
+
+---
+# 生产环境
+spring:
+  config:
+    activate:
+      on-profile: prod
+  cloud:
+    nacos:
+      server-addr: nacos-prod.example.com:8848
+      namespace: prod-namespace-id
+      username: ${NACOS_USERNAME}  # 从环境变量读取
+      password: ${NACOS_PASSWORD}
+      config:
+        group: PROD_GROUP
+      discovery:
+        group: PROD_GROUP
+```
+
+## Nacos 配置文件命名规则
+
+Nacos 按以下顺序自动加载配置：
+
+1. **应用配置**: `${spring.application.name}.${file-extension}`
+    - 示例：`my-service.yaml`
+
+2. **应用+环境配置**: `${spring.application.name}-${profile}.${file-extension}`
+    - 示例：`my-service-dev.yaml`
+
+3. **扩展配置**: 通过 `extension-configs` 指定
+
+4. **共享配置**: 通过 `shared-configs` 指定
+
+**优先级（从高到低）：**
+1. 应用+环境配置
+2. 应用配置
+3. 扩展配置
+4. 共享配置
+
+## 代码使用模式
+
+### 使用 RestTemplate 进行服务发现
+
+```java
+@Configuration
+public class RestTemplateConfig {
+
+    @Bean
+    @LoadBalanced  // 启用服务名解析
+    public RestTemplate restTemplate() {
+        return new RestTemplate();
+    }
+}
+
+@Service
+public class UserService {
+
+    @Autowired
+    private RestTemplate restTemplate;
+
+    public User getUser(Long id) {
+        // 通过服务名调用（而非 IP:端口）
+        return restTemplate.getForObject(
+            "http://user-service/users/" + id,
+            User.class
+        );
+    }
+}
+```
+
+### 使用 @Value 实现动态配置
+
+```java
+@RestController
+@RefreshScope  // 配置热更新必需
+public class ConfigController {
+
+    @Value("${app.feature.enabled:false}")
+    private boolean featureEnabled;
+
+    @GetMapping("/config")
+    public String getConfig() {
+        return "Feature enabled: " + featureEnabled;
+    }
+}
+```
+
+### 使用 @ConfigurationProperties 实现动态配置
+
+```java
+@Component
+@ConfigurationProperties(prefix = "app")
+@RefreshScope  // 配置热更新必需
+@Data
+public class AppConfig {
+    private String name;
+    private String version;
+    private Feature feature;
+
+    @Data
+    public static class Feature {
+        private boolean enabled;
+        private int maxUsers;
+    }
+}
+```
+
+**对应的 Nacos 配置**（Data ID: `my-service.yaml`）：
+
+```yaml
+app:
+  name: My Service
+  version: 1.0.0
+  feature:
+    enabled: true
+    maxUsers: 100
+```
+
+### 监听配置变更
+
+```java
+@Component
+public class ConfigChangeListener {
+
+    @EventListener
+    public void onRefresh(RefreshScopeRefreshedEvent event) {
+        log.info("配置已刷新");
+    }
+
+    @EventListener
+    public void onEnvironmentChange(EnvironmentChangeEvent event) {
+        log.info("环境已变更: {}", event.getKeys());
+    }
+}
+```
+
+## 最佳实践
+
+### 1. 环境隔离策略
+
+**使用命名空间隔离环境：**
+- 开发环境：`dev-namespace`
+- 测试环境：`test-namespace`
+- 生产环境：`prod-namespace`
+
+**使用分组隔离业务域：**
+- 用户服务：`USER_GROUP`
+- 订单服务：`ORDER_GROUP`
+- 支付服务：`PAYMENT_GROUP`
+
+### 2. 配置管理策略
+
+- **公共配置**：使用 `shared-configs` 实现跨应用设置
+- **业务配置**：使用应用专属配置
+- **敏感配置**：使用环境变量或加密配置
+
+### 3. 元数据使用
+
+添加有用的元数据用于路由和监控：
+
+```yaml
+spring:
+  cloud:
+    nacos:
+      discovery:
+        metadata:
+          version: ${project.version}
+          environment: ${spring.profiles.active}
+          region: cn-east
+          team: backend
+          git-commit: ${git.commit.id.abbrev}
+```
+
+**使用场景：**
+- **灰度发布**：根据版本路由
+- **流量控制**：根据区域路由
+- **监控告警**：按团队分组
+
+### 4. 配置刷新策略
+
+- 对需要热更新的 Bean 使用 `@RefreshScope`
+- 监听 `RefreshScopeRefreshedEvent` 实现自定义刷新逻辑
+- 某些配置（如线程池大小）可能需要重启
+
+### 5. 健康检查配置
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,nacos-config,nacos-discovery
+  endpoint:
+    health:
+      show-details: always
+  health:
+    nacos:
+      enabled: true
+```
+
+访问健康检查：
+```bash
+curl http://localhost:8080/actuator/health
+```
+
+## 故障排查指南
+
+### 问题 0：Logback Appender 冲突错误
+
+**症状**：启动时出现以下错误：
+```
+|-ERROR in ch.qos.logback.core.rolling.RollingFileAppender[CONFIG_LOG_FILE] - 'File' option has the same value "C:\Users\xxx/logs/nacos/config.log" as that given for appender [CONFIG_LOG_FILE] defined earlier.
+|-ERROR in ch.qos.logback.core.rolling.RollingFileAppender[CONFIG_LOG_FILE] - Collisions detected with FileAppender/RollingAppender instances defined earlier. Aborting.
+```
+
+**原因**：Nacos 客户端会加载自己的 Logback 配置，创建文件日志 appender（CONFIG_LOG_FILE、NAMING_LOG_FILE、REMOTE_LOG_FILE），与应用的 Logback 配置冲突。
+
+**解决方案**：
+
+1. **在 Application 启动类中禁用 Nacos 文件日志**（推荐）：
+
+```java
+@SpringBootApplication
+public class Application {
+
+    public static void main(String[] args) {
+        // 禁用 Nacos 客户端的文件日志输出,解决 Logback appender 冲突问题
+        // 参考: https://github.com/alibaba/spring-cloud-alibaba/issues/4004
+        // 参考: https://github.com/alibaba/spring-cloud-alibaba/issues/3995
+        System.setProperty("nacos.logging.default.config.enabled", "false");
+        System.setProperty("nacos.logging.config", "");
+
+        SpringApplication.run(Application.class, args);
+    }
+}
+```
+
+2. **在 application.yml 中设置 Nacos 日志级别**（可选）：
+
+```yaml
+logging:
+  level:
+    com.alibaba.nacos: ERROR  # 减少 Nacos 日志输出
+```
+
+3. **不要引用不存在的 logback 配置文件**：
+
+```yaml
+# ❌ 错误：引用不存在的文件
+logging:
+  config: classpath:logback-spring.xml  # 如果文件不存在会导致问题
+
+# ✅ 正确：不指定或确保文件存在
+logging:
+  level:
+    com.alibaba.nacos: ERROR
+```
+
+**关键点**：
+- 必须在 `SpringApplication.run()` **之前**设置系统属性
+- 这会禁用 Nacos 的文件日志，Nacos 日志只会输出到控制台
+- 通过 `logging.level.com.alibaba.nacos` 控制 Nacos 日志级别
+
+**参考资料**：
+- [Spring Cloud Alibaba Issue #4004](https://github.com/alibaba/spring-cloud-alibaba/issues/4004)
+- [Spring Cloud Alibaba Issue #3995](https://github.com/alibaba/spring-cloud-alibaba/issues/3995)
+
+### 问题 1：服务未注册
+
+**症状**：服务未出现在 Nacos 控制台
+
+**诊断步骤：**
+1. 检查 Nacos 服务器地址：`telnet nacos-server 8848`
+2. 启用调试日志：
+   ```yaml
+   logging:
+     level:
+       com.alibaba.nacos: DEBUG
+       com.alibaba.cloud.nacos: DEBUG
+   ```
+3. 验证 `spring.cloud.nacos.discovery.register-enabled=true`
+4. 检查应用名称已设置：`spring.application.name`
+
+**常见原因：**
+- 服务器地址错误
+- 网络/防火墙阻止端口 8848
+- Nacos 服务器未运行
+- 认证失败（用户名/密码错误）
+
+### 问题 2：配置未加载
+
+**症状**：应用无法从 Nacos 加载配置
+
+**常见错误信息**：
+- `No spring.config.import property has been defined`
+- `dataId must be specified`
+- `illegal URI: http://${nacos.server-addr}/...`
+
+**诊断步骤：**
+1. ✅ **检查 spring.config.import 是否存在**
+   ```yaml
+   spring:
+     config:
+       import:
+         - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+   ```
+
+2. ✅ **检查 spring.config.import 位置是否正确**
+    - 必须在顶层 `spring:` 下
+    - 不能在 `spring.cloud.nacos:` 下
+
+3. ✅ **检查 spring.application.name 是否在主配置文件中定义**
+   ```yaml
+   # application.yml (主配置)
+   spring:
+     application:
+       name: my-service  # 必须在这里定义
+   ```
+
+4. ✅ **检查 dataId 格式是否正确**
+   ```yaml
+   # ✅ 正确
+   - optional:nacos:my-service.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+
+   # ❌ 错误
+   - "nacos:"  # 缺少 dataId
+   - "optional:nacos:${spring.application.name}.yaml"  # 缺少 group 参数
+   ```
+
+5. 验证 Data ID 在 Nacos 控制台中存在
+6. 检查命名空间 ID 正确
+7. 验证分组名称匹配
+8. 确认文件扩展名匹配：`file-extension: yaml`
+
+**解决方案示例：**
+
+```yaml
+# application.yml (主配置)
+spring:
+  application:
+    name: my-service
+
+# application-dev.yml (环境配置)
+spring:
+  config:
+    import:
+      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+
+  cloud:
+    nacos:
+      server-addr: 127.0.0.1:8848
+      namespace: dev
+      config:
+        enabled: true
+        file-extension: yaml
+        group: DEFAULT_GROUP
+```
+
+### 问题 3：配置未刷新
+
+**症状**：Nacos 中的配置更改未在应用中更新
+
+**诊断步骤：**
+1. 验证 `spring.cloud.nacos.config.refresh-enabled=true`
+2. 检查 Bean 上有 `@RefreshScope` 注解
+3. 在日志中查找刷新事件
+4. 先用 `@Value` 测试（比 `@ConfigurationProperties` 简单）
+
+**常见原因：**
+- 缺少 `@RefreshScope` 注解
+- 配置无法注入（静态字段、构造函数注入）
+- 某些配置不支持热更新（需要重启）
+
+### 问题 4：服务调用失败
+
+**症状**：`http://service-name/path` 返回错误
+
+**诊断步骤：**
+1. 验证目标服务已在 Nacos 中注册
+2. 检查 RestTemplate 上有 `@LoadBalanced` 注解
+3. 验证服务名称正确（区分大小写）
+4. 先测试直接 IP:端口调用
+5. 检查网络连接
+
+**常见原因：**
+- 缺少 `@LoadBalanced` 注解
+- 服务名拼写错误
+- 目标服务未注册
+- 网络/防火墙问题
+
+### 问题 5：认证失败
+
+**症状**："403 Forbidden" 或 "401 Unauthorized"
+
+**解决方案：**
+```yaml
+spring:
+  cloud:
+    nacos:
+      username: ${NACOS_USERNAME:nacos}
+      password: ${NACOS_PASSWORD:nacos}
+```
+
+在生产环境使用环境变量：
+```bash
+export NACOS_USERNAME=your-username
+export NACOS_PASSWORD=your-password
+```
+
+## 配置生成器
+
+生成 Nacos 配置时，遵循此模板结构：
+
+```yaml
+# 基础结构
+spring:
+  application:
+    name: <服务名称>
+
+  cloud:
+    nacos:
+      server-addr: <NACOS服务器>
+      namespace: <命名空间ID>
+      username: ${NACOS_USERNAME:nacos}
+      password: ${NACOS_PASSWORD:nacos}
+
+      config:
+        enabled: <true|false>
+        file-extension: <yaml|properties|json|xml>
+        group: <分组名称>
+        refresh-enabled: <true|false>
+
+      discovery:
+        enabled: <true|false>
+        register-enabled: <true|false>
+        ephemeral: <true|false>
+        group: <分组名称>
+        metadata:
+          version: <版本>
+          environment: <环境>
+
+# 健康检查
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,nacos-config,nacos-discovery
+  endpoint:
+    health:
+      show-details: always
+
+# 日志
+logging:
+  level:
+    com.alibaba.nacos: INFO
+    com.alibaba.cloud.nacos: INFO
+```
+
+## 验证清单
+
+审查 Nacos 配置时，检查：
+
+- [ ] 已设置 `spring.application.name`
+- [ ] `server-addr` 指向正确的 Nacos 服务器
+- [ ] 命名空间 ID 匹配环境（dev/test/prod）
+- [ ] 配置和发现的分组名称一致
+- [ ] 云原生部署使用 `ephemeral: true`
+- [ ] 生产环境的认证凭据使用环境变量
+- [ ] 需要动态配置时 `refresh-enabled: true`
+- [ ] 元数据包含有用标签（版本、环境）
+- [ ] 健康检查端点已暴露
+- [ ] 生产环境禁用调试日志
+
+## 版本兼容性
+
+- **Spring Boot**: 3.5.3
+- **Spring Cloud**: 2025.0.0
+- **Spring Cloud Alibaba**: 2023.0.3.2
+- **Java**: 21
+
+**重要**：Spring Boot 3.x 不再使用 `bootstrap.yml` - 所有配置都在 `application.yml` 中。
+
+## 参考文档
+
+- [Spring Cloud Alibaba Nacos](https://github.com/alibaba/spring-cloud-alibaba/wiki/Nacos-config)
+- [Nacos 官方文档](https://nacos.io/zh-cn/docs/what-is-nacos.html)
+- [Spring Cloud LoadBalancer](https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#spring-cloud-loadbalancer)
+
+## 常见场景
+
+### 场景 1：仅服务发现的简单服务
+
+```yaml
+spring:
+  application:
+    name: simple-service
+  cloud:
+    nacos:
+      server-addr: 127.0.0.1:8848
+      discovery:
+        enabled: true
+      config:
+        enabled: false  # 禁用配置中心
+```
+
+### 场景 2：仅配置中心（无服务注册）
+
+```yaml
+spring:
+  application:
+    name: config-consumer
+  cloud:
+    nacos:
+      server-addr: 127.0.0.1:8848
+      config:
+        enabled: true
+      discovery:
+        enabled: false  # 禁用服务发现
+```
+
+### 场景 3：多配置加载
+
+```yaml
+spring:
+  cloud:
+    nacos:
+      config:
+        extension-configs:
+          - data-id: database.yaml
+            group: COMMON_GROUP
+            refresh: true
+          - data-id: redis.yaml
+            group: COMMON_GROUP
+            refresh: true
+          - data-id: kafka.yaml
+            group: COMMON_GROUP
+            refresh: true
+```
+
+### 场景 4：使用元数据的灰度发布
+
+```yaml
+spring:
+  cloud:
+    nacos:
+      discovery:
+        metadata:
+          version: 2.0.0-beta
+          gray: true
+          canary-weight: 10
+```
+
+然后使用自定义路由规则将 10% 的流量导向此版本。
+
+## 快速命令参考
+
+```bash
+# 检查 Nacos 连接
+telnet nacos-server 8848
+
+# 查看健康状态
+curl http://localhost:8080/actuator/health
+
+# 查看 Nacos 服务发现信息
+curl http://localhost:8080/actuator/nacos-discovery
+
+# 查看 Nacos 配置信息
+curl http://localhost:8080/actuator/nacos-config
+
+# 启用调试日志（添加到 application.yml）
+logging.level.com.alibaba.nacos=DEBUG
+```
+
+---
+
+**何时使用此技能：**
+- 配置新的 Avatar Boot 服务使用 Nacos
+- 排查 Nacos 连接或配置问题
+- 设置多环境配置
+- 实现服务发现
+- 设置动态配置管理
+- 审查 Nacos 配置的最佳实践
+- 从其他服务发现解决方案迁移