服务端开发

Appearance

Nacos 配置笔记 ​

📋 版本信息 ​

  • Nacos Server: 3.0.1 (Docker)
  • Spring Boot: 3.2.11
  • Spring Cloud: 2023.0.3
  • Spring Cloud Alibaba: 2023.0.3.3
  • Kotlin: 1.9.25
  • Java: 17

🚀 配置过程 ​

1. Docker 环境配置 ​

yaml
# docker/docker-compose.yml
services:
  nacos:
    image: nacos/nacos-server:3.0.1
    container_name: nacos
    environment:
      - MODE=standalone
      - NACOS_AUTH_TOKEN=xxxxxxxx
      - NACOS_AUTH_IDENTITY_KEY=serverIdentity
      - NACOS_AUTH_IDENTITY_VALUE=xxxxx
      - NACOS_AUTH_ENABLE=true # 🔑 重要：开启认证
    ports:
      - "8080:8080"
      - "8848:8848"
      - "9848:9848"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8848/nacos/v1/ns/operator/switches"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

2. Gradle 依赖配置 ​

kotlin
// build.gradle.kts
extra["springCloudVersion"] = "2023.0.3"
extra["springCloudAlibabaVersion"] = "2023.0.3.3"

dependencies {
    implementation("com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-discovery")
    implementation("com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-config")
    // ... 其他依赖
}

3. 应用配置 ​

properties
# src/main/resources/application.properties

# 应用基本配置
server.port=9999
spring.application.name=gateway

# Nacos 配置中心配置
spring.config.import[0]=nacos:app1?group=DEFAULT_GROUP
spring.cloud.nacos.config.server-addr=localhost:8848
spring.cloud.nacos.config.namespace=rfcdam
spring.cloud.nacos.config.username=nacos
spring.cloud.nacos.config.password=nacos

# Nacos 服务发现配置
spring.cloud.nacos.discovery.server-addr=localhost:8848
spring.cloud.nacos.discovery.namespace=rfcdam
spring.cloud.nacos.discovery.username=nacos
spring.cloud.nacos.discovery.password=nacos
spring.cloud.nacos.discovery.register-enabled=true

4. 代码配置 ​

kotlin
// 主应用类
@SpringBootApplication
@EnableDiscoveryClient // 启用服务发现
@EnableConfigurationProperties // 启用配置属性绑定
class GatewayApplication

// Controller 示例
@RequestMapping("/demo")
@RestController
@RefreshScope  // 支持配置动态刷新
class DemoController {

    @Value("\${message.hello:Hello World}")
    private lateinit var helloMessage: String

    @Value("\${app.message:Default Message}")
    private lateinit var appMessage: String

    // ... 接口方法
}

⚠️ 问题记录与解决方案 ​

问题 1: 配置不存在导致启动失败 ​

错误信息:

Config data resource 'nacos:app1?group=DEFAULT_GROUP' does not exist

解决方案:

  1. 使用 optional: 前缀临时允许配置不存在
properties
spring.config.import[0]=optional:nacos:app1?group=DEFAULT_GROUP
  1. 创建配置后移除 optional: 前缀

问题 2: 认证失败 ​

错误信息:

Code: 401, Message: User not found! Please check user exist or password is right!

解决方案: 添加 Nacos 用户名密码配置：

properties
spring.cloud.nacos.config.username=nacos
spring.cloud.nacos.config.password=nacos
spring.cloud.nacos.discovery.username=nacos
spring.cloud.nacos.discovery.password=nacos

问题 3: 服务注册失败导致启动失败 ​

错误信息:

nacos registry, gateway register failed...

解决方案:

  1. 临时禁用服务注册：
properties
spring.cloud.nacos.discovery.register-enabled=false
  1. 确认 Nacos 正常运行后重新启用

问题 4: 健康检查失败 ​

错误信息:

Status: unhealthy

解决方案: 修正健康检查路径：

yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8848/nacos/v1/ns/operator/switches"]

🔧 调试方法 ​

1. 检查 Nacos 服务状态 ​

bash
# 查看容器状态
docker-compose ps

# 查看容器日志
docker logs nacos --tail 20

# 测试 API 访问
curl http://localhost:8848/nacos/v1/ns/operator/switches

2. 通过 API 管理配置 ​

bash
# 创建/更新配置
curl -X POST "http://localhost:8848/nacos/v1/cs/configs" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "dataId=app1&group=DEFAULT_GROUP&content=message.hello=helloNacos%0Aapp.message=HellNacos&tenant=rfcdam&username=nacos&password=nacos"

# 查询配置
curl "http://localhost:8848/nacos/v1/cs/configs?dataId=app1&group=DEFAULT_GROUP&tenant=rfcdam" -u nacos:nacos

3. 应用日志检查 ​

关注以下日志信息：

  • Nacos 客户端连接信息
  • 配置加载成功/失败信息
  • 服务注册成功/失败信息

💡 注意事项 ​

1. Nacos 3.0.1 特殊配置 ​

  • 默认开启认证，必须配置用户名密码
  • 健康检查路径与旧版本不同
  • 控制台访问路径可能有变化

2. Spring Cloud 2023.x 配置 ​

  • 使用 spring.config.import 替代 bootstrap.yml
  • 配置格式：nacos:{dataId}?group={group}
  • 支持 optional: 前缀允许配置不存在

3. 开发建议 ​

  • 先用 optional: 前缀开发，避免配置不存在时启动失败
  • 使用 @RefreshScope 支持配置动态刷新
  • 服务注册可以后开启，确保基础功能正常

4. 生产环境注意 ​

  • 修改默认用户名密码
  • 配置合适的 JVM 参数
  • 设置数据持久化
  • 配置负载均衡和高可用