Nacos：超详细部署与使用教程

Nacos（Dynamic Naming and Configuration Service）是一个更易于构建云原生应用的动态服务发现、配置管理和服务管理平台。它是阿里巴巴开源的一站式微服务基础设施，也是 Spring Cloud Alibaba 生态的核心组件。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

Nacos 是一个用于动态服务发现、配置管理和服务管理的平台，帮助开发者轻松构建云原生应用与微服务体系。它脱胎于阿里巴巴内部经过十年生产验证的配置/命名系统（ConfigServer + Diamond），支持大规模（数百万服务）集群场景，并具备企业级 SLA。Nacos 支持 Dubbo、gRPC、Spring Cloud RESTful 服务以及 Kubernetes 服务等几乎所有主流服务类型，是业界常用的「注册中心 + 配置中心」一体化组件。

1.2 核心功能

• 服务发现与服务健康检查：支持 DNS 与 RPC 两种服务发现方式；服务端主动探测客户端实例健康状态，健康实例才能被调用方获取。
• 动态配置管理：配置以 DataId 维度管理，支持配置热更新（发布即生效，无需重启应用）、灰度发布、历史版本回滚、监听机制。
• 动态 DNS 服务：支持基于权重的路由、中间层负载均衡、更灵活的路由策略与流量管理。
• 服务及其元数据管理：管理数据中心的所有服务与元数据，包括服务的健康、权重、路由等属性。
• 命名空间与多环境隔离：通过 Namespace / Group 隔离不同环境、不同租户的配置与服务。
• 权限控制：自 2.2.1 起控制台默认开启登录鉴权；支持基于角色的访问控制（RBAC）。
• AI Registry 等新能力（3.x）：官方站点介绍 Nacos 3.x 面向 AI 场景扩展了对 Prompt、MCP、A2A 等 AI Registry 场景的支持（以官方文档为准）。

1.3 技术架构

下图是 Nacos 官方文档给出的总体架构：服务提供方（Provider）与服务消费方（Consumer）通过 Nacos Client / Sidecar 与 Nacos Server 交互；Server 侧对外提供 OpenAPI（HTTP/DNS/UDP/TLS），内部由 Config Service（配置服务）、Naming Service（命名服务）、Nacos Core（内核）与基于 JRaft / RDBMS 的一致性协议组成；同时提供 User Console / Admin Console / Customized Console 三种控制台。

下图是 Nacos 官方文档的逻辑架构图（含客户端 SDK、OpenAPI、内核与一致性协议、存储层的关系）：

二、环境要求

注意：2.x 起 Nacos 客户端通过 gRPC（端口 9848，服务端端口 +1000） 与服务端通信，防火墙/安全组必须放行 8848 与 9848，否则客户端会报 Client not connected, current status:STARTING 等错误。

三、部署方式

下面给出四种部署方式：二进制包单机部署（最快上手）→ 集群部署（生产）→ Docker 部署 → 源码编译部署。

3.1 方式一：二进制包单机部署（Standalone，最快上手）

步骤 1：下载并解压

从官方 Release 页下载最新稳定包：github.com/alibaba/nacos/releases，文件名形如 nacos-server-3.2.4.zip（以实际 release 为准）。以 Linux 为例：

cd /opt
wget https://github.com/alibaba/nacos/releases/download/3.2.4/nacos-server-3.2.4.zip
unzip nacos-server-3.2.4.zip
cd nacos/bin

若下载慢，可使用 GitHub 加速镜像（如 ghproxy）或官方提供的下载页（nacos.io/download/nacos-server）获取下载链接。

步骤 2：启动（单机模式）

Linux / Unix / macOS：

sh startup.sh -m standalone

Windows（CMD）：

startup.cmd -m standalone

-m standalone 指定单机模式，内置 Derby 数据库，无需额外配置即可启动。

步骤 3：验证启动成功

# 查看启动日志，出现 "Nacos started successfully" 即成功
tail -f /opt/nacos/logs/start.out

# 健康检查接口，返回 OK
curl -X GET 'http://127.0.0.1:8848/nacos/v1/console/health/readiness'

