Nacos单机部署入门：避坑指南与实战

真实的菜2026-06-13 8:47

第一次搭Nacos踩了5个坑：单机部署从入门到第一个服务注册

下载、解压、启动、报错，循环了4次

第一次搭 Nacos 是在一台刚装好的 CentOS 上。

复制代码 
wget https://github.com/alibaba/nacos/releases/download/2.3.2/nacos-server-2.3.2.zip
unzip nacos-server-2.3.2.zip
cd nacos/bin
./startup.sh -m standalone

然后盯着终端看了 10 秒。没有报错。访问 http://localhost:8848/nacos------打不开。

查了 20 分钟，发现 JDK 版本是 1.8.0_144，而 Nacos 2.3 需要 1.8.0_292 以上。

从那以后我每次搭 Nacos 都走一套固定流程。这篇文章就是把这套流程写出来，附上每个环节最常踩的坑和解决办法。

第一步：环境检查

#mermaid-svg-EVFXBrkhGVjoM5Dz{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-EVFXBrkhGVjoM5Dz .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-EVFXBrkhGVjoM5Dz .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-EVFXBrkhGVjoM5Dz .error-icon{fill:#552222;}#mermaid-svg-EVFXBrkhGVjoM5Dz .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-EVFXBrkhGVjoM5Dz .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-EVFXBrkhGVjoM5Dz .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-EVFXBrkhGVjoM5Dz .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-EVFXBrkhGVjoM5Dz .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-EVFXBrkhGVjoM5Dz .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-EVFXBrkhGVjoM5Dz .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-EVFXBrkhGVjoM5Dz .marker{fill:#333333;stroke:#333333;}#mermaid-svg-EVFXBrkhGVjoM5Dz .marker.cross{stroke:#333333;}#mermaid-svg-EVFXBrkhGVjoM5Dz svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-EVFXBrkhGVjoM5Dz p{margin:0;}#mermaid-svg-EVFXBrkhGVjoM5Dz .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-EVFXBrkhGVjoM5Dz .cluster-label text{fill:#333;}#mermaid-svg-EVFXBrkhGVjoM5Dz .cluster-label span{color:#333;}#mermaid-svg-EVFXBrkhGVjoM5Dz .cluster-label span p{background-color:transparent;}#mermaid-svg-EVFXBrkhGVjoM5Dz .label text,#mermaid-svg-EVFXBrkhGVjoM5Dz span{fill:#333;color:#333;}#mermaid-svg-EVFXBrkhGVjoM5Dz .node rect,#mermaid-svg-EVFXBrkhGVjoM5Dz .node circle,#mermaid-svg-EVFXBrkhGVjoM5Dz .node ellipse,#mermaid-svg-EVFXBrkhGVjoM5Dz .node polygon,#mermaid-svg-EVFXBrkhGVjoM5Dz .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-EVFXBrkhGVjoM5Dz .rough-node .label text,#mermaid-svg-EVFXBrkhGVjoM5Dz .node .label text,#mermaid-svg-EVFXBrkhGVjoM5Dz .image-shape .label,#mermaid-svg-EVFXBrkhGVjoM5Dz .icon-shape .label{text-anchor:middle;}#mermaid-svg-EVFXBrkhGVjoM5Dz .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-EVFXBrkhGVjoM5Dz .rough-node .label,#mermaid-svg-EVFXBrkhGVjoM5Dz .node .label,#mermaid-svg-EVFXBrkhGVjoM5Dz .image-shape .label,#mermaid-svg-EVFXBrkhGVjoM5Dz .icon-shape .label{text-align:center;}#mermaid-svg-EVFXBrkhGVjoM5Dz .node.clickable{cursor:pointer;}#mermaid-svg-EVFXBrkhGVjoM5Dz .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-EVFXBrkhGVjoM5Dz .arrowheadPath{fill:#333333;}#mermaid-svg-EVFXBrkhGVjoM5Dz .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-EVFXBrkhGVjoM5Dz .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-EVFXBrkhGVjoM5Dz .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-EVFXBrkhGVjoM5Dz .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-EVFXBrkhGVjoM5Dz .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-EVFXBrkhGVjoM5Dz .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-EVFXBrkhGVjoM5Dz .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-EVFXBrkhGVjoM5Dz .cluster text{fill:#333;}#mermaid-svg-EVFXBrkhGVjoM5Dz .cluster span{color:#333;}#mermaid-svg-EVFXBrkhGVjoM5Dz div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-EVFXBrkhGVjoM5Dz .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-EVFXBrkhGVjoM5Dz rect.text{fill:none;stroke-width:0;}#mermaid-svg-EVFXBrkhGVjoM5Dz .icon-shape,#mermaid-svg-EVFXBrkhGVjoM5Dz .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-EVFXBrkhGVjoM5Dz .icon-shape p,#mermaid-svg-EVFXBrkhGVjoM5Dz .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-EVFXBrkhGVjoM5Dz .icon-shape .label rect,#mermaid-svg-EVFXBrkhGVjoM5Dz .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-EVFXBrkhGVjoM5Dz .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-EVFXBrkhGVjoM5Dz .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-EVFXBrkhGVjoM5Dz :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 环境检查
JDK 版本
端口占用
内存
≥ 1.8.0_292

