安装与配置

本章节介绍 Nacos 的安装方式和基础配置，帮助你快速搭建 Nacos 环境。

环境要求

在安装 Nacos 之前，请确保你的系统满足以下要求：

要求	说明
操作系统	Linux/Unix/Mac/Windows，推荐 Linux
JDK	64 位 JDK 17+（Nacos 3.x 要求）或 JDK 8+（Nacos 2.x）
Maven	3.2.x+（从源码编译时需要）
内存	至少 2GB 可用内存，推荐 4GB+
CPU	至少 2 核，推荐 4 核+
磁盘	至少 60GB 可用空间

JDK 版本选择

Nacos 3.x：要求 JDK 17 及以上版本
Nacos 2.x：支持 JDK 8 及以上版本
推荐使用 LTS 版本：JDK 17 或 JDK 21

下载安装包

方式一：下载编译后的安装包

从 GitHub Releases 页面或官方网站下载最新稳定版本：

# 下载（以 3.1.1 版本为例，当前推荐稳定版）
wget https://github.com/alibaba/nacos/releases/download/3.1.1/nacos-server-3.1.1.tar.gz

# 解压
tar -xzf nacos-server-3.1.1.tar.gz

# 进入目录
cd nacos/bin

版本选择

生产环境：推荐使用 3.1.1 稳定版本（支持 AI 服务注册、A2A 功能、xDS 协议）
JDK 8 环境：可使用 2.5.2 版本
下载地址：Nacos 官方下载页 | GitHub Releases

方式二：使用 nacos-setup 一键部署（推荐）

Nacos 官方提供了一键部署工具 nacos-setup，自动处理下载、认证配置、端口检测和 Java 环境验证。

安装 nacos-setup：

# Linux/macOS
curl -fsSL https://nacos.io/nacos-installer.sh | sudo bash

# Windows (PowerShell)
powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -UseBasicParsing https://nacos.io/nacos-installer.ps1 | iex"

使用 nacos-setup：

# 一键部署最新单机版 Nacos
nacos-setup

# 部署指定版本
nacos-setup -v 3.2.0

# 一键部署集群
nacos-setup -c cluster

# 配置外部存储
nacos-setup --datasource-conf

方式二：从源码编译

# 克隆仓库
git clone https://github.com/alibaba/nacos.git

# 进入目录
cd nacos

# 编译
mvn -Prelease-nacos -Dmaven.test.skip=true clean install -U

# 进入编译产物目录
cd distribution/target/nacos-server-2.3.0/nacos/bin

启动模式

Nacos 支持两种启动模式：

单机模式：适用于开发和测试环境
集群模式：适用于生产环境

单机模式启动

单机模式使用内置数据库存储数据，无需额外配置：

# Linux/Unix/Mac
sh startup.sh -m standalone

# Windows
startup.cmd -m standalone

Nacos 3.0+ 认证配置

从 Nacos 3.0.0 开始，控制台认证默认开启。首次启动时，程序会提示输入以下 3 个认证配置：

`nacos.core.auth.plugin.nacos.token.secret.key` is missing, please set with Base64 string: 
请输入 Token 密钥（建议使用 32 位以上的 Base64 字符串）

`nacos.core.auth.server.identity.key` is missing, please set:
请输入服务端身份识别 Key

`nacos.core.auth.server.identity.value` is missing, please set:
请输入服务端身份识别 Value

生产环境务必使用自定义值，不要使用默认值或空值。

启动成功后，控制台会输出类似以下信息：

         ,--.
       ,--.'|
   ,--,:  : |                                           Nacos 3.2.0
,`--.'`|  ' :                       ,--.        Version: 3.2.0
|   :  :  | |          ,--.,--.    /   /   _   Server
:   |   \ | :  ,--.--. |   ||   :  /   /   / \   Mode: Standalone
|   : '  '; | /       \ '   '|  | /   /   /   \  Port: 8848
'   ' ;.    ;.--.  .-. |   ' '  ;   /   /    \  Web: http://localhost:8848/nacos

访问控制台

启动成功后，访问 http://localhost:8848/nacos 进入控制台。

默认用户名和密码都是 nacos。

Docker 安装

使用 Docker 可以更便捷地部署 Nacos：

快速启动（单机模式）

docker run -d \
  --name nacos-standalone \
  -e MODE=standalone \
  -p 8848:8848 \
  -p 9848:9848 \
  -p 9849:9849 \
  nacos/nacos-server:v3.2.0

Docker 镜像版本

生产环境推荐使用固定版本号（如 v3.2.0）
避免使用 latest 标签，以确保版本可控
Nacos 3.x 镜像需要 JDK 17+ 运行时环境