# 打开控制台（浏览器）
# http://127.0.0.1:8848/nacos

控制台默认账号密码：nacos / nacos（自 2.2.1 起控制台默认开启登录）。

3.2 方式二：集群部署（生产推荐，3 节点为例）

步骤 1：准备 MySQL 数据库

Nacos 集群需要 MySQL 存储。登录 MySQL 后执行官方提供的建表脚本（在解压包的 conf/mysql-schema.sql 中）：

CREATE DATABASE nacos_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
USE nacos_config;
SOURCE /opt/nacos/conf/mysql-schema.sql;

步骤 2：修改配置文件

编辑 /opt/nacos/conf/application.properties，开启 MySQL 数据源并填写连接信息：

# 开启 MySQL 数据源
spring.sql.init.platform=mysql
spring.datasource.platform=mysql
db.num=1
db.url.0=jdbc:mysql://192.168.1.10:3306/nacos_config?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai
db.user.0=root
db.password.0=你的数据库密码

步骤 3：配置集群节点

编辑 /opt/nacos/conf/cluster.conf（不存在则新建），每行一个节点 IP:端口：

192.168.1.11:8848
192.168.1.12:8848
192.168.1.13:8848

步骤 4：逐节点启动

每台机器上（不要加 -m standalone，默认即集群模式）：

sh startup.sh

生产环境建议通过 -Dnacos.member.list 或集群管理界面动态扩缩容，详见官方文档「集群部署说明」。 3 个及以上节点才具备容灾能力；集群节点间时间需同步（NTP）。

步骤 5：验证集群

# 任一节点健康检查
curl -X GET 'http://192.168.1.11:8848/nacos/v1/console/health/readiness'

# 查看集群节点列表（API 返回节点信息）
curl -X GET 'http://192.168.1.11:8848/nacos/v1/ns/operator/servers'

3.3 方式三：Docker 部署

官方镜像：Docker Hub nacos/nacos-server（hub.docker.com/r/nacos/nacos-server）。

单机模式：

docker run --name nacos-standalone -e MODE=standalone \
  -p 8848:8848 -p 9848:9848 \
  -d nacos/nacos-server:latest

使用 MySQL 的集群部署（Docker Compose 方式，官方仓库提供示例，以官方文档为准）：

docker run --name nacos-mysql \
  -e MODE=cluster \
  -e SPRING_DATASOURCE_PLATFORM=mysql \
  -e MYSQL_SERVICE_HOST=192.168.1.10 \
  -e MYSQL_SERVICE_DB_NAME=nacos_config \
  -e MYSQL_SERVICE_USER=root \
  -e MYSQL_SERVICE_PASSWORD=你的密码 \
  -p 8848:8848 -p 9848:9848 \
  -d nacos/nacos-server:latest

版本选择：镜像 tag 与 Release 版本对应（如 v3.2.4），生产环境请固定 tag 而非 latest。

3.4 方式四：源码编译部署

需要 JDK 8+ 与 Maven 3.2.5+：

git clone https://github.com/alibaba/nacos.git
cd nacos
mvn -Prelease-nacos -Dmaven.test.skip=true clean install -U
ls -al distribution/target/nacos-server-*.tar.gz   # 编译产物
# 解压产物后按 3.1/3.2 的方式启动

3.5 验证部署成功（通用）

1. 启动日志出现 Nacos started successfully in the xxx mode.；
2. curl http://127.0.0.1:8848/nacos/v1/console/health/readiness 返回 OK；
3. 浏览器打开 http://<服务器IP>:8848/nacos，用 nacos/nacos 登录后可看到「服务管理」「配置管理」等菜单。

3.6 关键配置说明

conf/application.properties 常用配置项：

startup.sh 常用参数：

四、使用方法

4.1 基础用法：控制台操作

登录控制台后：

• 服务管理 → 服务列表：查看已注册的服务、实例列表、健康状态、权重；可手动下线/上线实例，开启保护阈值。
• 配置管理 → 配置列表：新建配置（Data ID + Group + 配置格式 properties/yaml/json），发布后客户端监听立即感知。
• 命名空间：创建不同命名空间隔离环境（如 dev / test / prod）。
• 权限控制：用户管理、角色管理、给不同命名空间分配读写权限。

