Nacos 安装指南

Note

版本: Nacos 3.0.3 | 平台: Linux（CentOS Stream 9） | JDK: 17+（64-bit）

端口规划: 8080（控制台）/ 8848（主端口 API）/ 9848（gRPC 客户端）/ 7848（Raft 集群通信）/ 9080（AI Registry）

部署模式: 单机模式（开发测试）/ 集群模式（生产环境，≥3 节点）

一、概述与架构

Nacos（Dynamic Naming and Configuration Service）是阿里巴巴开源的服务发现、配置管理和服务治理平台。Nacos 3.0 在 2.x 基础上进行了重大升级，新增 AI/MCP Registry 能力，支持 Spring Cloud、Dubbo、gRPC、Kubernetes Service 等主流框架的无缝集成。

1.1 部署模式对比

特性	单机模式（Standalone）	集群模式（Cluster）
适用场景	开发、测试、功能验证	生产环境
节点数	1	≥3（奇数推荐）
数据存储	内嵌 Derby / 外置 MySQL	外置 MySQL（必须）
一致性协议	无需	Distro（临时实例）+ Raft/JRaft（持久实例/配置）
高可用	❌	✅

1.2 端口规划

端口	用途	协议	说明
8080	控制台 Web UI	HTTP	Nacos 3.0 控制台独立端口
8848	主端口（API）	HTTP	服务注册/发现、配置管理 REST API
9848	gRPC 客户端通信	gRPC	主端口 + 1000 偏移
7848	Raft 集群通信	gRPC	主端口 - 1000 偏移，集群模式必开
9080	AI Registry（MCP/Skill）	HTTP	可选，需显式启用

二、环境准备（CentOS Stream 9）

2.1 硬件要求

环境	CPU	内存	磁盘
开发/测试	≥2 核	≥4 GB	≥60 GB
生产（单节点）	≥4 核	≥8 GB	≥100 GB SSD

2.2 安装 JDK 17

Nacos 3.0 强制要求 JDK 17+ 64-bit。

Bash

# 方式一：使用系统包管理器
sudo dnf install -y java-17-openjdk java-17-openjdk-devel

# 方式二：手动安装 Oracle JDK / Adoptium
# 下载 JDK 17 tar.gz 后解压至 /usr/local/jdk-17
export JAVA_HOME=/usr/local/jdk-17
export PATH=$JAVA_HOME/bin:$PATH

# 验证
java -version
# openjdk version "17.x.x" 或 java version "17.x.x"

2.3 防火墙配置

Bash

# 开放 Nacos 所需端口
sudo firewall-cmd --permanent --add-port=8080/tcp   # 控制台
sudo firewall-cmd --permanent --add-port=8848/tcp   # API
sudo firewall-cmd --permanent --add-port=9848/tcp   # gRPC
sudo firewall-cmd --permanent --add-port=7848/tcp   # Raft（集群）
sudo firewall-cmd --reload

三、单机模式安装（开发测试）

3.1 下载与解压

Bash

# 下载 Nacos 3.0.3 发行包(如果下载缓慢，直接本地下载再上传到服务器即可)
cd /opt
wget https://github.com/alibaba/nacos/releases/download/3.0.3/nacos-server-3.0.3.tar.gz
tar -xzf nacos-server-3.0.3.tar.gz
cd nacos

3.2 配置鉴权（3.0 强制要求）

Warning

Nacos 3.0 首次启动必须配置以下三项鉴权参数，否则启动失败。切勿使用官方文档中的默认示例值用于任何非临时测试环境。

编辑 conf/application.properties：

Text

# ============ 鉴权配置（必填） ============
nacos.core.auth.system.type=nacos
nacos.core.auth.enabled=true

# JWT Token 密钥，Base64 编码，原始字符串长度 ≥ 32 字符
# 生成方式：echo -n "YourCustomSecretKey0123456789ABCDEF" | base64
nacos.core.auth.plugin.nacos.token.secret.key=WW91ckN1c3RvbVNlY3JldEtleTAxMjM0NTY3ODlBQkNERUY=

# 集群节点间内部 API 身份标识（Key-Value 对，所有节点一致）
nacos.core.auth.server.identity.key=nacosServerIdentity
nacos.core.auth.server.identity.value=YourStrongIdentityValue2025

3.3 启动与验证

Bash

# 以单机模式启动（默认使用内嵌 Derby 数据库）
sh bin/startup.sh -m standalone

# 查看启动日志
tail -f logs/startup.log
# 成功标志：Nacos started successfully in standalone mode. use embedded storage

3.4 访问控制台