使用外部 MySQL

docker run -d \
  --name nacos-standalone \
  -e MODE=standalone \
  -e SPRING_DATASOURCE_PLATFORM=mysql \
  -e MYSQL_SERVICE_HOST=your-mysql-host \
  -e MYSQL_SERVICE_PORT=3306 \
  -e MYSQL_SERVICE_DB_NAME=nacos \
  -e MYSQL_SERVICE_USER=nacos \
  -e MYSQL_SERVICE_PASSWORD=nacos \
  -p 8848:8848 \
  -p 9848:9848 \
  -p 9849:9849 \
  nacos/nacos-server:v3.1.1

Docker Compose 部署

创建 docker-compose.yml 文件：

version: '3.8'

services:
  nacos:
    image: nacos/nacos-server:v2.3.0
    container_name: nacos-standalone
    environment:
      - MODE=standalone
      - SPRING_DATASOURCE_PLATFORM=mysql
      - MYSQL_SERVICE_HOST=mysql
      - MYSQL_SERVICE_PORT=3306
      - MYSQL_SERVICE_DB_NAME=nacos
      - MYSQL_SERVICE_USER=nacos
      - MYSQL_SERVICE_PASSWORD=nacos
    ports:
      - "8848:8848"
      - "9848:9848"
      - "9849:9849"
    depends_on:
      - mysql
    restart: always

  mysql:
    image: mysql:8.0
    container_name: nacos-mysql
    environment:
      - MYSQL_ROOT_PASSWORD=root
      - MYSQL_DATABASE=nacos
      - MYSQL_USER=nacos
      - MYSQL_PASSWORD=nacos
    volumes:
      - ./mysql-data:/var/lib/mysql
      - ./nacos-mysql.sql:/docker-entrypoint-initdb.d/nacos-mysql.sql
    restart: always

启动服务：

docker-compose up -d

配置外部数据库

生产环境建议使用外部数据库（MySQL）存储数据，确保数据持久化和高可用。

1. 创建数据库

CREATE DATABASE nacos CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;

2. 初始化数据库表

Nacos 提供了 SQL 脚本，位于 conf/mysql-schema.sql。执行该脚本创建所需的表：

mysql -u root -p nacos < conf/mysql-schema.sql

3. 修改配置文件

编辑 conf/application.properties 文件：

# 数据库配置
spring.datasource.platform=mysql

# 数据库连接信息
db.num=1
db.url.0=jdbc:mysql://127.0.0.1:3306/nacos?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&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 的主要配置文件是 conf/application.properties，以下是一些常用配置：

服务端口配置

# 主端口
server.port=8848

# 上下文路径
server.servlet.contextPath=/nacos

认证配置

Nacos 默认开启认证，需要配置以下参数：

# 开启认证（Nacos 3.0+ 默认开启）
nacos.core.auth.enabled=true

# 认证类型
nacos.core.auth.system.type=nacos

# Token 密钥（生产环境必须修改，使用 Base64 编码的字符串）
# 建议使用 32 位以上的随机字符串进行 Base64 编码
nacos.core.auth.plugin.nacos.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789

# 服务端身份识别（生产环境必须修改）
nacos.core.auth.server.identity.key=serverIdentity
nacos.core.auth.server.identity.value=security

# Token 有效期（秒），默认 18000（5 小时）
nacos.core.auth.plugin.nacos.token.expire.seconds=18000

安全警告

生产环境必须修改以下配置：

Token 密钥：默认密钥是公开的，仅适合临时测试。生产环境务必使用自定义的强密钥（建议 32 位以上随机字符串），且确保所有节点配置一致。密钥泄露会导致严重的认证绕过风险。
服务端身份识别：配置唯一的 Key-Value 对，防止请求伪造。所有集群节点必须配置相同的值。
默认账号密码：默认用户名密码都是 nacos，生产环境必须修改。

密钥生成示例：

# 使用 OpenSSL 生成随机密钥
openssl rand -base64 32

# 或使用 Java 生成
java -e 'import java.util.Base64; import java.util.UUID; print(Base64.getEncoder().encodeToString(UUID.randomUUID().toString().getBytes()))'

日志配置

# 日志级别
logging.level.com.alibaba.nacos=info

# 日志路径
nacos.logging.path=${user.home}/nacos/logs

JVM 参数配置

根据部署规模调整 JVM 参数。编辑 startup.sh（Linux/Mac）或 startup.cmd（Windows）：

小规模部署（服务数 < 100）：

JAVA_OPT="${JAVA_OPT} -Xms512m -Xmx512m -Xmn256m"