4.2 常用命令/API

Java 客户端接入（Maven 依赖）

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>3.2.4</version>
</dependency>

服务注册与发现（Naming Service）

import com.alibaba.nacos.api.NacosFactory;
import com.alibaba.nacos.api.naming.NamingService;
import com.alibaba.nacos.api.naming.pojo.Instance;

public class NacosNamingDemo {
    public static void main(String[] args) throws Exception {
        String serverAddr = "127.0.0.1:8848";
        NamingService naming = NacosFactory.createNamingService(serverAddr);

        // 注册一个实例
        Instance instance = new Instance();
        instance.setIp("127.0.0.1");
        instance.setPort(8080);
        instance.setServiceName("demo-service");
        instance.addMetadata("version", "1.0");
        naming.registerInstance("demo-service", instance);

        // 获取全部健康实例
        System.out.println(naming.selectInstances("demo-service", true));
    }
}

动态配置管理（Config Service）

import com.alibaba.nacos.api.NacosFactory;
import com.alibaba.nacos.api.config.ConfigService;
import com.alibaba.nacos.api.config.listener.Listener;

import java.util.concurrent.Executor;

public class NacosConfigDemo {
    public static void main(String[] args) throws Exception {
        String serverAddr = "127.0.0.1:8848";
        String dataId = "demo.properties";
        String group = "DEFAULT_GROUP";
        ConfigService config = NacosFactory.createConfigService(serverAddr);

        // 拉取配置
        String content = config.getConfig(dataId, group, 5000);
        System.out.println("配置内容: " + content);

        // 监听配置变更（热更新）
        config.addListener(dataId, group, new Listener() {
            @Override
            public void receiveConfigInfo(String configInfo) {
                System.out.println("配置已更新: " + configInfo);
            }
            @Override
            public Executor getExecutor() { return null; }
        });
    }
}

开放 HTTP API 示例

# 注册服务实例
curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?serviceName=demo-service&ip=127.0.0.1&port=8080'

# 获取服务实例列表
curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=demo-service'

# 发布配置（注意：3.x 后 API 前缀可能变化，以官方文档为准）
curl -X POST 'http://127.0.0.1:8848/nacos/v1/cs/configs' \
  -d 'dataId=demo.properties&group=DEFAULT_GROUP&content=key=value'

4.3 进阶功能

• Spring Cloud Alibaba 集成：添加 spring-cloud-starter-alibaba-nacos-discovery 与 spring-cloud-starter-alibaba-nacos-config 依赖，配置 spring.cloud.nacos.discovery.server-addr 即可实现服务发现与配置中心，详见官方生态文档 nacos.io/docs/latest/ecology/use-nacos-with-spring-cloud。
• Dubbo 集成：Nacos 可作为 Dubbo 3 注册中心，详见 nacos.io/docs/latest/ecology/use-nacos-with-dubbo。
• Kubernetes 部署：官方提供 Helm Chart 与 quick-start-kubernetes 文档（nacos.io/docs/latest/quickstart/quick-start-kubernetes），支持 nacos.io CRD 方式部署（3.x）。
• 配置灰度发布与回滚：控制台支持 Beta 发布（指定一部分客户端生效）、历史版本回滚。
• 多环境多租户：Namespace + Group 组合隔离，配合权限体系实现租户隔离。
• gRPC 长连接：2.x 起客户端与服务端采用 gRPC 长连接通信，减少心跳开销，支持连接级推送。

4.4 适用场景

• 微服务注册中心：替代/兼容 Eureka、Consul、Zookeeper 的注册发现职责；
• 配置中心：统一管理多环境配置、配置热更新、灰度发布；
• 大规模集群：支撑百万级服务、千万级实例（官方宣称）的注册与推送；
• 云原生基础设施：与 K8s、Istio 等集成，作为服务治理底座；
• AI 场景服务注册（3.x）：注册与管理 AI Agent / MCP 服务（以官方文档为准）。

五、常见问题排查（FAQ）

