跳到主要内容

Nacos 速查表

本页面提供 Nacos 常用配置、命令和 API 的快速参考。

服务端配置​

核心配置项​

配置项默认值说明
server.port8848主端口
nacos.modestandalone启动模式：standalone/cluster
nacos.standalonetrue是否单机模式
spring.datasource.platform空数据库类型：mysql/empty
nacos.server.main.port8848主端口（2.x 新增）

服务发现配置​

# 服务发现相关配置
nacos.naming.service.expired-time=60000        # 服务过期时间（毫秒）
nacos.naming.clean.empty-service.interval=60000  # 清理空服务间隔
nacos.naming.clean.empty-service.expired-time=60000  # 空服务过期时间
nacos.naming.clean.expired-metadata.interval=5000    # 清理过期元数据间隔
nacos.naming.clean.expired-metadata.expired-time=60000  # 元数据过期时间

数据库配置​

# MySQL 配置
spring.datasource.platform=mysql
db.num=1
db.url.0=jdbc:mysql://localhost:3306/nacos?characterEncoding=utf8&connectTimeout=10000&socketTimeout=30000&autoReconnect=true&useSSL=false&serverTimezone=Asia/Shanghai
db.user.0=nacos
db.password.0=nacos

# 连接池配置
db.pool.config.connectionTimeout=30000
db.pool.config.validationTimeout=10000
db.pool.config.maximumPoolSize=20
db.pool.config.minimumIdle=2

认证配置​

# 开启认证
nacos.core.auth.enabled=true
nacos.core.auth.system.type=nacos

# Token 密钥（生产环境必须修改）
nacos.core.auth.plugin.nacos.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789

# 服务端身份识别
nacos.core.auth.server.identity.key=serverIdentity
nacos.core.auth.server.identity.value=security

# 默认 token（仅测试用）
nacos.core.auth.plugin.nacos.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789

集群配置​

# cluster.conf 文件内容
# 格式：ip:port
192.168.1.101:8848
192.168.1.102:8848
192.168.1.103:8848

客户端配置​

Spring Cloud 服务发现完整配置​

spring:
  application:
    name: user-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        namespace: dev                    # 命名空间 ID（不是名称）
        group: DEFAULT_GROUP              # 分组名
        service: ${spring.application.name}  # 服务名（默认为应用名）
        weight: 1                         # 权重（0.01-10000）
        ephemeral: true                   # 是否临时实例
        cluster-name: DEFAULT             # 集群名
        # 心跳配置
        heart-beat-interval: 5000         # 心跳间隔（毫秒）
        heart-beat-timeout: 15000         # 心跳超时（毫秒）
        ip-delete-timeout: 30000          # IP 删除超时（毫秒）
        # 网络配置
        ip: ""                            # 指定注册的 IP（空则自动获取）
        port: -1                          # 指定注册的端口（-1 则自动获取）
        # 元数据
        metadata:
          version: 1.0.0
          region: cn-east
          preserved.register.source: SPRING_CLOUD
        # 安全配置
        username: nacos
        password: nacos
        # 订阅配置
        watch:
          enabled: true                   # 是否开启服务订阅
        # 快速失败
        fail-fast: true                   # 启动时是否检查服务注册成功

Spring Cloud 配置中心完整配置​

spring:
  application:
    name: user-service
  profiles:
    active: dev
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        namespace: dev                    # 命名空间 ID
        group: DEFAULT_GROUP              # 分组名
        file-extension: yaml              # 配置文件扩展名
        prefix: ${spring.application.name}  # 配置前缀（默认应用名）
        refresh-enabled: true             # 是否自动刷新
        # 共享配置（多个服务共享的配置）
        shared-configs:
          - data-id: common.yaml
            group: DEFAULT_GROUP
            refresh: true
          - data-id: database.yaml
            group: SHARED_GROUP
            refresh: true
        # 扩展配置（优先级高于共享配置）
        extension-configs:
          - data-id: redis.yaml
            group: DATABASE_GROUP
            refresh: true
          - data-id: kafka.yaml
            group: MQ_GROUP
            refresh: true
        # 安全配置
        username: nacos
        password: nacos
        # 快速失败
        fail-fast: true                   # 启动时是否检查配置加载成功
        # 超时配置
        timeout: 3000                     # 获取配置超时时间（毫秒）