控制台地址：http://<服务器IP>:8080/index.html
首次登录会要求初始化管理员用户 nacos 的密码
API 端点：http://<服务器IP>:8848

3.5 验证服务

Bash

# 登录获取 accessToken
curl -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/login' \
  -d 'username=nacos' -d 'password=<你设置的密码>'

# 服务注册
curl -X POST 'http://127.0.0.1:8848/nacos/v3/client/ns/instance?serviceName=test.service&ip=127.0.0.1&port=8080'

# 服务发现
curl -X GET 'http://127.0.0.1:8848/nacos/v3/client/ns/instance/list?serviceName=test.service'

# 发布配置
curl -X POST 'http://127.0.0.1:8848/nacos/v3/admin/cs/config?dataId=test.config&groupName=DEFAULT_GROUP&content=HelloNacos' \
  -H "accessToken:<你的token>"

# 获取配置
curl -X GET 'http://127.0.0.1:8848/nacos/v3/client/cs/config?dataId=test.config&groupName=DEFAULT_GROUP'

3.6 关闭服务

Bash

sh bin/shutdown.sh

四、集群模式部署（生产环境）

Warning

生产环境必须使用集群模式（≥3 节点）+ 外置 MySQL 数据库，确保高可用和数据持久化。推荐架构：Domain + SLB + Nacos Cluster。

4.1 架构拓扑

Text

客户端 → 域名/SLB(内网) → Nacos Node 1 (192.168.1.11:8848)
                         → Nacos Node 2 (192.168.1.12:8848)
                         → Nacos Node 3 (192.168.1.13:8848)
                                    ↓
                              MySQL 主从/高可用

推荐访问方式（优先级从高到低）：

http://nacos.internal.com:8848/nacos — 域名 + SLB（推荐）
http://SLB_IP:8848/nacos — SLB 直连
http://ip:8848/nacos — 直连 IP（不推荐）

4.2 初始化 MySQL 数据库

Bash

# 在 MySQL 8 中创建 Nacos 数据库
mysql -u root -p

Sql

CREATE DATABASE nacos_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'nacos'@'%' IDENTIFIED BY 'YourStrongPassword';
GRANT ALL PRIVILEGES ON nacos_config.* TO 'nacos'@'%';
FLUSH PRIVILEGES;
USE nacos_config;

-- 导入 Nacos 表结构（文件在 Nacos 解压目录中）
SOURCE /opt/nacos/conf/mysql-schema.sql;

4.3 配置 application.properties

在每个节点的 conf/application.properties 中配置：

Text

# ============ 数据源配置 ============
spring.sql.init.platform=mysql
db.num=1
db.url.0=jdbc:mysql://mysql-host:3306/nacos_config?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai
db.user=nacos
db.password=YourStrongPassword

# 连接池优化（HikariCP）
db.pool.config.connectionTimeout=30000
db.pool.config.maximumPoolSize=20
db.pool.config.minimumIdle=5

# ============ 鉴权配置（所有节点必须一致） ============
nacos.core.auth.system.type=nacos
nacos.core.auth.enabled=true
nacos.core.auth.admin.enabled=true
nacos.core.auth.console.enabled=true
nacos.core.auth.plugin.nacos.token.secret.key=<Base64编码密钥，所有节点相同>
nacos.core.auth.server.identity.key=nacosIdentityKey
nacos.core.auth.server.identity.value=nacosIdentityValue2025
nacos.core.auth.plugin.nacos.token.expire.seconds=18000

4.4 配置 cluster.conf

在每个节点的 conf/cluster.conf 中填写所有节点的 ip:port：

Text

# ip:port
192.168.1.11:8848
192.168.1.12:8848
192.168.1.13:8848

4.5 启动集群

Bash

# 在每个节点上执行（默认集群模式）
sh bin/startup.sh

# 查看日志确认启动
tail -f logs/start.out
# 成功标志：Nacos started successfully in cluster mode. use external storage

五、Docker 部署

5.1 单机模式（快速启动）

Bash

docker run -d \
  --name nacos-standalone \
  -e MODE=standalone \
  -e NACOS_AUTH_TOKEN=WW91ckN1c3RvbVNlY3JldEtleTAxMjM0NTY3ODlBQkNERUY= \
  -e NACOS_AUTH_IDENTITY_KEY=nacosServerIdentity \
  -e NACOS_AUTH_IDENTITY_VALUE=YourStrongIdentityValue2025 \
  -p 8080:8080 \
  -p 8848:8848 \
  -p 9848:9848 \
  nacos/nacos-server:v3.0.3

5.2 Docker Compose + MySQL（推荐）