Q1：启动报错 java.io.IOException: java.lang.IllegalArgumentException: db.num is null - 原因：集群模式但未配置数据库。 - 解决：单机测试用 -m standalone；集群必须按 3.2 配置 MySQL 并执行建表脚本。

Q2：客户端报 Client not connected, current status:STARTING 或连接超时 - 原因：2.x 起使用 gRPC 端口 9848（服务端端口 +1000），防火墙/安全组未放行。 - 解决：放行 8848 与 9848 端口后重试；检查 server.port 与客户端 serverAddr 一致。

Q3：控制台登录提示用户名密码错误 - 原因：2.2.1+ 默认开启鉴权，或已修改密码。 - 解决：默认账号 nacos/nacos；若修改过密码请用新密码；可参考官方文档重置。

Q4：单机模式重启后数据“丢失”或残留 - 原因：单机模式使用内置 Derby 存储，数据文件在 data/ 目录。 - 解决：不要删除 nacos/data 目录；长期使用请迁移 MySQL；测试环境反复重置可删除 data 目录后重启。

Q5：内存不足（OOM）或启动慢 - 原因：默认 JVM 参数偏大。 - 解决：修改 bin/startup.sh 中 JAVA_OPT 的 -Xms/-Xmx（如 -Xms512m -Xmx512m）。

Q6：集群模式下节点互相报错、选主失败 - 原因：节点间网络不通、时间不同步或 cluster.conf 配置错误。 - 解决：确认 7848（JRaft）端口放行、节点间时钟用 NTP 同步、cluster.conf 每行格式为 IP:8848。

Q7：MySQL 连接报错 Public Key Retrieval is not allowed - 解决：JDBC URL 增加 allowPublicKeyRetrieval=true&useSSL=false。

Q8：修改配置后客户端未感知 - 解决：确认客户端使用同一 Group 与 Namespace；检查是否开启了 spring.cloud.nacos.config.refresh-enabled（Spring Cloud 场景）；客户端是否使用了正确的 dataId。

六、部署注意事项与最佳实践

1. 生产禁止单机 Derby：单机模式仅用于开发测试；生产至少 3 节点集群 + MySQL。
2. 必须修改默认密码与鉴权密钥：生产环境修改 nacos/nacos 默认密码，并设置 nacos.core.auth.plugin.nacos.token.secret.key（Base64 编码的 ≥32 字节随机串）。
3. 端口规划：放行 8848（HTTP）、9848/9849（gRPC 客户端/服务端）、7848（JRaft 集群通信，2.x）。
4. 时钟同步：集群节点配置 NTP，避免选主与心跳异常。
5. 数据备份：定期备份 MySQL 中 nacos_config 库与配置历史。
6. 版本兼容：客户端版本尽量与服务端保持同一大版本；升级 Nacos 前阅读官方升级文档（3.x 相对 2.x 有接口与存储变化，以官方文档为准）。
7. 监控告警：关注 /nacos/v1/ns/operator/metrics 指标（服务数、实例数、健康检查队列等），接入 Prometheus/Grafana。
8. 不要在公网裸奔：通过 Nacos 的鉴权 + 网络白名单/安全组控制访问。

七、参考资料

• GitHub 仓库：https://github.com/alibaba/nacos
• 官方文档首页：https://nacos.io/docs/latest/overview/
• 快速开始（Quick Start）：https://nacos.io/docs/latest/quickstart/quick-start/
• 集群部署说明：https://nacos.io/docs/latest/admin/cluster-mode-quick-start/
• 下载页：https://nacos.io/download/nacos-server
• Release 下载：https://github.com/alibaba/nacos/releases
• Docker 镜像：https://hub.docker.com/r/nacos/nacos-server
• 与 Spring Cloud 集成：https://nacos.io/docs/latest/ecology/use-nacos-with-spring-cloud/
• 与 Dubbo 集成：https://nacos.io/docs/latest/ecology/use-nacos-with-dubbo/
• Kubernetes 部署：https://nacos.io/docs/latest/quickstart/quick-start-kubernetes/
• 架构与原理电子书：https://nacos.io/docs/ebook/kbyo6n/