Dubbo 注册中心配置​

dubbo:
  application:
    name: user-service-provider
  registry:
    address: nacos://127.0.0.1:8848
    username: nacos
    password: nacos
    group: dubbo                          # 分组
    parameters:
      namespace: 5cbb70a5-xxx-xxx-xxx     # 命名空间 ID
      register-consumer-url: true        # 是否注册消费者
  protocol:
    name: dubbo
    port: 20880

完整配置示例​

spring:
  application:
    name: user-service
  profiles:
    active: dev
  cloud:
    nacos:
      # 服务发现配置
      discovery:
        server-addr: ${NACOS_SERVER:127.0.0.1:8848}
        namespace: ${NACOS_NAMESPACE:dev}
        group: DEFAULT_GROUP
        weight: 1
        ephemeral: true
        metadata:
          version: 1.0.0
          preserved.register.source: SPRING_CLOUD
      # 配置中心配置
      config:
        server-addr: ${NACOS_SERVER:127.0.0.1:8848}
        namespace: ${NACOS_NAMESPACE:dev}
        group: DEFAULT_GROUP
        file-extension: yaml
        refresh-enabled: true
        shared-configs:
          - data-id: common.yaml
            group: DEFAULT_GROUP
            refresh: true

常用命令​

服务端命令​

# 单机模式启动
sh startup.sh -m standalone

# 集群模式启动
sh startup.sh

# 关闭服务
sh shutdown.sh

# 查看日志
tail -f logs/start.out
tail -f logs/nacos.log

Docker 命令​

# 单机模式
docker run -d \
  --name nacos \
  -e MODE=standalone \
  -p 8848:8848 \
  nacos/nacos-server:v3.1.1

# 集群模式
docker run -d \
  --name nacos \
  -e MODE=cluster \
  -e NACOS_SERVERS="nacos1:8848 nacos2:8848 nacos3:8848" \
  -e SPRING_DATASOURCE_PLATFORM=mysql \
  -e MYSQL_SERVICE_HOST=mysql \
  -e MYSQL_SERVICE_PORT=3306 \
  -e MYSQL_SERVICE_DB_NAME=nacos \
  -e MYSQL_SERVICE_USER=nacos \
  -e MYSQL_SERVICE_PASSWORD=nacos \
  -p 8848:8848 \
  nacos/nacos-server:v2.3.0

Open API​

服务注册与发现​

# 注册服务实例
curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance' \
  -d 'serviceName=user-service' \
  -d 'ip=192.168.1.100' \
  -d 'port=8080' \
  -d 'weight=1.0' \
  -d 'ephemeral=true' \
  -d 'metadata={"version":"1.0.0"}'

# 注销服务实例
curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/ns/instance' \
  -d 'serviceName=user-service' \
  -d 'ip=192.168.1.100' \
  -d 'port=8080'

# 查询服务实例列表
curl 'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=user-service'

# 查询服务详情
curl 'http://127.0.0.1:8848/nacos/v1/ns/instance?serviceName=user-service&ip=192.168.1.100&port=8080'

# 发送心跳
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/instance/beat' \
  -d 'serviceName=user-service' \
  -d 'ip=192.168.1.100' \
  -d 'port=8080' \
  -d 'beat={"cluster":"DEFAULT","ip":"192.168.1.100","port":8080,"serviceName":"user-service"}'

# 查询服务列表
curl 'http://127.0.0.1:8848/nacos/v1/ns/service/list?pageNo=1&pageSize=10'