YAML

# docker-compose-nacos.yml
version: '3.8'
services:
  nacos-mysql:
    image: mysql:8.0
    container_name: nacos-mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: rootPassword123
      MYSQL_DATABASE: nacos_config
      MYSQL_USER: nacos
      MYSQL_PASSWORD: nacosPassword123
    volumes:
      - ./nacos/conf/mysql-schema.sql:/docker-entrypoint-initdb.d/nacos-schema.sql
      - nacos-mysql-data:/var/lib/mysql
    ports:
      - "3306:3306"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  nacos:
    image: nacos/nacos-server:v3.0.3
    container_name: nacos-server
    restart: always
    depends_on:
      nacos-mysql:
        condition: service_healthy
    environment:
      MODE: standalone
      SPRING_DATASOURCE_PLATFORM: mysql
      MYSQL_SERVICE_HOST: nacos-mysql
      MYSQL_SERVICE_PORT: 3306
      MYSQL_SERVICE_DB_NAME: nacos_config
      MYSQL_SERVICE_USER: nacos
      MYSQL_SERVICE_PASSWORD: nacosPassword123
      NACOS_AUTH_TOKEN: WW91ckN1c3RvbVNlY3JldEtleTAxMjM0NTY3ODlBQkNERUY=
      NACOS_AUTH_IDENTITY_KEY: nacosServerIdentity
      NACOS_AUTH_IDENTITY_VALUE: YourStrongIdentityValue2025
      JVM_XMS: 512m
      JVM_XMX: 512m
      JVM_XMN: 256m
    ports:
      - "8080:8080"
      - "8848:8848"
      - "9848:9848"
    volumes:
      - nacos-logs:/home/nacos/logs

volumes:
  nacos-mysql-data:
  nacos-logs:

Bash

# 启动
docker compose -f docker-compose-nacos.yml up -d

# 查看日志
docker logs -f nacos-server

5.3 Docker 环境变量参考

变量名	说明	默认值
`MODE`	启动模式	cluster
`NACOS_SERVERS`	集群地址列表（空格分隔）	—
`SPRING_DATASOURCE_PLATFORM`	数据源类型	空（Derby）
`MYSQL_SERVICE_HOST`	MySQL 主机	—
`MYSQL_SERVICE_PORT`	MySQL 端口	3306
`MYSQL_SERVICE_DB_NAME`	数据库名	—
`MYSQL_SERVICE_USER`	数据库用户	—
`MYSQL_SERVICE_PASSWORD`	数据库密码	—
`NACOS_AUTH_TOKEN`	JWT 密钥（Base64）	—
`NACOS_AUTH_IDENTITY_KEY`	节点身份 Key	—
`NACOS_AUTH_IDENTITY_VALUE`	节点身份 Value	—
`JVM_XMS` / `JVM_XMX` / `JVM_XMN`	JVM 内存配置	—
`NACOS_APPLICATION_PORT`	自定义主端口	8848
`PREFER_HOST_MODE`	使用 hostname 或 ip	ip

六、Kubernetes 部署

6.1 快速启动（无持久化）

Bash

# 克隆 nacos-k8s 项目
git clone https://github.com/nacos-group/nacos-k8s.git
cd nacos-k8s

编辑 deploy/nacos/nacos-quick-start.yaml，添加鉴权环境变量：

YAML

env:
  - name: NACOS_SERVERS
    value: "nacos-0.nacos-headless.default.svc.cluster.local:8848 nacos-1.nacos-headless.default.svc.cluster.local:8848 nacos-2.nacos-headless.default.svc.cluster.local:8848"
  - name: NACOS_AUTH_TOKEN
    value: "<你的Base64密钥>"
  - name: NACOS_AUTH_IDENTITY_KEY
    value: "nacosServerIdentity"
  - name: NACOS_AUTH_IDENTITY_VALUE
    value: "YourStrongIdentityValue2025"

Bash

# 启动
chmod +x quick-startup.sh
./quick-startup.sh

# 验证
kubectl logs -f nacos-0
# 成功标志：Nacos started successfully in cluster mode.

6.2 生产级 K8s 部署建议

使用 StatefulSet 部署 ≥3 副本
使用 PersistentVolumeClaim 挂载日志和数据目录
通过 ConfigMap 管理 application.properties
通过 Secret 管理数据库密码和 Auth Token
配置 Readiness/Liveness Probe 指向 http://:8848/nacos/actuator/health
使用内部 Service（ClusterIP） + Ingress 暴露控制台

七、生产环境配置详解

7.1 application.properties 完整生产模板

Text

