Nacos 这个中间件现在基本可以算微服务体系的标配了。做服务注册发现和配置管理Spring Cloud Alibaba、Dubbo 生态里都会遇到它。最近我帮好几个项目做了 nacos 部署有单机也有集群过程中踩了不少坑也整理出一套比较顺手的操作流程。这篇文章就从一个经常和部署、排障打交道的运维视角把 nacos 单机部署和集群部署的完整路径讲清楚该改的配置、该放的端口、该避的坑一次说透希望能帮你少走点弯路。无论你是刚接触 Spring Cloud 的开发者还是负责中间件维护的运维同学只要接下来要碰 Nacos这篇文章都值得你花几分钟看完。单机怎么快速跑起来并不难集群部署才是真正考验架构意识的地方两者我都有详细的实操记录。1. 先搞清楚需求单机部署和集群部署怎么选1.1 单机部署的真实场景很多人一上来就问“单机怎么装”但我想先泼一盆冷水单机部署并不是用来扛生产的它有非常明确的使用边界。单机模式主要出现在开发环境、测试环境以及一些内部小工具类项目里。比如你本地写 Spring Boot 服务不想用一堆第三方中间件只想把服务注册发现和配置中心跑起来那直接单机启动一个 Nacos 就够了。再比如公司内部某个后台系统注册的服务数量几十个流量不大临时用单机版本也说得过去。单机模式最大的优势是省事。默认自带的嵌入式 Derby 数据库几乎零依赖解压即用不需要额外准备 MySQL。但省事的另一面是数据持久化很弱Derby 数据文件就放在本地 data 目录里机器一挂或者目录被清掉配置和注册信息就全没了。所以我个人的建议是哪怕是单机只要这台机器承担了配置中心职责就把存储切到 MySQL别用 Derby 长期跑。这个切换我后面会单独拿出来讲因为确实有人用默认配置跑了半年后来机器重启后发现数据全丢了那个感受真的很难受。1.2 集群部署要解决的核心问题集群部署解决的是单点故障和数据可靠性的问题。一个 Nacos 节点挂掉如果它是注册中心所有依赖它的服务都会失去服务发现能力新启动的实例注册不进来调用方也可能拿不到最新的实例列表整个微服务链路很容易雪崩。如果它同时是配置中心客户端拉不到配置启动直接失败线上事故分分钟就来了。Nacos 集群典型的架构是多个 Nacos 节点组成一个集群节点之间通过 Raft 协议同步状态所有节点共享同一个 MySQL 数据库来存配置数据。对外由一个负载均衡入口承接客户端请求比如 Nginx、云上的 SLB或者 K8s 里的 Service。客户端不直接跟单个节点打交道而是走这个统一入口。这里有个关键点需要解释为什么生产环境推荐至少 3 个节点因为集群的选举基于多数派原则3 个节点挂 1 个还能正常选主5 个节点挂 2 个也没问题但 2 个节点挂 1 个就选不出结果了。所以节点数量尽量取奇数2 个节点是最尴尬的看着有冗余实际一挂就瘫。做集群规划的时候别贪多也别省事三节点起步最稳。2. 部署前的准备工作版本、JDK、端口、数据库2.1 Nacos 版本怎么选才不踩坑版本选型看着简单实际是最容易埋雷的地方。Nacos 1.x 和 2.x 的通信机制差别很大2.x 默认引入了 gRPC 长连接端口占用逻辑和 1.x 完全不同。现在新项目基本都该用 2.x还在用 1.x 的老项目迁移成本也不高我建议尽早升级。如果你准备用 MySQL 8.x比如现在常见的 MySQL 8.0 和更新的 8.4.11那 Nacos 版本不要太旧。我实测下来Nacos 2.2.0 以上版本对 MySQL 8 的兼容性才比较稳妥尤其是认证插件 caching_sha2_password 的问题老版本驱动可能连不上。另外从 2.2 开始MySQL 驱动包不再默认内置在启动依赖里需要手动把 mysql-connector-j 的 jar 包放到${NACOS_HOME}/plugins/mysql/目录否则启动时会报找不到驱动类。这个坑我第一次部署时就踩了当时还以为是数据库配置写错了排查了半天。还有一点务必注意如果你用的是 2.2.0 或更早版本建议升级到 2.2.0.1 以上的补丁版本因为老的 Nacos 存在默认 JWT 密钥导致身份认证被绕过的安全漏洞攻击者可以用公开的默认密钥伪造管理员 Token直接访问控制台和管理接口。这个漏洞在下文安全加固部分我会详细说修复方式这里先记住结论别用老版本裸奔。2.2 目录结构和关键配置文件认识一遍下载 Nacos 的二进制包后解压出来核心目录其实就几个bin 目录放启动脚本conf 目录放配置文件data 目录是 Derby 或集群内部数据目录logs 目录自然就是日志了。我第一次用的时候最常犯的错就是找不到启动日志其实 Nacos 的启动日志在 logs/start.out 里报错信息基本都集中在这个文件。配置文件方面单机模式下最重要的是 conf/application.properties。这个文件里你会看到很多被注释掉的配置项最核心的是数据源切换相关的几行spring.datasource.platformmysql db.num1 db.url.0jdbc:mysql://127.0.0.1:3306/nacos_config?characterEncodingutf8connectTimeout1000socketTimeout3000autoReconnecttrueuseSSLfalseserverTimezoneAsia/Shanghai db.user.0root db.password.0yourpassword集群模式下还要关注 conf/cluster.conf这个文件描述集群里有哪些节点格式很简单每行一个IP:8848。需要注意不能写 localhost 或 127.0.0.1否则节点之间互相发现的地址就错了。如果是多网卡机器务必写能互通的真实 IP不然节点能找到自己但找不到对方。端口方面Nacos 2.x 默认监听 8848 端口但这不是全部。它内部还会占用 9848gRPC 请求端口默认主端口1000、9849gRPC 服务端端口、7848集群 Raft 通信端口。当初我在云服务器上部署只放行了 8848客户端服务注册一直超时折腾半天才反应过来 9848 端口没放开。3. Nacos 单机部署实操从零配置起步到 MySQL 持久化3.1 第一次启动用默认 Derby 快速跑起来如果你只想在本地验证一下 Nacos 功能最省事的路径就是用默认 Derby 启动。前提是机器上装好了 JDK推荐 JDK 8 以上的较新版本我自己习惯用 JDK 8 或 JDK 11稳定压倒一切。切到解压目录后Linux 或 macOS 上执行cd /opt/nacos sh startup.sh -m standaloneWindows 上则执行cd D:\nacos startup.cmd -m standalone执行后别急着关终端观察一下输出。启动完成后用浏览器访问http://localhost:8848/nacos默认账号密码都是nacos/nacos登录进去会看到控制台界面。看到这个界面说明单机实例已经活了。有几个细节值得记录一下。第一次启动时如果 8848 端口被占用启动会直接失败看 start.out 会提示端口绑定异常。另外启动脚本默认给 JVM 分配的内存比较大我记着默认 Xms/Xmx 都是 2G如果是小内存机器比如 2G 的轻量云服务器会直接起不来或很卡需要手动调小。可以在启动脚本里看到JAVA_OPT相关的参数或者通过环境变量JVM_XMS、JVM_XMX来覆盖我习惯设置成JVM_XMS256m JVM_XMX512m这种级别开发机完全够用。再说个容易忽略的点standalone 模式下如果多次启停data 目录里的 Derby 数据库可能出现锁文件残留导致下次启动失败。遇到这种情况可以停服后删掉 data 目录再重启。当然这只是临时方案真正要用 Nacos 存配置还是得切 MySQL。3.2 换成 MySQL 存储配置与初始化把 Nacos 的配置数据从 Derby 切到 MySQL本质就两步建库建表改配置重启。首先在 MySQL 里新建一个独立的数据库名字随意我习惯叫nacos_config。Nacos 的 conf 目录下自带初始化 SQL 文件叫nacos-mysql.sql里面包含了配置存储、用户权限、集群元数据等所有表结构。在命令行执行mysql -uroot -p -e CREATE DATABASE nacos_config DEFAULT CHARACTER SET utf8mb4; mysql -uroot -p nacos_config /opt/nacos/conf/nacos-mysql.sql这里有个小经验建库时字符集我用 utf8mb4因为有些配置内容可能包含特殊字符和表情符号用老 utf8 会出现存储报错。如果你建库时没指定字符集后期写入中文字符或特殊符号时很容易遇到乱码问题。建完库后编辑conf/application.properties文件把前面提到的数据源配置解开。注意db.num默认可能被注释掉需要手动改成 1db.url.0里的 IP、端口、库名、账号密码都要改成自己的。配置完成后重启 Nacos登录控制台随便新建一个配置然后去 MySQL 里查一下config_info表能看到数据说明切换成功了。如果你用的是 MySQL 8.x还记得前面说的驱动问题吗别忘了解压一个 mysql-connector-j jar 到plugins/mysql目录然后用启动脚本重新拉起来。驱动版本别太老我一般用 8.0.33 或更新版本连 8.4 的 MySQL 基本没问题。3.3 外部访问和 Windows 启动的细节处理单机部署跑通后很多人紧接着会遇到一个问题本地能访问别人或者其他服务器访问不了。这时候要从几个层面查。首先是防火墙。Linux 上如果开启了 firewalld 或 iptables需要放行 8848、9848、9849 端口。CentOS Stream 9 这类较新系统上我用过firewall-cmd --zonepublic --add-port8848/tcp --permanent firewall-cmd --zonepublic --add-port9848/tcp --permanent firewall-cmd --zonepublic --add-port9849/tcp --permanent firewall-cmd --reload云服务器的话还要去云控制台的安全组规则里放行对应端口。有些云厂商默认安全组只开 22、80、443其他端口全都不通别只想着改服务器防火墙安全组也要检查。其次是 Nacos 的启动参数默认绑定 0.0.0.0理论上监听所有网卡不需要额外改 bind 地址。但也有一种情况就是机器有多个网卡比如内网和公网网卡客户端通过公网 IP 访问不到这时候需要检查安全组和路由必要时用 Nginx 做端口转发来兜底。Windows 启动时还有一个经典问题中文乱码。这是因为 Nacos 的启动脚本和控制台输出用的编码不一致。解决方式是在startup.cmd中给 java 命令加上-Dfile.encodingutf-8或者调整 Windows 终端的代码页为 UTF-8。乱码不影响功能但报错信息看不清排查问题会很难受所以这个细节我一般顺手就处理好。4. Nacos 集群部署实操三节点高可用方案4.1 集群拓扑规划与端口清单集群部署前做规划比敲命令重要得多。我先给一个常见的三节点拓扑说明方便你对号入座3 台 Nacos 服务器假设 IP 分别为 192.168.1.11、192.168.1.12、192.168.1.13操作系统都是 LinuxJDK 版本统一。1 个 MySQL 实例生产上推荐 MySQL 主从或云 RDS所有 Nacos 节点连接同一个数据库。1 个 Nginx 或云负载均衡后端指向 3 个 Nacos 节点的 8848 端口。这里要提醒一下Nacos 集群的数据一致性依赖 Raft 成员通信节点之间必须能通过 7848 端口互相访问云服务器安全组、服务器防火墙、以及 Docker 网络策略都要保证这一条。嘴皮子说一百遍不如提前列一张端口清单端口用途开放范围8848主 HTTP 端口控制台和客户端 HTTP 请求客户端、负载均衡、运维人员9848gRPC 客户端请求端口88481000客户端、负载均衡9849gRPC 服务端请求端口集群节点之间按需开放7848Raft 选举和成员通信端口仅集群节点之间3306后端 MySQL仅 Nacos 节点到数据库很多部署项目出问题都是因为只放行 8848结果客户端报注册失败这个锅大概率要由 9848 来背。4.2 三个节点依次配置和启动Step 1在每台服务器上解压 Nacos 包版本保持一致目录最好也保持一致比如都放在/opt/nacos。Step 2修改每台机器的conf/application.properties数据源配置指向同一个 MySQL。也就是说3 台机器的db.url.0、db.user.0、db.password.0完全一样只是各自的 IP 和机器信息不同。Step 3配置集群节点列表。修改每台机器的conf/cluster.conf文件内容三行192.168.1.11:8848 192.168.1.12:8848 192.168.1.13:8848三台机器写的内容一模一样不要只写自己。Step 4在每台机器上执行启动命令。注意这里启动不能加-m standalone直接执行sh startup.sh脚本默认会走集群模式。启动后观察logs/start.out看到服务启动成功且集群节点互相发现没有报连接异常说明基本配置对了。这里还有一个实操细节启动顺序。理论上 3 个节点可以同时启动但为了排查方便我习惯先把节点 11 启动观察一下日志再启动 12看 11 的日志里有没有出现节点 12 的注册信息最后启动 13。这样顺序错开如果哪个节点网络不通很快就能定位是第几台的问题。启动全部完成后可以从任意一台的http://IP:8848/nacos进入控制台在“集群管理”菜单里能看到节点列表如果 3 个节点都在线就说明集群组成了。控制台里的节点状态会显示 UP 或 DOWNDOWN 的节点需要去对应服务器看日志排查。4.3 负载均衡、外部访问与高可用验证集群只是后端的事情客户端接入时不应该直连某个节点而是通过一个统一入口。最常见的做法是用 Nginx 做负载均衡。我写一个最基础的资源配置upstream nacos_cluster { server 192.168.1.11:8848; server 192.168.1.12:8848; server 192.168.1.13:8848; keepalive 32; } server { listen 8848; server_name yourdomain.com; location / { proxy_pass http://nacos_cluster; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }把域名yourdomain.com解析到 Nginx 服务器客户端配置注册中心地址就写这个域名或 Nginx 的 VIP 加端口这样 Nginx 挂了还可以切备Nacos 单节点挂掉也不会影响整体接入。外部访问遇到问题时记得把 Nginx 所在机器的 8848 端口也加入安全组同时确保它到后端 3 个节点的 8848、9848、9849 网络都是通的。如果你是在 Rancher 或 Kubernetes 环境里部署 Nacos注意 Service 的暴露方式。用NodePort或LoadBalancer把 Nacos 服务端口映射到宿主机避免只映射 8848 不管 gRPC 端口。Pod 重建时 IP 会变化推荐使用固定 Service 域名或者 hostNetwork 方式否则集群节点列表会因为 IP 漂移出现问题。高可用验证也很简单直接。先把 3 个节点都启动在任意节点控制台看集群状态正常然后手动停掉其中一个节点比如把节点 12 的进程 kill 掉再去控制台看集群状态另外两个节点应该保持在线接着尝试从客户端读写配置、服务注册比如启动一个 Spring Boot 服务并调用配置接口确认没有报错。如果一切正常说明冗余生效了。最后把节点 12 重新拉起来观察它会不会自动重新加入集群。这个演练建议每个集群上线前都做一遍别等项目跑起来挂着才临时验证。真到事故现场再查配置心态完全是两个级别。5. 部署完成后的配置管理与安全加固5.1 账号密码、鉴权开关与默认密钥加固Nacos 初始账号密码 nacos/nacos 人尽皆知不修改等于把控制台裸奔在公网。登录控制台后第一件事就是在“权限控制”里改密码。如果一个 Nacos 集群同时有多个团队使用强烈建议开启鉴权和命名空间隔离避免所有人混在一个空间里改来改去。开启鉴权需要修改application.properties加上这几行配置nacos.core.auth.enabledtrue nacos.core.auth.plugin.nacos.token.secret.key你的自定义Base64密钥 nacos.core.auth.server.identity.key自定义Key nacos.core.auth.server.identity.value自定义Value密钥生成很简单用 openssl 命令openssl rand -base64 32拿到的字符串直接填进去。网上很多文章让用默认密钥甚至有些老版本代码里内置了默认值这就是导致漏洞的原因之一。Nacos 2.2.0 及之前版本存在的默认 JWT 密钥绕过认证漏洞攻击者利用公开的默认密钥不登录就能伪造 Token 访问管理接口和 Namespace 数据。修复方式就是升级到补丁版本并且一定修改默认 Token 密钥。如果你发现生产环境的 Nacos 还是旧版本别犹豫赶紧排期升级。顺便提一句开启鉴权后客户端接入时也要配置账号密码否则服务注册和配置拉取会报 403。Spring Cloud Alibaba 项目里通过spring.cloud.nacos.username和spring.cloud.nacos.password配置即可。5.2 配置中心动态刷新的正确姿势Nacos 作为配置中心最大的优势之一就是变动配置能实时推送给客户端。控制台里改一个配置客户端不用重启新值立刻生效。这个能力背后依赖的是客户端长轮询机制客户端每隔一段时间向服务端发起配置监听请求服务端有变更时直接返回结果客户端本地再更新内存里的配置。但需要注意热更新并不是改完配置客户端就自动全局生效需要代码配合。Spring Boot 项目中配置类上加上RefreshScope或者直接在字段上用NacosValue(value ${xxx}, autoRefreshed true)才能实现动态刷新。如果只是用Value改了 Nacos 里的配置客户端是不会自动变的。这个细节我见过很多次团队翻车配置改了没反应还以为是 Nacos 推送坏了其实是忘记开启自动刷新。命名空间和 Group 也是配置管理里的高频概念。简单理解Namespace 是环境隔离比如 dev、test、prod 各一个命名空间Group 是同一环境内的分组比如按业务模块区分。客户端接入时要确保 namespace、group、dataId 三者完全匹配否则拉不到配置启动直接失败。排查这类问题时我一般是先在控制台看配置是否存在于目标命名空间再比对客户端 bootstrap 配置里的命名空间 ID 是否正确。5.3 Spring Boot 接入注册中心的版本和网络要点把 Nacos 注册中心接入 Spring Boot 项目最麻烦的就是版本对应。Spring Cloud Alibaba 的版本和 Nacos Client 版本是强关联的我最近整理了一下常用对应关系Spring Cloud Alibaba 版本Nacos Client 版本Spring Boot 版本2021.0.5.02.2.02.6.x2022.0.0.02.2.13.0.x2023.0.1.02.3.23.2.x如果你的 Nacos 服务端是 2.x客户端尽量不要用 1.x不然 gRPC 相关功能没法用服务注册也可能出现各种奇怪问题。网络方面客户端所在机器和服务端之间必须能连通 8848 和 9848。有防火墙或安全组拦截常见表现是控制台上看不到服务实例注册或者服务注册后经常掉线。另外如果你的服务器有多个网卡客户端注册到 Nacos 的 IP 可能不是你想暴露给其他服务的那一个这时候需要在客户端配置里指定spring: cloud: nacos: discovery: ip: 10.0.0.5这个配置在 Docker 部署和 Kubernetes 环境里尤其重要因为容器内网 IP 和宿主机 IP 不一样服务注册的地址错了其他服务根本调不通。6. 实际问题排查实录与避坑清单6.1 启动失败和客户端注册不上的排查套路先讲启动失败。看到 Nacos 进程没起来老手的第一反应不是看控制台而是去logs/start.out翻最后几行。常见的几种错误java.net.BindException: Address already in use端口被占用检查 8848 或 9848 是不是被其他进程占了。ClassNotFoundException: com.mysql.cj.jdbc.DriverMySQL 驱动缺失去plugins/mysql目录确认驱动 jar 是否存在。Table config_info doesnt exist说明数据库建表没执行或者连接的数据库不对检查nacos-mysql.sql是否导入到正确的库。Failed to init server identity鉴权配置里的 identity key/value 没配对或者开启了鉴权但密钥是默认值。客户端注册不上的排查思路按层级来先看网络telnet 或nc -vz测试 8848 和 9848 是否可达再看服务端日志客户端注册请求如果到了服务端日志里会有对应记录最后看客户端日志重点找 Nacos 相关的 WARN 和 ERROR。这个顺序能筛掉大部分问题。6.2 未授权访问和身份认证漏洞的修复方案Nacos 控制台和管理接口如果暴露在不安全网络里很容易被扫描工具发现并利用。典型的两个问题一是nacos/v1/auth/users或nacos/v1/console/namespaces等接口未授权访问攻击者可以绕过登录直接读取或操作数据二是默认 JWT 密钥导致的认证绕过漏洞。修复思路从三个层面入手升级版本。这是最根本的办法老版本再修修补补也不如直接升到补丁版本Nacos 官方在 2.2.0.1 和 2.2.1 之后修复了大量安全问题。开启鉴权并自定义密钥。修改application.properties中的nacos.core.auth.enabledtrue同时把token.secret.key换成你自己生成的随机 Base64 字符串避免使用内置默认值。网络层限制。控制台端口和管理接口只对运维网段开放不要直接暴露到公网。云环境用安全组做白名单IDC 就用防火墙做限制这一条成本最低但效果最明显。没过多久前有个朋友的项目被扫描出 Namespaces 未授权访问我给他出的方案就是上面三条第二天就修复了。安全这种事等被网友扫描利用了才处理代价就大了。6.3 与 Consul 的选型差异经常有人问 Nacos 和 Consul 怎么选。两者的定位都是注册中心加配置中心但侧重点不同。Nacos 更贴近国内技术栈文档和社区生态好Spring Cloud Alibaba、Dubbo 集成完善控制台做配置管理非常顺手。Consul 的优势是 HashiCorp 出品一致性协议用的是 Raft在服务网格和与 Kubernetes 集成方面更成熟。我的判断标准很简单如果团队主要技术栈是 Spring Cloud 体系或者 Dubbo选 Nacos 会舒服很多配置管理、动态刷新、命名空间隔离都是开箱即用如果基础设施比较杂重视多数据中心和跨云场景Consul 也是一个稳妥选项。但只是做微服务注册发现Nacos 的学习成本明显更低而且不涉及额外付费对大多数中小团队更划算。6.4 最后一个建议把部署脚本化和版本固化文章末尾不谈宏大的架构理念只想说一点实操心得无论单机还是集群把部署步骤固化成脚本把版本号写清楚比什么都重要。我经历过好几次事故最后发现原因都是“嗯这台机器上跑的是老版本之前升级的时候漏了它”版本不一致在集群里最容易出问题。我自己现在的做法是准备一套标准化的部署脚本包含下载、解压、配置数据库、设置密钥、启动、健康检查这几个步骤。每次新环境来了直接跑既保证版本一致也减少手工操作带来的随机隐患。如果你是用 Docker 或 Rancher 部署那就把镜像版本固定住不要用 latest 标签。部署 Nacos 真不算难但把细节做到位也需要耐心。希望这篇实操分享能帮你把单机和集群路径走顺少踩几个我已经踩过的坑。