# 创建服务（持久服务）
curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/service' \
  -d 'serviceName=mysql-service' \
  -d 'ephemeral=false' \
  -d 'protectThreshold=0.5'

# 更新服务
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/service' \
  -d 'serviceName=user-service' \
  -d 'protectThreshold=0.3' \
  -d 'metadata={"version":"2.0.0"}'

配置管理​

# 发布配置
curl -X POST 'http://127.0.0.1:8848/nacos/v1/cs/configs' \
  -d 'dataId=user-service.yaml' \
  -d 'group=DEFAULT_GROUP' \
  -d 'content=spring:\n  datasource:\n    url: jdbc:mysql://localhost:3306/user_db'

# 获取配置
curl 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=user-service.yaml&group=DEFAULT_GROUP'

# 删除配置
curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=user-service.yaml&group=DEFAULT_GROUP'

# 监听配置（长轮询）
curl -X POST 'http://127.0.0.1:8848/nacos/v1/cs/configs/listener' \
  -d 'Listening-Configs=user-service.yaml\u0002DEFAULT_GROUP\u0002dev\u0002'

# 查询配置历史
curl 'http://127.0.0.1:8848/nacos/v1/cs/history?dataId=user-service.yaml&group=DEFAULT_GROUP&pageNo=1&pageSize=10'

# 导出配置
curl 'http://127.0.0.1:8848/nacos/v1/cs/configs?export=true&dataId=&group=&tenant=dev' -o config.zip

# 导入配置
curl -X POST 'http://127.0.0.1:8848/nacos/v1/cs/configs?import=true&tenant=dev' \
  -F '[email protected]'

# 发布配置（带标签，用于灰度）
curl -X POST 'http://127.0.0.1:8848/nacos/v1/cs/configs' \
  -d 'dataId=user-service.yaml' \
  -d 'group=DEFAULT_GROUP' \
  -d 'content=...' \
  -d 'config_tags=gray,canary'

认证相关​

# 登录获取 Token
curl -X POST 'http://127.0.0.1:8848/nacos/v1/auth/login' \
  -d 'username=nacos' \
  -d 'password=nacos'
# 返回：{"accessToken": "xxx.yyy.zzz", "tokenTtl": 18000}

# 使用 Token 访问 API
curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/service/list' \
  -H 'Authorization: Bearer xxx.yyy.zzz'

# 创建用户
curl -X POST 'http://127.0.0.1:8848/nacos/v1/auth/users' \
  -H 'Authorization: Bearer xxx.yyy.zzz' \
  -d 'username=newuser' \
  -d 'password=password'

# 修改密码
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/auth/users' \
  -H 'Authorization: Bearer xxx.yyy.zzz' \
  -d 'username=nacos' \
  -d 'newPassword=new_password'

命名空间管理​

# 创建命名空间
curl -X POST 'http://127.0.0.1:8848/nacos/v1/console/namespaces' \
  -d 'customNamespaceId=dev' \
  -d 'namespaceName=开发环境' \
  -d 'namespaceDesc=开发环境命名空间'

# 查询命名空间列表
curl 'http://127.0.0.1:8848/nacos/v1/console/namespaces'

# 删除命名空间
curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/console/namespaces?namespaceId=dev'

集群管理​

# 查询集群状态
curl 'http://127.0.0.1:8848/nacos/v1/ns/operator/metrics'

# 查询集群节点
curl 'http://127.0.0.1:8848/nacos/v1/core/cluster/nodes'

# 查询 Raft 状态
curl 'http://127.0.0.1:8848/nacos/v1/core/cluster/raft/leader'

Maven 依赖​

Spring Cloud Alibaba BOM​

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>2022.0.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

服务发现依赖​

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

配置管理依赖​

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

完整依赖​

<dependencies>
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Nacos 服务发现 -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    </dependency>

    <!-- Nacos 配置管理 -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    </dependency>

    <!-- Spring Cloud LoadBalancer -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-loadbalancer</artifactId>
    </dependency>

    <!-- OpenFeign（可选） -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-openfeign</artifactId>
    </dependency>