# ==========================================
#  Nacos 3.0.3 生产环境配置模板
# ==========================================

# ---------- 端口配置 ----------
nacos.server.main.port=8848
nacos.console.port=8080

# ---------- 数据源（MySQL） ----------
spring.sql.init.platform=mysql
db.num=1
db.url.0=jdbc:mysql://mysql-vip:3306/nacos_config?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
db.user=nacos
db.password=<强密码>

# HikariCP 连接池
db.pool.config.connectionTimeout=30000
db.pool.config.maximumPoolSize=30
db.pool.config.minimumIdle=10
db.pool.config.idleTimeout=600000
db.pool.config.maxLifetime=1800000

# ---------- 鉴权 ----------
nacos.core.auth.system.type=nacos
nacos.core.auth.enabled=true
nacos.core.auth.admin.enabled=true
nacos.core.auth.console.enabled=true
nacos.core.auth.caching.enabled=true
nacos.core.auth.plugin.nacos.token.secret.key=<自定义Base64密钥>
nacos.core.auth.server.identity.key=<自定义Key>
nacos.core.auth.server.identity.value=<自定义Value>
nacos.core.auth.plugin.nacos.token.expire.seconds=18000

# ---------- JRaft 配置（集群一致性） ----------
nacos.core.protocol.raft.data.election_timeout_ms=5000
nacos.core.protocol.raft.data.snapshot_interval_secs=1800
nacos.core.protocol.raft.data.core_thread_num=8
nacos.core.protocol.raft.data.cli_service_thread_num=4
nacos.core.protocol.raft.data.read_index_type=ReadOnlySafe
nacos.core.protocol.raft.data.rpc_request_timeout_ms=5000

# ---------- Distro 协议（临时实例同步） ----------
nacos.core.protocol.distro.data.sync.delayMs=1000
nacos.core.protocol.distro.data.sync.timeoutMs=3000
nacos.core.protocol.distro.data.sync.retryDelayMs=3000
nacos.core.protocol.distro.data.verify.intervalMs=5000
nacos.core.protocol.distro.data.verify.timeoutMs=3000

# ---------- gRPC 配置 ----------
nacos.remote.server.grpc.sdk.max-inbound-message-size=10485760
nacos.remote.server.grpc.sdk.keep-alive-time=7200000
nacos.remote.server.grpc.sdk.keep-alive-timeout=20000

# ---------- Naming 模块 ----------
nacos.naming.data.warmup=true
nacos.naming.expireInstance=true
nacos.naming.empty-service.auto-clean=true
nacos.naming.empty-service.clean.initial-delay-ms=50000
nacos.naming.empty-service.clean.period-time-ms=30000

# ---------- Config 模块 ----------
nacos.config.push.maxRetryTime=50

# ---------- 访问日志 ----------
server.tomcat.accesslog.enabled=true
server.tomcat.accesslog.max-days=30
server.tomcat.accesslog.pattern=%h %l %u %t "%r" %s %b %D %{User-Agent}i %{Request-Source}i

# ---------- 监控（Prometheus） ----------
management.endpoints.web.exposure.include=prometheus
nacos.prometheus.metrics.enabled=true

# ---------- AI 模块（可选） ----------
# nacos.extension.ai.enabled=true
# nacos.ai.mcp.registry.enabled=false
# nacos.ai.registry.port=9080

7.2 JVM 调优

编辑 bin/startup.sh 中的 JVM 参数，或通过环境变量设置：

Bash

# 生产推荐 JVM 配置（8GB 内存节点）
JAVA_OPT="${JAVA_OPT} -server -Xms4g -Xmx4g -Xmn2g"
JAVA_OPT="${JAVA_OPT} -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m"
JAVA_OPT="${JAVA_OPT} -XX:+UseG1GC"
JAVA_OPT="${JAVA_OPT} -XX:MaxGCPauseMillis=200"
JAVA_OPT="${JAVA_OPT} -XX:+ParallelRefProcEnabled"
JAVA_OPT="${JAVA_OPT} -XX:+HeapDumpOnOutOfMemoryError"
JAVA_OPT="${JAVA_OPT} -XX:HeapDumpPath=${BASE_DIR}/logs/heapdump.hprof"
JAVA_OPT="${JAVA_OPT} -XX:+PrintGCDetails -Xloggc:${BASE_DIR}/logs/gc.log"

服务器内存	-Xms / -Xmx	-Xmn	MetaspaceSize
4 GB	2g	1g	128m / 256m
8 GB	4g	2g	256m / 512m
16 GB	8g	4g	256m / 512m

7.3 Prometheus + Grafana 监控

