兄弟们今天聊一个动手实操的活在 Linux 上从零安装 Nacos 3.x。我前阵子刚好在一台 AlmaLinux 9 上把 Nacos 3.x 从下载到集群都过了一遍中途踩了不少坑比如解压乱码、JDK 版本不对、内存撑爆、鉴权登录死活过不去之类的。这次干脆把整个过程整理成一篇保姆级教程从环境准备到配置修改从启动验证到 systemd 托管再到常见问题排查全部按我实际操作的顺序写清楚。不管是刚接触微服务的新手还是准备给团队搭一套配置中心的老手照着做基本都能一次跑通。先说结论Nacos 3.x 和 2.x 的安装思路差别不大但有几个关键点变了比如服务端对 JDK 版本的要求、默认鉴权策略、还有一些目录和端口上的细节。如果你以前装过 2.x这次也要耐心看完不然很容易在启动阶段翻车。1. 安装前必须想清楚的几件事1.1 先弄明白 Nacos 3.x 和 2.x 有什么区别很多文章一上来就让你下载、解压、启动结果启动完发现控制台打不开或者客户端连不上最后查来查去才发现是版本特性没搞清楚。所以在动手之前我建议你先花两分钟弄清楚 3.x 到底变了什么。Nacos 3.x 是阿里巴巴在 2.x 基础上重构的一代版本我自己的体会有三点。第一服务端默认要求 JDK 17 及以上因为 3.x 构建在 Spring Boot 3 上Spring Boot 3 基于 Spring Framework 6而 Spring Framework 6 的最低要求就是 JDK 17。你要是拿 JDK 8 去跑 3.x启动时大概率会直接报UnsupportedClassVersionError根本起不来。第二鉴权默认开启而且必须配置 token secret key否则控制台虽然能开但服务会一直提示鉴权风险。第三客户端 gRPC 端口规范保持不变依然是主端口加 1000 偏移后面我会细说。除此之外3.x 在配置管理、服务发现、插件扩展这些方面都有增强。所以如果你现在是从零开始搭建我建议直接上 3.x没必要再装 2.x 了。1.2 环境清单别在第一步就翻车我这次安装用的是一台 2 核 4G 的云服务器系统是 AlmaLinux 9内核版本没太所谓CentOS 7、Ubuntu 20.04、Debian 11 这些主流发行版基本都支持。下面是完整的环境清单你可以直接照着准备组件版本要求说明操作系统CentOS 7 / Ubuntu 18.04 / Debian 10我测试用的是 AlmaLinux 9JDK17 及以上推荐 JDK 17 LTSNacos 3.x 服务端强依赖 JDK 17MySQL5.7 / 8.0生产环境建议使用单机测试可以不用Nacos3.x 最新稳定版到官网或 GitHub Releases 页面下载内存最低 2G推荐 4G默认 JVM 参数会吃掉不少内存磁盘10G 以上日志和 MySQL 数据都会膨胀另外确认两件事。一是 JDK 环境变量我建议你单独给 Nacos 配一个用户不要直接用 root 跑后面 systemd 托管也方便。二是防火墙端口Nacos 涉及 8848、9848、9849 这几个端口如果是云服务器安全组里也要放行。2. 从零开始下载并解压 Nacos2.1 下载安装包官方渠道与版本选择下载 Nacos 我比较推荐两个地方一是官网的下载页二是 GitHub 的 Releases 页面。GitHub 上会有详细的 changelog可以看到每个版本的升级说明建议优先看这里。cd /opt wget https://github.com/alibaba/nacos/releases/download/3.0.0/nacos-server-3.0.0.tar.gz如果你服务器在国内GitHub 下载速度不稳定也可以从镜像站拉或者找国内厂商的软件源。有一点我要提醒尽量下载tar.gz包别下载zip包。为啥因为 Windows 上压缩 zip 时中文文件名经常用 GBK 编码Linux 下默认用 UTF-8 解压就会出现中文乱码日志目录、脚本目录名乱七八糟看着都头疼。tar.gz 就没这个问题在 Linux 下解压最省心。下载完之后顺便检查一下文件完整性官方 Releases 页面会提供 sha512 校验值用sha512sum对一下避免下载损坏。sha512sum nacos-server-3.0.0.tar.gz2.2 解压安装包乱码问题怎么绕开如果你实在只有 zip 包或者公司内网只能传 zip那我们就正面处理乱码问题。Linux 下解压 zip 出现中文乱码的根源是编码不匹配。Windows 下常见的压缩工具默认用 GBK而 Linux 的unzip默认按 UTF-8 解压文件名里的中文字节被当成非法 UTF-8 序列就显示成乱码了。解决办法有几种。最省事的是先file nacos-server-xxx.zip看一下压缩包的编码方式然后用unzip -O参数指定编码unzip -O gbk nacos-server-3.0.0.zip -d /opt/但这里有个坑老版本的unzip不支持-O参数如果你执行的时候提示invalid option -- O要么换个支持该参数的版本要么直接下载 tar.gz 包就完事了。另外7z也有类似方案7z x -mcp936 nacos-server-3.0.0.zip我用-O gbk解压过一个包文件名正常但如果压缩时用的是 UTF-8那就要用-O UTF-8。实在不行你就用enca或者convmv事后转换文件名但那就是折腾了。我的建议是能 tar.gz 就别 zip。2.3 看懂解压后的目录结构解压完成后Nacos 目录大概长这样nacos/ ├── bin/ # 启动和停止脚本 ├── conf/ # 配置文件、SQL 初始化脚本 ├── data/ # 内置数据库的数据文件用 Derby 时才生成 ├── logs/ # 运行日志 ├── target/ # 启动时生成的应用目录一般跑起来后才有 └── LICENSE、NOTICE这几个目录里最需要注意的是conf。里面有几个关键文件我要点名application.properties核心配置文件端口、数据库、鉴权都在这改。mysql-schema.sqlMySQL 初始化脚本建库建表全靠它。cluster.conf集群模式下配置节点列表的文件单机模式默认不存在需要自己创建。bin目录下主要是startup.sh和shutdown.sh。3.x 的startup.sh支持-m standalone参数来指定单机模式-m cluster或-m缺省则按集群模式启动。3. 核心配置修改改完再启动3.1 配置 MySQL 持久化默认情况下Nacos 单机模式使用的是内嵌的 Derby 数据库好处是零配置开箱即用坏处是数据不好迁移、不好备份也不适合多人协作开发。所以我强烈建议生产环境换成 MySQL单机测试如果只是想体验功能用 Derby 倒也行。换 MySQL 分三步走。第一步在 MySQL 里创建独立的数据库。Nacos 官方脚本要求库名随意但字符集建议用utf8mb4CREATE DATABASE nacos_config CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;第二步导入官方初始化脚本。这个脚本在 Nacos 解压目录的conf/mysql-schema.sql执行命令如下mysql -uroot -p nacos_config /opt/nacos/conf/mysql-schema.sql导入完成后你可以查一下表数量正常情况下会有几十张表包括config_info、config_info_gray、his_config_info、users、roles这些。第三步修改conf/application.properties把数据源指到 MySQL。默认文件里有一段是 Derby 配置你要注释掉或者覆盖掉改成spring.datasource.platformmysql db.num1 db.url.0jdbc:mysql://127.0.0.1:3306/nacos_config?characterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue db.user.0root db.password.0你自己的密码这里有几个参数我单独解释一下。serverTimezoneAsia/Shanghai是解决 MySQL 8.x 时区报错的关键useSSLfalse是避免本机连接时出现 SSL 告警刷屏allowPublicKeyRetrievaltrue是 MySQL 8.0 为了支持 caching_sha2_password 认证方式的参数不加的话可能报Public Key Retrieval is not allowed。这三个都是我在实际使用中踩过坑后补上去的缺一不可。3.2 设置鉴权密钥和默认端口Nacos 3.x 默认开启鉴权所以你必须配置一个自定义的 token secret key否则控制台会一直提示风险而且某些版本可能直接拒绝非 localhost 的请求。官方建议的密钥长度是 Base64 编码后不少于 32 字节我这里用 OpenSSL 生成一个随机值openssl rand -base64 32然后把这串值复制到conf/application.properties里nacos.core.auth.plugin.nacos.token.secret.key你生成的这一长串Base64内容这里有个大坑网上很多老教程让你设置nacos.core.auth.enabledfalse来关闭鉴权但在 Nacos 3.x 里这种操作不安全而且后续客户端、控制台都会遇到权限问题。我建议保留默认的true只要把上面的 secret key 配置好就没问题。另外端口相关配置也在这个文件里server.port8848默认主端口是 8848一般不用改。但你要知道Nacos 2.x 开始引入了 gRPC 通信客户端和服务端之间会用server.port 1000和server.port 1001两个端口也就是 9848 和 9849所以防火墙和安全组记得一起放行不然控制台能打开客户端却连不上排查半天都不知道问题出在端口上。3.3 调整 JVM 参数防止内存爆炸Nacos 默认的 JVM 参数对 2G 内存的小机器很不友好。我那次装的时候用默认参数启动跑了不到半小时就 OOM服务直接挂掉日志里插满了java.lang.OutOfMemoryError: Java heap space。startup.sh里相关的参数集中在一个区域JVM_XMS512m JVM_XMX512m JVM_XMN256m JVM_MS32m JVM_MMS80m正常情况下JVM_XMS和JVM_XMX是同一份配置如果你机器内存紧张可以改成 256m 或者 512m如果机器有 8G、16G也可以直接拉到 1g 甚至 2g。我是这样改的JVM_XMS512m JVM_XMX512m JVM_XMN256m改完之后可以用free -h看一下当前系统内存剩余再启动 Nacos基本就能避免因为内存不够导致的崩溃。别忘了startup.sh里还有一行JAVA_HOME的自动检测如果系统里有多个 JDK建议直接把JAVA_HOME显式指到 JDK 17 的安装路径避免启动时用了错误的版本。4. 启动、验证与日志排查4.1 用 standalone 模式启动 Nacos配置改完终于到启动环节了。切到 Nacos 解压目录下的bincd /opt/nacos/bin bash startup.sh -m standalone这里我建议用bash startup.sh而不是./startup.sh因为startup.sh里有些环境变量解析在部分系统上会出问题用 bash 显式执行更稳。启动成功后终端通常会输出一段提示然后进程转入后台运行。但别高兴太早startup.sh只是把 Java 进程 fork 出去了实际是否启动成功要看日志tail -100f /opt/nacos/logs/start.out如果看到类似Nacos started successfully的日志那就说明启动成功了。4.2 验证服务状态日志、端口、控制台日志没问题不代表服务真的可用我一般还会做三层验证。第一层看进程到底有没有起来ps -ef | grep nacos第二层看端口有没有监听ss -lntp | grep 8848正常情况下你应该能看到8848、9848、9849三个端口都在 LISTEN 状态。如果 8848 有了但 9848 没有说明 gRPC 服务可能启动失败客户端是连不上的这时候要去看 start.out 日志。第三层看控制台。浏览器访问http://你的服务器IP:8848/nacos3.x 的控制台样式和 2.x 差距不大默认账号密码都是nacos/nacos首次登录系统会提示修改密码建议立刻改。4.3 第一次登录要做的三件事登录进去之后别急着创建配置先做几件收尾的事。第一改掉默认密码。Nacos 的默认密码是公开的不改密码等于门户大开。第二检查命名空间。开发、测试、生产建议用命名空间隔离不要全塞在public下。第三看一下运维页签里的集群管理。单机模式下节点列表里一般只会看到一个节点如果这里显示异常说明配置或环境有问题。5. systemd 托管让 Nacos 随系统开机自启5.1 编写 nacos.service 文件很多人启动 Nacos 就只是startup.sh一重启服务器又得手动拉起来很烦。我更推荐用 systemd 把 Nacos 管起来这样开机自启、异常自动重启、日志管理都方便。先创建一个 systemd 服务文件名字随意比如nacos.servicevi /etc/systemd/system/nacos.service内容如下[Unit] DescriptionNacos server Afternetwork.target mysql.service [Service] Typeforking Usernacos Groupnacos EnvironmentJAVA_HOME/usr/local/java/jdk-17.0.12 ExecStart/opt/nacos/bin/startup.sh -m standalone ExecStop/opt/nacos/bin/shutdown.sh Restarton-failure LimitNOFILE65535 [Install] WantedBymulti-user.target这里面有几个细节要注意。Typeforking是因为startup.sh会把 Java 进程 fork 到后台运行systemd 需要知道父进程退出后服务仍然在运行。Usernacos表示用普通用户跑别用 root。Environment里的JAVA_HOME要和你实际的 JDK 路径一致否则 systemd 可能找不到 java 命令。LimitNOFILE是调高文件描述符上限Nacos 作为注册中心连接数一多默认 1024 肯定不够用。5.2 启动服务并设置开机自启写好服务文件后依次执行systemctl daemon-reload systemctl enable nacos systemctl start nacos这里有一个常见问题如果你之前已经用startup.sh启动过一个 Nacos 实例再用 systemd 启动就会端口冲突。所以先停掉旧的bash /opt/nacos/bin/shutdown.sh然后观察 systemd 状态systemctl status nacos看到active (running)就说明托管成功了。以后服务器重启Nacos 也会自动拉起来再也不用记着手动敲启动命令了。6. 常见问题排查与避坑指南6.1 解压乱码与文件名错乱这个问题在本文开头提过再单独列一次因为它太常见了。你下载 zip 包后解压出乱码目录千万别硬着头皮继续装。我的建议永远是优先下载 tar.gz 包如果只有 zip用unzip -O gbk再不行就换 7z 的-mcp936参数。解压完成后马上检查一下conf、bin这些目录名是不是正常别等到启动脚本找不到才回头。6.2 启动报错JDK 版本、内存、端口占用启动时报错五花八门但归纳下来无非这几类。JDK 版本不对的症状是日志抛UnsupportedClassVersionError或者class file has wrong version。解决方式很直接确认java -version是 17 及以上然后在startup.sh里显式配置JAVA_HOME。端口被占用的症状是启动日志里出现Address already in use。用lsof -i:8848看是谁占了然后对应处理。我遇到过好多次要么是以前启动的 Nacos 没停干净要么是别的程序占了 8848。内存不足的症状是启动后进程还在但日志里不断出现OutOfMemoryError。按前面说的调低JVM_XMS/JVM_XMX或者给服务器加内存。6.3 鉴权登录问题与密钥配置Nacos 3.x 控制台登录报错或者提示未授权多半和 secret key 有关。如果你没配nacos.core.auth.plugin.nacos.token.secret.key启动时日志里会有告警控制台也有风险提示。这个 key 一定要用足够长的随机字符串至少 32 字节建议用openssl rand -base64 32生成。还有一点3.x 里改配置后必须重启 Nacos 才能生效不是热加载。6.4 数据库连接与 gRPC 端口问题如果你配置了 MySQL 后启动失败先看日志有没有Communications link failure或Access denied。前者通常是网络不通或 url 写错后者是账号密码不对。MySQL 8.x 如果报Public Key Retrieval is not allowed记得在 JDBC url 里加allowPublicKeyRetrievaltrue。gRPC 端口的问题是最容易忽视的。控制台能打开但微服务客户端连不上十有八九是 9848 端口没放行。因为客户端走的是 gRPC 而不是 HTTP你在安全组或防火墙里只开了 8848 没用。检查方式ss -lntp | grep 9848 firewall-cmd --list-ports # 如果是 firewalld7. 集群部署与后续维护的思路7.1 集群模式的基本玩法单机版跑通之后我建议你再花点时间了解一下集群模式。生产环境中不可能让注册中心和配置中心是单点一台挂了全链路遭殃。集群部署的大体思路是三台机器分别部署 Nacos使用同一个 MySQL 数据库或者主从然后在每台机器的conf/cluster.conf里配置节点列表。示例格式如下192.168.1.10:8848 192.168.1.11:8848 192.168.1.12:8848启动时不加-m standalone直接bash startup.sh默认就是集群模式。Nacos 3.x 内部用 Raft 类协议做节点间同步和选主某个节点挂了其他节点会自动接管。集群部署有几个细节需要提醒一是 MySQL 必须是共享的不能每台 Nacos 用各自的库否则数据各管各的失去集群意义二是节点之间需要互相通信防火墙要放行 8848、9848、9849 以及 Raft 用的 7848 端口三是集群节点数建议奇数个便于选主。7.2 升级与备份经验Nacos 升级时不要直接拿新包覆盖旧包我推荐这套操作先备份conf/application.properties和data目录如果用了 MySQL顺手备份nacos_config库然后下载新版本包解压到新目录把旧配置里的关键项迁移到新配置文件里最后先启动一个新实例验证控制台和客户端都正常再切换流量。这个流程看着繁琐但能避免很多莫名其妙的坑。尤其是 2.x 升 3.x中间如果有鉴权策略、配置格式的差异不一步步验证很容易翻车。最后再分享一点我的体会装 Nacos 本身不复杂真正花时间的是理解它为什么这么配置、为什么端口多出 1000 偏移、为什么 3.x 强制鉴权、为什么服务端要 JDK 17。我第一次装 2.x 的时候也是照着教程一路y、一路回车结果生产环境一出问题就抓瞎。后来老老实实把启动过程、日志、端口、数据库这些底层逻辑理了一遍再遇到问题就顺手多了。我的建议是先按这篇教程把单机版跑起来把控制台里服务管理、配置管理、命名空间这几个页面都点一遍再考虑上集群。循序渐进比追求一步到位靠谱得多。如果你在安装过程中遇到别的问题把logs/start.out里的报错信息贴出来基本就能定位到方向。