建议 JDK 17 用于 2.4+
8848 / 9848 / 9849

三个端口都不能被占
至少 2G 可用内存

启动前检查三个东西：JDK 版本、端口占用、可用内存。三个有一个不对，Nacos 都起不来。

JDK 版本对照

Nacos 版本 最低 JDK 推荐 JDK
1.x 1.8.0_60 1.8.0_292+
2.0 ~ 2.2 1.8.0_292 11
2.3+ 1.8.0_292 17
bash 复制代码 
# 确认 JDK 版本
java -version

# 如果不是高版本，安装 OpenJDK 17
# Ubuntu
sudo apt install openjdk-17-jdk -y

# CentOS
sudo yum install java-17-openjdk-devel -y

# Windows
# 去 https://adoptium.net 下载 msi 安装包

Nacos 需要三个端口

复制代码 
8848 → HTTP 主端口（控制台 + OpenAPI）
9848 → gRPC 客户端通信（2.x 新增）
9849 → gRPC 集群节点间通信（2.x 新增）
bash 复制代码 
# 检查端口是否被占用
# Linux/Mac
lsof -i :8848
lsof -i :9848

# Windows PowerShell
netstat -ano | findstr "8848"

坑1：很多人只检查 8848，忘了 9848。 8848 空闲但 9848 被占，Nacos 能启动但 gRPC 通道不通，2.x 客户端连不上。

第二步：下载 & 目录结构

bash 复制代码 
# 最新稳定版（以 2.3.2 为例）
wget https://github.com/alibaba/nacos/releases/download/2.3.2/nacos-server-2.3.2.zip

# 解压
unzip nacos-server-2.3.2.zip -d ./nacos

# 目录结构
cd nacos
tree -L 2

解压后的关键目录：

复制代码 
nacos/
├── bin/
│   ├── startup.sh          # Linux/Mac 启动脚本
│   ├── startup.cmd         # Windows 启动脚本
│   └── shutdown.sh         # 停止脚本
├── conf/
│   ├── application.properties  # 核心配置文件
│   ├── cluster.conf.example    # 集群配置示例
│   └── nacos-logback.xml       # 日志配置
├── target/
│   └── nacos-server.jar        # 主 jar 包
└── logs/                       # 启动后生成

第三步：启动 standalone 模式

Linux / Mac

bash 复制代码 
# standalone 模式启动（不分集群，单机运行）
cd nacos/bin
./startup.sh -m standalone

# 输出大致是这样的：
# nacos is starting with standalone
# nacos is starting，you can check the /opt/nacos/logs/start.out

坑2：-m standalone 不写的话，默认以集群模式启动。 单机跑集群模式会报错，因为找不到集群其他节点。

Windows

cmd 复制代码 
cd nacos\bin
startup.cmd -m standalone

确认启动成功

bash 复制代码 
# 方法1：看日志
tail -f nacos/logs/start.out

# 看到这一行就是启动成功了：
# Nacos started successfully in stand alone mode.

# 方法2：看端口
netstat -tlnp | grep 8848

# 方法3：直接访问
curl http://127.0.0.1:8848/nacos/v1/console/health/readiness
# 返回 ok