在 application.properties 中启用 Prometheus 端点：

Text

management.endpoints.web.exposure.include=prometheus
nacos.prometheus.metrics.enabled=true

Prometheus scrape_configs 配置：

YAML

scrape_configs:
  - job_name: 'nacos'
    metrics_path: '/nacos/actuator/prometheus'
    static_configs:
      - targets:
          - '192.168.1.11:8848'
          - '192.168.1.12:8848'
          - '192.168.1.13:8848'

Grafana 导入 Nacos 官方 Dashboard（Dashboard ID: 13221）

7.4 systemd 服务管理

创建 /etc/systemd/system/nacos.service：

Text

[Unit]
Description=Nacos Server 3.0.3
After=network.target mysql.service

[Service]
Type=forking
User=nacos
Group=nacos
Environment="JAVA_HOME=/usr/local/jdk-17"
ExecStart=/opt/nacos/bin/startup.sh
ExecStop=/opt/nacos/bin/shutdown.sh
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Bash

# 创建 nacos 用户
sudo useradd -r -s /sbin/nologin nacos
sudo chown -R nacos:nacos /opt/nacos

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable nacos
sudo systemctl start nacos
sudo systemctl status nacos

7.5 日志管理

Nacos 日志位于 ${nacos.home}/logs/ 目录：

日志文件	说明
`start.out`	启动日志
`nacos.log`	主运行日志
`naming-server.log`	服务注册/发现日志
`config-server.log`	配置管理日志
`nacos-cluster.log`	集群同步日志

建议配合 logrotate 或日志采集工具（Filebeat/Fluentd）管理日志轮转与归档。

八、常见问题与排查

8.1 启动失败：鉴权未配置

现象： 日志报 nacos.core.auth.plugin.nacos.token.secret.key must not be blank

原因： Nacos 3.0 强制要求配置鉴权三项参数

解决： 参照第三节 3.2 配置 application.properties 中的鉴权参数

8.2 集群节点无法互相发现

现象： 节点启动但控制台只显示自身

排查步骤：

确认 cluster.conf 中 IP 和端口正确且所有节点一致
检查防火墙是否开放 7848（Raft）和 9848（gRPC）端口
确认 nacos.inetutils.ip-address 是否与 cluster.conf 中的 IP 匹配
查看 nacos-cluster.log 获取详细错误信息

8.3 外置 MySQL 连接失败

现象： No DataSource set 或 Communications link failure

排查步骤：

确认 spring.sql.init.platform=mysql 已设置
检查 db.url.0 中的主机、端口、数据库名是否正确
确认 MySQL 用户有远程访问权限：GRANT ALL ON nacos_config.* TO 'nacos'@'%'
检查网络连通性：telnet mysql-host 3306
确认 mysql-schema.sql 已正确导入

8.4 Docker 容器中无法连接宿主机 MySQL

原因： Docker 容器网络与宿主机网络隔离

解决方案：

使用 host.docker.internal（Docker Desktop）或宿主机实际 IP 作为 MySQL 地址
使用 --network host 模式运行容器
Docker Compose 中将 MySQL 放在同一 network 中

8.5 内存不足导致 OOM

现象： 日志出现 java.lang.OutOfMemoryError

解决： 参照第七节 7.2 根据服务器内存调整 JVM 参数，确保 -Xmx 不超过物理内存的 70%

8.6 gRPC 连接超时

现象： 客户端报 UNAVAILABLE: io exception 或连接 9848 端口超时

排查步骤：

确认防火墙/安全组已开放 9848 端口
如使用 SLB，确认 gRPC 端口已配置 TCP 转发（非 HTTP）
检查 gRPC 相关配置参数是否合理

九、快速参考

常用命令速查

操作	命令
单机启动	`sh bin/startup.sh -m standalone`
集群启动（外置 DB）	`sh bin/startup.sh`
集群启动（内嵌 DB）	`sh bin/startup.sh -p embedded`
停止服务	`sh bin/shutdown.sh`
查看启动日志	`tail -f logs/start.out`
检查集群状态	`curl http://IP:8848/nacos/v3/console/server/state`
Docker 快速启动	`docker run -d -e MODE=standalone ... nacos/nacos-server:v3.0.3`

关键文件路径

文件/目录	说明
`conf/application.properties`	主配置文件
`conf/cluster.conf`	集群节点列表
`conf/mysql-schema.sql`	MySQL 初始化 SQL
`bin/startup.sh`	启动脚本（含 JVM 参数）
`bin/shutdown.sh`	停止脚本
`logs/`	日志目录
`data/`	数据目录（Derby/Raft 快照）