中等规模部署（服务数 100-500）：

JAVA_OPT="${JAVA_OPT} -Xms1g -Xmx1g -Xmn512m"

大规模部署（服务数 > 500）：

JAVA_OPT="${JAVA_OPT} -Xms2g -Xmx2g -Xmn1g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

JVM 调优建议

堆内存：建议设置为物理内存的 50%-80%
新生代：一般为堆内存的 1/3 到 1/2
GC 算法：大规模部署推荐使用 G1 GC
元空间：默认无限制，可添加 -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=256m

关闭服务

# Linux/Unix/Mac
sh shutdown.sh

# Windows
shutdown.cmd

Spring Cloud 集成

添加依赖

在 Spring Cloud 项目中集成 Nacos，首先添加依赖：

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

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

版本兼容性

Spring Cloud Alibaba	Spring Cloud	Spring Boot	Nacos 版本
2023.0.1.0	2023.0.x	3.2.x	2.x / 3.x
2022.0.0.0	2022.0.0	3.0.x	2.x / 3.x
2021.0.5.0	2021.0.x	2.6.x / 2.7.x	2.x
2.2.10-RC1	Hoxton.SR12	2.3.x / 2.4.x	1.x / 2.x

版本选择建议

新项目：推荐使用 Spring Boot 3.x + Nacos 3.x
JDK 8 环境：使用 Spring Boot 2.7.x + Nacos 2.3.x
升级路径：从 Nacos 1.x 升级到 2.x，再升级到 3.x

配置文件

在 bootstrap.yml 中配置 Nacos 连接信息：

spring:
  application:
    name: my-service
  cloud:
    nacos:
      # 服务发现配置
      discovery:
        server-addr: 127.0.0.1:8848
        namespace: dev
        group: DEFAULT_GROUP
      # 配置中心配置
      config:
        server-addr: 127.0.0.1:8848
        namespace: dev
        group: DEFAULT_GROUP
        file-extension: yaml
        # 共享配置
        shared-configs:
          - data-id: common.yaml
            group: DEFAULT_GROUP
            refresh: true

启用服务发现

在启动类上添加 @EnableDiscoveryClient 注解：

@SpringBootApplication
@EnableDiscoveryClient
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

验证安装

检查服务状态

# 检查服务是否启动
curl http://localhost:8848/nacos/v1/ns/operator/metrics

注册测试服务

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

查询服务列表

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

发布配置

# 发布配置
curl -X POST "http://localhost:8848/nacos/v1/cs/configs?dataId=test.properties&group=DEFAULT_GROUP&content=test.value=hello"

获取配置

# 获取配置
curl "http://localhost:8848/nacos/v1/cs/configs?dataId=test.properties&group=DEFAULT_GROUP"

常见问题

1. 端口被占用

如果 8848 端口被占用，可以修改 application.properties 中的端口配置：

server.port=8849

注意：修改主端口后，gRPC 端口会自动调整（主端口 + 1000 和 + 1001）。

2. 内存不足

如果启动时内存不足，可以修改启动脚本中的 JVM 参数：

# 修改 startup.sh 中的 JVM 参数
JAVA_OPT="${JAVA_OPT} -Xms512m -Xmx512m -Xmn256m"

3. 连接 MySQL 失败

检查以下几点：

MySQL 服务是否启动
数据库是否已创建
用户名密码是否正确
防火墙是否开放端口

4. 控制台无法访问

检查以下几点：

Nacos 服务是否正常启动
防火墙是否开放端口
浏览器是否使用正确的地址

下一步

服务注册与发现 - 学习如何使用 Nacos 进行服务注册与发现
配置管理基础 - 学习 Nacos 配置管理的核心功能

环境要求​

下载安装包​

方式一：下载编译后的安装包​

方式二：使用 nacos-setup 一键部署（推荐）​

方式二：从源码编译​

启动模式​

单机模式启动​

访问控制台​

Docker 安装​

快速启动（单机模式）​

使用外部 MySQL​

Docker Compose 部署​

配置外部数据库​

1. 创建数据库​

2. 初始化数据库表​

3. 修改配置文件​

核心配置说明​

服务端口配置​

认证配置​

日志配置​

JVM 参数配置​

关闭服务​

Spring Cloud 集成​

添加依赖​

版本兼容性​

配置文件​

启用服务发现​

验证安装​

检查服务状态​

注册测试服务​

查询服务列表​

发布配置​

获取配置​

常见问题​

1. 端口被占用​

2. 内存不足​

3. 连接 MySQL 失败​

4. 控制台无法访问​

下一步​