Nacos Server JVM startup.sh 你 Nacos Server JVM startup.sh 你 #mermaid-svg-izv9r9nQMkpt2WYw{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-izv9r9nQMkpt2WYw .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-izv9r9nQMkpt2WYw .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-izv9r9nQMkpt2WYw .error-icon{fill:#552222;}#mermaid-svg-izv9r9nQMkpt2WYw .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-izv9r9nQMkpt2WYw .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-izv9r9nQMkpt2WYw .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-izv9r9nQMkpt2WYw .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-izv9r9nQMkpt2WYw .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-izv9r9nQMkpt2WYw .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-izv9r9nQMkpt2WYw .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-izv9r9nQMkpt2WYw .marker{fill:#333333;stroke:#333333;}#mermaid-svg-izv9r9nQMkpt2WYw .marker.cross{stroke:#333333;}#mermaid-svg-izv9r9nQMkpt2WYw svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-izv9r9nQMkpt2WYw p{margin:0;}#mermaid-svg-izv9r9nQMkpt2WYw .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-izv9r9nQMkpt2WYw text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-izv9r9nQMkpt2WYw .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-izv9r9nQMkpt2WYw .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-izv9r9nQMkpt2WYw .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-izv9r9nQMkpt2WYw .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-izv9r9nQMkpt2WYw #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-izv9r9nQMkpt2WYw .sequenceNumber{fill:white;}#mermaid-svg-izv9r9nQMkpt2WYw #sequencenumber{fill:#333;}#mermaid-svg-izv9r9nQMkpt2WYw #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-izv9r9nQMkpt2WYw .messageText{fill:#333;stroke:none;}#mermaid-svg-izv9r9nQMkpt2WYw .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-izv9r9nQMkpt2WYw .labelText,#mermaid-svg-izv9r9nQMkpt2WYw .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-izv9r9nQMkpt2WYw .loopText,#mermaid-svg-izv9r9nQMkpt2WYw .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-izv9r9nQMkpt2WYw .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-izv9r9nQMkpt2WYw .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-izv9r9nQMkpt2WYw .noteText,#mermaid-svg-izv9r9nQMkpt2WYw .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-izv9r9nQMkpt2WYw .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-izv9r9nQMkpt2WYw .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-izv9r9nQMkpt2WYw .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-izv9r9nQMkpt2WYw .actorPopupMenu{position:absolute;}#mermaid-svg-izv9r9nQMkpt2WYw .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-izv9r9nQMkpt2WYw .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-izv9r9nQMkpt2WYw .actor-man circle,#mermaid-svg-izv9r9nQMkpt2WYw line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-izv9r9nQMkpt2WYw :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} ./startup.sh -m standalone检查 JAVA_HOME设置 JVM 参数（默认 -Xms512m -Xmx512m -Xmn256m）启动 jar 包Spring Boot 初始化加载 application.properties初始化 Derby 数据库启动 HTTP(8848) + gRPC(9848) 端口启动完成

启动流程：Shell 脚本 → JVM 参数设置 → Spring Boot 初始化 → 内嵌 Derby 初始化 → 双端口监听。

第四步：访问控制台 & 注册第一个服务

打开浏览器访问 http://localhost:8848/nacos：

  • 默认账号：nacos
  • 默认密码：nacos

坑3：2.2+ 版本首次登录必须改密码。 用默认密码登录后会出现修改密码的页面。记得把这个密码记下来。

用 Spring Boot 注册一个服务

xml 复制代码 
<!-- pom.xml -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    <version>2023.0.1.0</version>
</dependency>
yaml 复制代码 
# application.yml
spring:
  application:
    name: demo-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        username: nacos
        password: nacos
java 复制代码 
@SpringBootApplication
@EnableDiscoveryClient
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

启动后，回到 Nacos 控制台 → 服务管理 → 服务列表，看到 demo-service 就说明部署成功了。

第五步：Derby vs MySQL ------ 别在生产环境用 Derby

内置 Derby 的问题

Nacos 默认使用内嵌的 Apache Derby 数据库。它能用，但有三个问题：

  1. 数据无法共享。集群模式下每个节点有自己的 Derby 实例，数据不同步。
  2. 不支持高并发写入。Derby 是单文件嵌入式数据库，写操作会锁整个库。
  3. 不支持运维操作。没法做主从、没法做备份、没法用 Navicat 看数据。

坑4：很多团队 standalone 模式用 Derby 跑着跑着就开始丢数据。 尤其是配置多了之后。

切换到 MySQL

properties 复制代码 
# conf/application.properties
# 把原来的 Derby 配置注释掉：
# spring.sql.init.platform=derby