</dependencies>

版本兼容性​

Spring Cloud Alibaba 版本对应关系​

Spring Cloud AlibabaSpring CloudSpring Boot
2022.0.0.02022.0.03.0.x
2021.0.5.02021.0.x2.6.x / 2.7.x
2021.0.4.02021.0.x2.6.x
2021.0.1.02021.0.x2.6.x
2.2.10-RC1Hoxton.SR122.3.x / 2.4.x

Nacos 版本推荐​

Nacos 版本说明JDK 要求
3.1.1当前推荐生产版本，支持 AI 服务注册、A2A 功能、xDS 协议、分布式锁JDK 17+
3.x最新系列，MCP Registry、A2A Registry、Skills Registry 等新特性JDK 17+
2.5.2稳定的 2.x 版本，支持 gRPC，兼容 JDK 8JDK 8+
2.3.x稳定的 2.x 系列JDK 8+
1.x旧版本，仅 HTTP，不建议新项目使用JDK 8+
版本选择建议
  • 新项目：推荐使用 3.1.1 版本，支持 AI 服务注册、A2A 功能等新特性
  • JDK 8 环境：使用 2.5.2 稳定版本
  • AI 服务场景：必须使用 3.x 版本
  • 服务网格集成：3.x 支持原生 xDS 协议
  • 旧项目升级：建议从 1.x 升级到 2.x，再升级到 3.x
  • 版本兼容：升级前请查看官方升级指南

端口说明​

端口用途计算方式
8848主端口默认
9848gRPC 客户端端口8848 + 1000
9849gRPC 服务端端口8848 + 1001
7848Raft 协议端口8848 - 100

常见错误码​

Nacos 2.x API 错误码​

错误码说明解决方案
0成功-
10000参数缺失检查必填参数是否传入
10001访问被拒绝检查用户权限或 Token 是否有效
10002数据访问错误检查数据库连接和状态
20001tenant 参数错误检查命名空间 ID 是否正确
20004资源未找到检查 Data ID、Group、Namespace 是否正确
20005资源冲突可能是并发操作导致，重试即可
21003实例未找到检查服务名、IP、端口是否正确
21008服务不存在检查服务名是否正确或先创建服务
22001命名空间非法检查命名空间 ID 格式
22002命名空间不存在检查命名空间是否已创建
30000服务端内部错误查看服务端日志排查

常见问题排查​

服务注册失败​

排查步骤：

  1. 检查 Nacos Server 是否正常运行
curl http://127.0.0.1:8848/nacos/v1/ns/operator/metrics
  1. 检查网络连通性
# 检查主端口
telnet 127.0.0.1 8848
# 检查 gRPC 端口（2.x 必需）
telnet 127.0.0.1 9848
  1. 检查认证信息
# 验证用户名密码
curl -X POST 'http://127.0.0.1:8848/nacos/v1/auth/login' \
  -d 'username=nacos' -d 'password=nacos'

配置加载失败​

排查步骤：

  1. 检查配置是否存在
curl 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=xxx&group=xxx'
  1. 检查命名空间 ID（注意是 ID 不是名称）
  2. 检查 Data ID 和 Group 是否正确
  3. 检查文件扩展名配置是否与实际一致

服务发现不到实例​

排查步骤：

  1. 确认服务已注册
curl 'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=xxx'
  1. 检查命名空间和分组是否一致
  2. 检查服务实例是否健康
  3. 检查是否设置了 healthyOnly=true

默认账号密码​

用户名密码说明
nacosnacos默认管理员账号
安全警告

生产环境务必修改默认账号密码！

配置文件路径​

文件路径说明
主配置文件conf/application.propertiesNacos 服务端配置
集群配置conf/cluster.conf集群节点列表
日志文件logs/nacos.log运行日志
启动日志logs/start.out启动日志
访问日志logs/access.logHTTP 访问日志

参考链接​