# 换成 MySQL：
spring.sql.init.platform=mysql
db.num=1
db.url.0=jdbc:mysql://127.0.0.1:3306/nacos_config?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8
db.user.0=root
db.password.0=your_password
sql 复制代码 
-- 创建一个空数据库
CREATE DATABASE IF NOT EXISTS nacos_config DEFAULT CHARACTER SET utf8mb4;

重启 Nacos 后，它会自动在 MySQL 里创建所有表。配置数据和服务注册信息都会落到 MySQL。

启动失败 5 大原因速查

报错 原因 解决
java.lang.UnsupportedClassVersionError JDK 版本太低 升级到 JDK 17
Address already in use 端口 8848/9848 被占用 lsof -i :8848 找到进程 kill 掉
cluster.conf 找不到 standalone 模式没指定 -m 加上 -m standalone
Unable to connect to database MySQL 配置错了 检查 db.url.0 和用户名密码
nacos is starting with cluster 误启动了集群模式 确认用了 -m standalone 参数

一键脚本（懒得手动敲的可以用）

bash 复制代码 
#!/bin/bash
# nacos-standalone-quickstart.sh
# 使用方法: chmod +x nacos-standalone-quickstart.sh && ./nacos-standalone-quickstart.sh

NACOS_VERSION="2.3.2"
NACOS_HOME="/opt/nacos"

# 1. 下载
wget -q https://github.com/alibaba/nacos/releases/download/${NACOS_VERSION}/nacos-server-${NACOS_VERSION}.zip -O /tmp/nacos.zip

# 2. 解压
unzip -qo /tmp/nacos.zip -d ${NACOS_HOME}

# 3. 启动
cd ${NACOS_HOME}/nacos/bin
./startup.sh -m standalone

# 4. 等 5 秒后检查
sleep 5
curl -s http://127.0.0.1:8848/nacos/v1/console/health/readiness && echo "Nacos 启动成功！" || echo "启动失败，请查看日志：${NACOS_HOME}/nacos/logs/start.out"

总结

单机部署 5 步走：

  1. 环境检查：JDK 版本 ≥ 1.8.0_292（推荐 17），8848/9848/9849 三个端口空闲，内存 ≥ 2G。
  2. 下载解压：从 GitHub Releases 下最新版，解压到服务器。
  3. standalone 启动 ：./startup.sh -m standalone，别忘了 -m standalone。
  4. 验证 ：访问 localhost:8848/nacos，默认账号 nacos/nacos，注册一个 Demo 服务。
  5. 切 MySQL：生产环境一定要把 Derby 换成 MySQL。

常见报错记牢五个就行：JDK 版本低、端口占用、忘加 -m standalone、MySQL 连不上、误启集群模式。

你第一次搭 Nacos 踩了什么坑？评论区留个数字：1=JDK版本太低 2=端口被占 3=忘了-m standalone 4=Derby丢数据 5=其他（具体说说）。我看看哪个坑踩的人最多。

相关推荐
asdfg12589631 小时前
三层架构（Controller-Service-DAO）模式中的controller 和 dao/mapper的通俗理解
java·架构模式
霸道流氓气质1 小时前
JWT 认证全面解析：原理、流程与 Spring Boot 实战
java·spring boot·后端
TeamDev1 小时前
JxBrowser 9.1.2 版本发布啦！
java·跨平台·混合应用·jxbrowser·浏览器控件·compose 多平台
逢君学术论文AI写作2 小时前
Java第21课：JavaWeb入门——Tomcat+第一个Servlet
java·servlet·tomcat
就叫_这个吧2 小时前
Java使用tomcat+servlet+filter实现简单的登录功能，需先登录再进行页面数据管理操作
java·开发语言·servlet·tomcat·jsp·filter
十五年专注C++开发2 小时前
ANTLR4: CORBA IDL、C++ 语法文件分析利器
java·开发语言·c++·antlr4
子非衣2 小时前
Java使用Aspose进行Word转PDF时异常卡主问题
java·pdf·word
此生决int2 小时前
Java面向对象进阶精讲：抽象类、接口、内部类与Object类万字详解
java
热门推荐
01HTTP 与 HTTPS 的区别：从原理到实战详解02《置身钉内》原文-可播放阅读03【AI】2026 年具身智能模型和世界模型总结042026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？05Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析06AI科技热点日报 | 2026年6月1日072026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？08GitHub 镜像站点09AI一周事件 · 2026-06-03 至 2026-06-09102026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf